46.2. 基本 JAX-RS 注释

概述

RESTful Web 服务实施所需的最基本信息是:

  • 服务资源的 URI
  • 类方法如何映射到 HTTP 动词

JAX-RS 定义一组提供此基本信息的注释。所有资源类必须至少有一个注解。

设置路径

@Path 注释指定资源的 URI。该注解由 javax.ws.rs.Path 接口定义,可用于分离资源类型或资源方法。它使用字符串值作为其唯一参数。字符串值是一个 URI 模板,用于指定实现资源的位置。

URI 模板指定资源的相对位置。如 例 46.2 “URI 模板语法” 所示,模板可包含以下内容:

  • 未处理的路径组件
  • { }发布的参数标识符

    注意

    参数标识符可以包括正则表达式来更改默认路径处理。

例 46.2. URI 模板语法

@Path("resourceName/{param1}/../{paramN}")

例如,URI 模板 widget /{color}/{number} /{number} 映射到 widgets/blue/12color 参数的值分配给 蓝色number 参数的值被分配 12

URI 模板如何映射到完整的 URI 取决于 @Path 注释的内容。如果放置在根资源类上,则 URI 模板是树中所有资源的根 URI,直接附加到发布该服务的 URI。如果注解分离子资源,它将相对于 root 资源 URI。

指定 HTTP 动词

JAX-RS 使用五个注释来指定将用于方法的 HTTP 动词:

  • javax.ws.rs.DELETE 指定方法映射到 DELETE
  • javax.ws.rs.GET 指定方法映射到 GET
  • javax.ws.rs.POST 指定方法映射到 POST
  • javax.ws.rs.PUT 指定方法映射到 PUT
  • javax.ws.rs.HEAD 指定方法映射到 HEAD

当您将方法映射到 HTTP 动词时,您必须确保映射是有意义的。例如,如果您映射了旨在提交购买订单的方法,您可以将它映射到 PUTPOST。把它映射到 GETDELETE 会导致无法预计的行为。