Java Jersey 实战指南：用 JAX-RS 注解写清晰的 REST API

简介

Jersey 是 Jakarta RESTful Web Services 规范的一种实现。

老名字常叫 JAX-RS，新包名是：

1jakarta.ws.rs
2

Jersey 自己的核心包名通常是：

1org.glassfish.jersey
2

简单理解：

1Jakarta REST / JAX-RS 是规范
2Jersey 是实现
3Spring Boot 提供 Jersey 自动配置和 starter
4

Jersey 的开发方式是用注解把 Java 类声明成 HTTP 资源：

1@Path("/users")
2public class UserResource {
3
4    @GET
5    @Path("/{id}")
6    public UserView getById(@PathParam("id") Long id) {
7        return userService.getById(id);
8    }
9}
10

这种写法和 Spring MVC 的 Controller 很像，只是注解来自 Jakarta REST 规范。

Jersey 适合什么场景

Java 写 REST API 常见有几种方式：

Jersey 适合这些场景：

• 已经在使用 JAX-RS / Jakarta REST 注解的项目
• 传统 Java EE / Jakarta EE 项目
• 需要兼容标准 REST 资源模型的服务
• Spring Boot 项目里更偏好 JAX-RS 编程模型
• 需要 Jersey Client、Filter、ExceptionMapper 等能力的项目

如果项目已经深度使用 Spring MVC，继续用 Spring MVC 通常更顺。

如果团队习惯 @Path、@GET、@Produces 这套标准注解，Jersey 会更自然。

Jersey、JAX-RS、Jakarta REST 的关系

这些名字容易混。

Spring Boot 3 相关项目里通常使用：

1import jakarta.ws.rs.GET;
2import jakarta.ws.rs.Path;
3import jakarta.ws.rs.Produces;
4

老项目里可能会看到：

1import javax.ws.rs.GET;
2import javax.ws.rs.Path;
3

迁移到 Spring Boot 3 或 Jakarta EE 新版本时，包名变化是主要改动之一。

Jersey 和 Spring MVC 对比

同一个用户查询接口，用 Spring MVC 可能这样写：

1@RestController
2@RequestMapping("/users")
3public class UserController {
4
5    @GetMapping("/{id}")
6    public UserView getById(@PathVariable Long id) {
7        return userService.getById(id);
8    }
9}
10

Jersey 写法：

1@Path("/users")
2public class UserResource {
3
4    @GET
5    @Path("/{id}")
6    public UserView getById(@PathParam("id") Long id) {
7        return userService.getById(id);
8    }
9}
10

对比：

两者都能写 REST API。

区别不在“能不能写”，而在项目选择的编程模型和生态集成方式。

Spring Boot 集成 Jersey

Spring Boot 项目里使用 Jersey，直接引入 starter。

1<dependency>
2    <groupId>org.springframework.boot</groupId>
3    <artifactId>spring-boot-starter-jersey</artifactId>
4</dependency>
5

如果需要参数校验：

1<dependency>
2    <groupId>org.springframework.boot</groupId>
3    <artifactId>spring-boot-starter-validation</artifactId>
4</dependency>
5

Spring Boot 会为 Jersey 做自动配置。

还需要提供一个 ResourceConfig Bean，用来注册资源类、过滤器、异常映射器等组件。

ResourceConfig 配置

1package com.example.jersey.config;
2
3import com.example.jersey.exception.ApiExceptionMapper;
4import com.example.jersey.exception.ConstraintViolationMapper;
5import com.example.jersey.filter.RequestLogFilter;
6import com.example.jersey.resource.UserResource;
7import org.glassfish.jersey.server.ResourceConfig;
8import org.springframework.stereotype.Component;
9
10@Component
11public class JerseyConfig extends ResourceConfig {
12
13    public JerseyConfig() {
14        register(UserResource.class);
15        register(ApiExceptionMapper.class);
16        register(ConstraintViolationMapper.class);
17        register(RequestLogFilter.class);
18    }
19}
20

Spring Boot 官方文档建议在可执行 jar 场景里显式 register(...) 端点。

原因是 Jersey 对可执行 jar 的包扫描支持有限，显式注册更稳定。

如果要给 Jersey 统一加路径前缀，可以在 ResourceConfig 上加 @ApplicationPath：

