RESTEasy框架（依赖）的功能和常用注解 · Java入门

# RESTEasy (org.jboss.resteasy) 功能与常用注解下面通过表格形式展示 RESTEasy 依赖的主要功能和常用注解： ## 一、核心功能概览 | 功能模块 | 主要作用 | 相关依赖包 | |---------|---------|-----------| | **JAX-RS 实现** | 实现 JAX-RS 2.1/3.0 规范，提供 RESTful Web Services 支持 | resteasy-jaxrs | | **客户端 API** | 提供 REST 客户端调用功能 | resteasy-client | | **JSON 处理** | 支持 JSON-B 和 JSON-P 规范 | resteasy-json-p-provider, resteasy-json-b-provider | | **XML 处理** | 支持 JAXB、Jackson XML 等 | resteasy-jaxb-provider | | **CDI 集成** | 与 CDI 容器集成 | resteasy-cdi | | **Spring 集成** | 与 Spring 框架集成 | resteasy-spring | | **异步支持** | 支持异步请求处理 | resteasy-async | | **缓存控制** | 提供 HTTP 缓存支持 | resteasy-cache | | **拦截器** | 支持客户端和服务器端拦截器 | resteasy-client, resteasy-jaxrs | | **安全** | 集成安全认证和授权 | resteasy-undertow, resteasy-wildfly | ## 二、常用注解分类表 ### 1. JAX-RS 标准注解 | 注解 | 作用范围 | 说明 | 示例 | |------|---------|------|------| | **@Path** | 类/方法 | 定义资源路径 | `@Path("/users")` | | **@GET**, **@POST**, **@PUT**, **@DELETE**, **@PATCH** | 方法 | 指定 HTTP 方法 | `@GET @Path("/{id}")` | | **@Produces** | 类/方法 | 指定响应媒体类型 | `@Produces(MediaType.APPLICATION_JSON)` | | **@Consumes** | 类/方法 | 指定请求媒体类型 | `@Consumes(MediaType.APPLICATION_JSON)` | | **@PathParam** | 参数 | 从 URL 路径提取参数 | `@PathParam("id") Long id` | | **@QueryParam** | 参数 | 从查询字符串提取参数 | `@QueryParam("page") int page` | | **@HeaderParam** | 参数 | 从 HTTP 头部提取参数 | `@HeaderParam("Authorization") String auth` | | **@FormParam** | 参数 | 从表单数据提取参数 | `@FormParam("username") String user` | | **@CookieParam** | 参数 | 从 Cookie 提取参数 | `@CookieParam("session") String session` | | **@DefaultValue** | 参数 | 为参数提供默认值 | `@QueryParam("size") @DefaultValue("10") int size` | | **@Context** | 参数 | 注入上下文对象 | `@Context HttpServletRequest request` | ### 2. RESTEasy 扩展注解 | 注解 | 作用范围 | 说明 | 示例 | |------|---------|------|------| | **@Form** | 参数 | 批量接收表单参数 | `@Form Form form` | | **@MatrixParam** | 参数 | 从矩阵参数提取值 | `@MatrixParam("color") String color` | | **@Suspend** | 方法 | 异步响应支持（旧版本） | `@Suspend(10000)` | | **@Asynchronous** | 方法 | 标记方法为异步执行 | `@Asynchronous` | | **@Cache** | 类/方法 | 控制 HTTP 缓存 | `@Cache(maxAge=3600)` | | **@NoCache** | 类/方法 | 禁用缓存 | `@NoCache` | | **@PreMatching** | 过滤器 | 在请求匹配前执行过滤器 | `@PreMatching` | | **@Cookie** | 参数 | 注入 Cookie 对象 | `@Cookie Cookie sessionCookie` | | **@LinkHeader** | 参数/方法 | 处理 Link 头部 | `@LinkHeader Link link` | ### 3. 参数处理注解 | 注解 | 作用范围 | 说明 | 示例 | |------|---------|------|------| | **@Encoded** | 参数/方法 | 禁止自动解码 | `@QueryParam("q") @Encoded String query` | | **@BeanParam** | 参数 | 将多个参数封装为 Bean | `@BeanParam UserFilter filter` | | **@RestForm** | 参数 | RESTEasy 的表单参数 | `@RestForm String username` | | **@MultipartForm** | 参数 | 处理 multipart/form-data | `@MultipartForm FileUpload form` | ### 4. 异步和响应处理 | 注解 | 作用范围 | 说明 | 示例 | |------|---------|------|------| | **@Suspended** | 参数 | 异步响应支持（JAX-RS 2.0+） | `@Suspended AsyncResponse response` | | **@Blocking** | 方法 | 显式标记为阻塞操作 | `@Blocking` | | **@NonBlocking** | 方法 | 显式标记为非阻塞操作 | `@NonBlocking` | ### 5. 安全相关注解 | 注解 | 作用范围 | 说明 | 示例 | |------|---------|------|------| | **@RolesAllowed** | 类/方法 | 指定允许的角色 | `@RolesAllowed({"admin", "user"})` | | **@PermitAll** | 类/方法 | 允许所有用户访问 | `@PermitAll` | | **@DenyAll** | 类/方法 | 拒绝所有用户访问 | `@DenyAll` | ## 三、Maven 依赖示例 ```xml  <dependency> <groupId>org.jboss.resteasy</groupId> <artifactId>resteasy-jaxrs</artifactId> <version>4.7.4.Final</version> </dependency>  <dependency> <groupId>org.jboss.resteasy</groupId> <artifactId>resteasy-json-binding-provider</artifactId> <version>4.7.4.Final</version> </dependency>  <dependency> <groupId>org.jboss.resteasy</groupId> <artifactId>resteasy-client</artifactId> <version>4.7.4.Final</version> </dependency>  <dependency> <groupId>org.jboss.resteasy</groupId> <artifactId>resteasy-spring-boot-starter</artifactId> <version>4.7.4.Final</version> </dependency> ``` ## 四、使用示例 ```java // 资源类示例 @Path("/api/users") @Produces(MediaType.APPLICATION_JSON) @Consumes(MediaType.APPLICATION_JSON) public class UserResource { @GET @Path("/{id}") public Response getUser(@PathParam("id") Long id, @QueryParam("details") @DefaultValue("false") boolean details) { // 实现逻辑 return Response.ok(user).build(); } @POST @RolesAllowed("admin") public Response createUser(@Valid User user, @Context UriInfo uriInfo) { // 创建用户 URI location = uriInfo.getAbsolutePathBuilder().path(id.toString()).build(); return Response.created(location).entity(user).build(); } @PUT @Path("/{id}") public Response updateUser(@PathParam("id") Long id, @BeanParam UserUpdateParams params) { // 更新用户 return Response.ok(updatedUser).build(); } @DELETE @Path("/{id}") @RolesAllowed("admin") public Response deleteUser(@PathParam("id") Long id) { // 删除用户 return Response.noContent().build(); } } // BeanParam 示例 public class UserUpdateParams { @FormParam("name") private String name; @FormParam("email") private String email; @HeaderParam("X-Request-ID") private String requestId; // getters and setters } ``` ## 五、注意事项 1. **版本兼容性**：RESTEasy 4.x 支持 JAX-RS 2.1/3.0，而 3.x 支持 JAX-RS 2.0 2. **容器集成**：根据部署环境（WildFly、Tomcat、Spring Boot 等）选择相应的依赖 3. **异步处理**：在 Servlet 3.0+ 容器中支持异步处理 4. **CDI 整合**：在支持 CDI 的环境中，RESTEasy 资源会自动成为 CDI bean 这个表格汇总了 RESTEasy 的主要功能和常用注解，实际使用时需要根据具体版本和需求选择合适的依赖和注解。