JAX-RS API的@GET方法如何配置多@Path实现ID与名称分别查询

JAX-RS的路径匹配逻辑是先匹配路径模板，再执行参数类型校验，你现在的ID查询和名称查询接口的路径模板都是/{变量}，属于完全同级的模板，框架无法区分两个接口的匹配优先级，只会触发先注册的那一个，另一个永远不会被调用。

方案1：路径参数加正则约束（最适合当前场景） #

给ID接口的路径变量添加纯数字正则匹配规则，只有当路径最后一段是纯数字时才会匹配到ID查询接口，其他非数字的字符串会自动匹配名称查询接口，不需要修改其他逻辑：

@GET
// 仅匹配纯数字的路径参数
@Path("{id : \\d+}")
@Produces(MediaType.APPLICATION_JSON)
public Carta getById(@PathParam("id") int id) {
    return repositorio.getID(id);
}

注意：如果你的业务中存在名称为纯数字的Carta，这个方案会出现匹配错误，请求纯数字名称时会被误分到ID查询接口，此时用方案2。

方案2：合并接口自行做分发逻辑 #

将两个路径参数接口合并为一个，自己实现参数类型判断和逻辑分发，兼容所有场景：

@GET
@Path("{param}")
@Produces(MediaType.APPLICATION_JSON)
public Response getByParam(@PathParam("param") String param) {
    // 先尝试转整数走ID查询逻辑
    try {
        int id = Integer.parseInt(param);
        Carta carta = repositorio.getID(id);
        if (carta != null) {
            return Response.ok(carta).build();
        }
        // ID查不到可以按需选择是否fallback到名称查询
    } catch (NumberFormatException ignored) {
        // 非数字参数直接走名称查询
    }
    List<Carta> cartas = repositorio.getString(param);
    return Response.ok(cartas).build();
}

这个方案需要注意统一返回值格式，你原有两个接口分别返回单个对象和列表，要么统一返回列表，要么用Response做通用包装。

/search/byid/xx、/search/byname/xx这类细分端点是行业公认的更优实践，优势非常明确：

• 完全消除歧义：不需要依赖参数类型、正则做匹配，接口行为100%可预期，不会出现任何匹配冲突，后续业务变化也不受影响
• 扩展性极强：后续要新增按其他字段（比如稀有度、卡组分类）查询的能力，直接加对应路径即可，不需要修改现有接口逻辑，也不会影响历史调用方
• 可读性高：调用方只看路径就能明确知道接口的查询维度，不需要额外查文档确认参数规则
• 方便运维治理：不同查询接口可以单独配置限流、权限、监控告警策略，互不影响

如果不想做过细的路径拆分，也可以用查询参数的方式实现，比如GET /carta?id=xx、GET /carta?nome=xx，也是非常常见的RESTful设计方式，同样不会出现路径冲突问题。

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