1package com.example.jersey.config;
2
3import com.example.jersey.resource.UserResource;
4import jakarta.ws.rs.ApplicationPath;
5import org.glassfish.jersey.server.ResourceConfig;
6import org.springframework.stereotype.Component;
7
8@Component
9@ApplicationPath("/api")
10public class JerseyConfig extends ResourceConfig {
11
12    public JerseyConfig() {
13        register(UserResource.class);
14    }
15}
16

这样 @Path("/users") 最终访问路径就是：

1/api/users
2

第一个 Resource

1package com.example.jersey.resource;
2
3import jakarta.ws.rs.GET;
4import jakarta.ws.rs.Path;
5import jakarta.ws.rs.Produces;
6import jakarta.ws.rs.core.MediaType;
7import org.springframework.stereotype.Component;
8
9@Component
10@Path("/hello")
11public class HelloResource {
12
13    @GET
14    @Produces(MediaType.TEXT_PLAIN)
15    public String hello() {
16        return "Hello Jersey";
17    }
18}
19

注册：

1register(HelloResource.class);
2

访问：

1GET http://localhost:8080/api/hello
2

如果 Resource 类加了 @Component，它可以交给 Spring 管理，也可以注入 Spring Bean。

用户 CRUD Demo

下面用一个用户接口串起常用注解。

请求对象：

1package com.example.jersey.user;
2
3import jakarta.validation.constraints.Email;
4import jakarta.validation.constraints.NotBlank;
5import jakarta.validation.constraints.NotNull;
6import jakarta.validation.constraints.Size;
7
8public record CreateUserRequest(
9
10        @NotBlank(message = "用户名不能为空")
11        @Size(min = 2, max = 20, message = "用户名长度需要在2到20之间")
12        String username,
13
14        @NotBlank(message = "邮箱不能为空")
15        @Email(message = "邮箱格式不正确")
16        String email,
17
18        @NotNull(message = "年龄不能为空")
19        Integer age
20) {
21}
22

响应对象：

1package com.example.jersey.user;
2
3public record UserView(
4        Long id,
5        String username,
6        String email,
7        Integer age
8) {
9}
10

业务服务：

1package com.example.jersey.user;
2
3import org.springframework.stereotype.Service;
4
5import java.util.ArrayList;
6import java.util.List;
7import java.util.Map;
8import java.util.concurrent.ConcurrentHashMap;
9import java.util.concurrent.atomic.AtomicLong;
10
11@Service
12public class UserService {
13
14    private final AtomicLong idGenerator = new AtomicLong(1000);
15
16    private final Map<Long, UserView> users = new ConcurrentHashMap<>();
17
18    public List<UserView> findAll(String keyword) {
19        return new ArrayList<>(users.values())
20                .stream()
21                .filter(user -> keyword == null || user.username().contains(keyword))
22                .toList();
23    }
24
25    public UserView findById(Long id) {
26        UserView user = users.get(id);
27        if (user == null) {
28            throw new ApiException(404, "用户不存在");
29        }
30        return user;
31    }
32
33    public UserView create(CreateUserRequest request) {
34        Long id = idGenerator.incrementAndGet();
35        UserView user = new UserView(id, request.username(), request.email(), request.age());
36        users.put(id, user);
37        return user;
38    }
39
40    public void delete(Long id) {
41        users.remove(id);
42    }
43}
44

Resource：

1package com.example.jersey.resource;
2
3import com.example.jersey.user.CreateUserRequest;
4import com.example.jersey.user.UserService;
5import com.example.jersey.user.UserView;
6import jakarta.validation.Valid;
7import jakarta.ws.rs.Consumes;
8import jakarta.ws.rs.DELETE;
9import jakarta.ws.rs.GET;
10import jakarta.ws.rs.POST;
11import jakarta.ws.rs.Path;
12import jakarta.ws.rs.PathParam;
13import jakarta.ws.rs.Produces;
14import jakarta.ws.rs.QueryParam;
15import jakarta.ws.rs.core.MediaType;
16import jakarta.ws.rs.core.Response;
17import org.springframework.stereotype.Component;
18
19import java.net.URI;
20import java.util.List;
21
22@Component
23@Path("/users")
24@Produces(MediaType.APPLICATION_JSON)
25@Consumes(MediaType.APPLICATION_JSON)
26public class UserResource {
27
28    private final UserService userService;
29
30    public UserResource(UserService userService) {
31        this.userService = userService;
32    }
33
34    @GET
35    public List<UserView> list(@QueryParam("keyword") String keyword) {
36        return userService.findAll(keyword);
37    }
38
39    @GET
40    @Path("/{id}")
41    public UserView getById(@PathParam("id") Long id) {
42        return userService.findById(id);
43    }
44
45    @POST
46    public Response create(@Valid CreateUserRequest request) {
47        UserView user = userService.create(request);
48        return Response.created(URI.create("/api/users/" + user.id()))
49                .entity(user)
50                .build();
51    }
52
53    @DELETE
54    @Path("/{id}")
55    public Response delete(@PathParam("id") Long id) {
56        userService.delete(id);
57        return Response.noContent().build();
58    }
59}
60

