JAX-RS 3.0 规范要求 @PathParam、@QueryParam、@MatrixParam 解析异常时抛出 NotFoundException（HTTP 404），而 @HeaderParam/@CookieParam 异常则返回 BadRequestException（HTTP 400），其核心在于语义区分：URI 不匹配代表“资源不可达”，而非“请求格式错误”。
jax-rs 3.0 规范要求 `@pathparam`、`@queryparam`、`@matrixparam` 解析异常时抛出 `notfoundexception`（http 404），而 `@headerparam`/`@cookieparam` 异常则返回 `badrequestexception`（http 400），其核心在于语义区分：uri 不匹配代表“资源不可达”，而非“请求格式错误”。
在 RESTful 设计中，HTTP 状态码不仅用于指示错误，更承载着明确的语义契约。JAX-RS 将参数解析阶段的异常按参数所属的 URI 定位层级进行语义归类：
URI 路径级参数（@PathParam, @QueryParam, @MatrixParam）：这些参数共同构成资源的唯一标识。例如，GET /users/123?role=admin 中，123 是路径参数，role=admin 是查询参数。若 123 无法转换为 Long 类型，或 role 值违反枚举约束，JAX-RS 认为——该请求根本未指向一个有效的资源端点。此时，服务器甚至无法完成资源方法匹配（resource method dispatch），本质上等同于客户端访问了不存在的 URI（如 /users/abc），因此规范强制返回 404 Not Found，强调“资源不可寻址”。
元数据级参数（@HeaderParam, @CookieParam）：它们不参与资源定位，仅提供上下文信息（如认证令牌、语言偏好）。即使 Authorization: Bearer invalid-token 解析失败，URI /api/orders 本身仍是合法且可路由的——服务器能准确识别目标资源，只是请求附带的元数据有误。因此，规范要求抛出 BadRequestException（400），表示“请求语义有缺陷”，而非“资源不存在”。
这种设计并非违背直觉，而是严格遵循 HTTP 语义分层：
@Path("/products")
public class ProductResource {
// ✅ 404：/products/abc → 无法将 "abc" 转为 Long，资源路径无效
@GET
@Path("/{id}")
public Response getProduct(@PathParam("id") Long id) { ... }
// ✅ 400：Header "X-Client-ID: xyz" 无法转为 UUID，但 /products 资源存在
@GET
public Response listProducts(@HeaderParam("X-Client-ID") UUID clientId) { ... }
}
⚠️ 注意事项：
- 开发者不应手动对 @PathParam 异常捕获后改为 400，否则破坏 REST 语义一致性；
- 若业务需统一返回 400，应在参数校验层（如 Bean Validation）提前拦截，而非依赖运行时转换异常；
- 自定义 ExceptionMapper 可覆盖默认行为，但需谨慎权衡 API 合规性与客户端兼容性。
综上，JAX-RS 的这一设计是将“资源可达性”（404）与“请求合规性”（400）解耦的体现——它迫使开发者正视 URI 作为资源地址的核心地位，确保状态码真实反映服务端的路由决策结果，而非仅作为通用错误容器。
