Jakarta REST：GET方法空@PathParam仅无其他REST方法时生效的原因及解决

问题现象 #

在Jakarta EE 10中使用Jakarta REST API时，遇到如下问题：

• 当CustomerResource类中仅包含一个GET方法时，该方法可以正常解析空的@PathParam，处理http://example.com/resources/customer/（空参数）和http://example.com/resources/customer/5（非空参数）两种请求。
• 一旦向类中添加PUT、POST或DELETE等其他REST方法，空参数的GET请求就会抛出HTTP Status 405 - Method not allowed错误，无法正常处理。

用户初始代码如下：

@Path("/customer/")
public class CustomerResource {

    @GET @Produces("text/xml")
    @Path("{query: .*}/")
    public List<RestCustomer> getCustomer(@PathParam("query") String query) {
       // method body
    }
}

原因分析 #

1. 路径匹配歧义：你使用的{query: .*}/正则路径与类级别@Path("/customer/")的组合，在存在其他HTTP方法端点时，JAX-RS的资源匹配优先级发生变化。容器会优先尝试匹配更精确的路径，导致空参数的GET请求无法正确绑定到目标方法。
2. 斜杠重复匹配冲突：类级别和方法级别路径末尾都带有/，当添加其他方法后，容器对路径的解析逻辑出现混乱，无法识别空参数请求对应的GET方法，进而返回405错误。

解决办法 #

方案1：拆分GET方法（推荐） #

将原有的单个GET方法拆分为两个，分别处理空路径和带参数的路径，避免匹配歧义：

@Path("/customer")
public class CustomerResource {

    // 处理空路径，返回所有客户列表
    @GET @Produces("text/xml")
    public List<RestCustomer> getAllCustomers() {
       // 返回所有客户的业务逻辑
    }

    // 处理带参数的路径，返回匹配的客户列表
    @GET @Produces("text/xml")
    @Path("/{query}")
    public List<RestCustomer> getCustomer(@PathParam("query") String query) {
       // 根据参数匹配客户的业务逻辑
    }

    // 示例PUT方法
    @PUT @Produces("text/xml")
    @Path("/{id}")
    public RestCustomer updateCustomer(@PathParam("id") String id, RestCustomer customer) {
       // 更新客户的业务逻辑
    }
}

这种方式路径匹配规则清晰，无论添加多少其他方法，空路径的GET请求都能正确匹配到对应的处理方法。

方案2：调整路径正则规则 #

修改方法级别的路径注解，去掉末尾的/，同时调整正则表达式以匹配空字符串，减少匹配冲突：

@Path("/customer/")
public class CustomerResource {

    @GET @Produces("text/xml")
    @Path("{query:.*}") // 移除末尾斜杠，正则匹配任意字符（包括空）
    public List<RestCustomer> getCustomer(@PathParam("query") String query) {
       // query为空时返回所有客户，否则返回匹配项
    }

    // 示例POST方法
    @POST @Consumes("text/xml")
    @Path("/")
    public RestCustomer createCustomer(RestCustomer customer) {
       // 创建客户的业务逻辑
    }
}

方案3：使用@DefaultValue注解 #

保留原有方法结构，通过@DefaultValue为@PathParam设置默认值，确保空参数时能被正确赋值：

@Path("/customer")
public class CustomerResource {

    @GET @Produces("text/xml")
    @Path("/{query:.*}")
    public List<RestCustomer> getCustomer(@PathParam("query") @DefaultValue("") String query) {
       // 根据query参数处理业务逻辑
    }

    // 示例DELETE方法
    @DELETE
    @Path("/{id}")
    public void deleteCustomer(@PathParam("id") String id) {
       // 删除客户的业务逻辑
    }
}

内容的提问来源于stack exchange，提问作者Guillem Chesa