接口效果：

POST 请求示例：

1{
2  "username": "tom",
3  "email": "tom@example.com",
4  "age": 20
5}
6

常用注解

Jersey 主要使用 Jakarta REST 注解。

@Produces 和 @Consumes 可以放在类上，也可以放在方法上。

方法上的配置优先级更高。

参数绑定

路径参数：

1@GET
2@Path("/{id}")
3public UserView getById(@PathParam("id") Long id) {
4    return userService.findById(id);
5}
6

查询参数：

1@GET
2public List<UserView> list(@QueryParam("keyword") String keyword,
3                           @QueryParam("page") @DefaultValue("1") Integer page) {
4    return userService.findAll(keyword);
5}
6

请求头：

1@GET
2@Path("/profile")
3public UserView profile(@HeaderParam("X-User-Id") Long userId) {
4    return userService.findById(userId);
5}
6

表单参数：

1@POST
2@Path("/login")
3@Consumes(MediaType.APPLICATION_FORM_URLENCODED)
4public Response login(@FormParam("username") String username,
5                      @FormParam("password") String password) {
6    return Response.ok().build();
7}
8

上下文对象：

1@GET
2@Path("/request-info")
3public String requestInfo(@Context jakarta.ws.rs.core.UriInfo uriInfo) {
4    return uriInfo.getRequestUri().toString();
5}
6

BeanParam：封装查询条件

查询条件比较多时，可以用 @BeanParam。

1package com.example.jersey.user;
2
3import jakarta.ws.rs.DefaultValue;
4import jakarta.ws.rs.QueryParam;
5
6public class UserQueryParam {
7
8    @QueryParam("keyword")
9    private String keyword;
10
11    @QueryParam("page")
12    @DefaultValue("1")
13    private Integer page;
14
15    @QueryParam("size")
16    @DefaultValue("20")
17    private Integer size;
18
19    public String getKeyword() {
20        return keyword;
21    }
22
23    public Integer getPage() {
24        return page;
25    }
26
27    public Integer getSize() {
28        return size;
29    }
30}
31

Resource：

1@GET
2@Path("/search")
3public List<UserView> search(@BeanParam UserQueryParam queryParam) {
4    return userService.findAll(queryParam.getKeyword());
5}
6

这种写法适合列表查询、分页查询、筛选条件较多的接口。

Response：控制状态码和响应头

直接返回对象时，Jersey 会自动序列化。

需要精细控制状态码、响应头时，可以返回 Response。

创建成功：

1return Response.created(URI.create("/api/users/" + user.id()))
2        .entity(user)
3        .build();
4

无内容：

1return Response.noContent().build();
2

自定义响应头：

1return Response.ok(user)
2        .header("X-Request-Source", "jersey")
3        .build();
4

常见状态码：

异常处理：ExceptionMapper

Jersey 用 ExceptionMapper 统一处理异常。

先定义业务异常：

1package com.example.jersey.user;
2
3public class ApiException extends RuntimeException {
4
5    private final int status;
6
7    public ApiException(int status, String message) {
8        super(message);
9        this.status = status;
10    }
11
12    public int getStatus() {
13        return status;
14    }
15}
16

错误响应：

1package com.example.jersey.exception;
2
3public record ApiErrorResponse(
4        String code,
5        String message
6) {
7}
8

异常映射器：

