为何UriInfo.getPathParameters()返回MultivaluedMap？

一、规范相关规定 #

JAX-RS规范（如JSR-370）允许在@Path URI模板中重复使用同一参数名称，要求实现类将每个匹配到的URI片段值按顺序存入MultivaluedMap对应参数名的列表中。

比如使用@Path("{id}/details/{id}")模板时，若请求URI为/123/details/456，getPathParameters().get("id")会返回包含"123"和"456"的列表。规范并未禁止重复参数名的使用，反而明确了这种场景下的处理逻辑。

二、产生多值的场景 #

除了你提到的单个@Path注解内重复参数名（如@Path("{foo}/bar/{foo}")），还有另一种场景：

嵌套资源类的同名路径参数 #

当父资源类和子资源类的@Path注解使用相同参数名时，请求URI匹配到的所有层级的对应值都会被收集。示例：

// 父资源类
@Path("/users/{userId}")
public class UserResource {
    @Path("/orders/{userId}")
    public OrderResource getOrderResource() {
        return new OrderResource();
    }
}

当请求/users/123/orders/456时，getPathParameters().get("userId")会返回包含"123"和"456"的列表，两个层级的参数值都会被存入映射。

除此之外，不存在其他会导致单个路径参数名对应多个值的场景。比如路径参数使用正则表达式匹配多段内容（如@Path("{id:.+}")），只会生成一个完整的匹配值，不会拆分存入多值列表。

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