1package com.example.jersey.exception;
2
3import com.example.jersey.user.ApiException;
4import jakarta.ws.rs.ext.ExceptionMapper;
5import jakarta.ws.rs.ext.Provider;
6import jakarta.ws.rs.core.MediaType;
7import jakarta.ws.rs.core.Response;
8
9@Provider
10public class ApiExceptionMapper implements ExceptionMapper<ApiException> {
11
12    @Override
13    public Response toResponse(ApiException exception) {
14        ApiErrorResponse body = new ApiErrorResponse(
15                "BUSINESS_ERROR",
16                exception.getMessage()
17        );
18
19        return Response.status(exception.getStatus())
20                .type(MediaType.APPLICATION_JSON)
21                .entity(body)
22                .build();
23    }
24}
25

注册：

1register(ApiExceptionMapper.class);
2

这样 Resource 里可以直接抛业务异常，统一由 Mapper 转成 JSON 响应。

参数校验

Jersey 可以结合 Jakarta Validation。

请求对象上写约束：

1public record CreateUserRequest(
2
3        @NotBlank(message = "用户名不能为空")
4        String username,
5
6        @Email(message = "邮箱格式不正确")
7        String email
8) {
9}
10

Resource 参数上加 @Valid：

1@POST
2public Response create(@Valid CreateUserRequest request) {
3    UserView user = userService.create(request);
4    return Response.ok(user).build();
5}
6

校验异常也可以通过 ExceptionMapper 统一处理。

1package com.example.jersey.exception;
2
3import jakarta.validation.ConstraintViolation;
4import jakarta.validation.ConstraintViolationException;
5import jakarta.ws.rs.core.Response;
6import jakarta.ws.rs.ext.ExceptionMapper;
7import jakarta.ws.rs.ext.Provider;
8
9import java.util.List;
10
11@Provider
12public class ConstraintViolationMapper implements ExceptionMapper<ConstraintViolationException> {
13
14    @Override
15    public Response toResponse(ConstraintViolationException exception) {
16        List<String> errors = exception.getConstraintViolations()
17                .stream()
18                .map(ConstraintViolation::getMessage)
19                .toList();
20
21        return Response.status(Response.Status.BAD_REQUEST)
22                .entity(errors)
23                .build();
24    }
25}
26

Filter：请求日志和鉴权入口

Jersey 里常用过滤器处理请求日志、鉴权、TraceId 等逻辑。

1package com.example.jersey.filter;
2
3import jakarta.ws.rs.container.ContainerRequestContext;
4import jakarta.ws.rs.container.ContainerRequestFilter;
5import jakarta.ws.rs.ext.Provider;
6
7import java.io.IOException;
8
9@Provider
10public class RequestLogFilter implements ContainerRequestFilter {
11
12    @Override
13    public void filter(ContainerRequestContext requestContext) throws IOException {
14        System.out.printf(
15                "Jersey 请求：%s %s%n",
16                requestContext.getMethod(),
17                requestContext.getUriInfo().getPath()
18        );
19    }
20}
21

注册：

1register(RequestLogFilter.class);
2

简单鉴权示例：

1package com.example.jersey.filter;
2
3import jakarta.ws.rs.container.ContainerRequestContext;
4import jakarta.ws.rs.container.ContainerRequestFilter;
5import jakarta.ws.rs.core.Response;
6import jakarta.ws.rs.ext.Provider;
7
8import java.io.IOException;
9
10@Provider
11public class TokenAuthFilter implements ContainerRequestFilter {
12
13    @Override
14    public void filter(ContainerRequestContext requestContext) throws IOException {
15        String token = requestContext.getHeaderString("Authorization");
16        if (token == null || token.isBlank()) {
17            requestContext.abortWith(
18                    Response.status(Response.Status.UNAUTHORIZED)
19                            .entity("未登录")
20                            .build()
21            );
22        }
23    }
24}
25

复杂安全逻辑更适合交给 Spring Security 或网关统一处理。

Jersey Client

Jersey 不只可以写服务端，也提供 Client API 调用 HTTP 服务。

Maven 依赖：

1<dependency>
2    <groupId>org.glassfish.jersey.core</groupId>
3    <artifactId>jersey-client</artifactId>
4    <version>${jersey.version}</version>
5</dependency>
6
7<dependency>
8    <groupId>org.glassfish.jersey.media</groupId>
9    <artifactId>jersey-media-json-jackson</artifactId>
10    <version>${jersey.version}</version>
11</dependency>
12