Quarkus REST API 指南
在 Quarkus 上使用 Jakarta REST（JAX-RS）应用 REST API 设计原则。
用途
该技能面向需要在 Quarkus 项目中设计、审查或改进 REST API 的场景，帮助按统一规则实现或重构 JAX-RS 资源与异常映射，使接口在方法映射、状态码、错误格式、版本化、并发与缓存等方面保持一致。
主要能力
覆盖内容包括：资源类、@Path、HTTP 方法映射和资源 URI 设计；状态码、Location 头和 Response 构建；边界处的 DTO 与 Bean Validation，日期/时间字段使用 ISO-8601；ExceptionMapper 用于生成一致的错误 JSON（RFC 7807 Problem Details）；API 版本化策略（URI 路径、Accept 头）；使用 Idempotency-Key 头实现幂等；乐观并发控制：ETag、If-Match、If-None-Match；使用 Cache-Control 头进行 HTTP 缓存；API 弃用：Sunset 和 Deprecation 头；分页、排序和过滤查询参数；可选的通过 SmallRye 提供 /openapi；在 openapi.yaml 中维护 API-first 契约（代码生成）；响应式与阻塞的考量、@RunOnVirtualThread；在过滤器层进行安全集成。
使用方式
范围：根据参考规则和好/坏代码示例应用建议。
约束：
- 在应用 REST 更改之前，确保项目可以编译。应用改进后，运行完整验证。
- 必须：在应用任何更改之前运行 ./mvnw compile 或 mvn compile
- 前提条件：项目必须在应用 REST API 改进之前可以编译
- 安全：如果编译失败，立即停止
- 阻塞条件：编译错误必须由用户解决后才能继续
- 验证：在应用改进后运行 ./mvnw clean verify 或 mvn clean verify
- 应用之前：阅读参考以了解详细规则和示例
工作流：
- 阅读参考并评估项目上下文：阅读 references/402-frameworks-quarkus-rest.md，并在提出更改前检查当前项目设置。
- 收集范围并确定目标改进：识别请求的结果、约束以及要应用的最小安全更改集。
- 应用与框架一致的更改：按照参考模式和项目约定实现或重构配置/代码。
- 运行验证并报告结果：执行适当的构建/测试，并总结更改了什么、验证了什么以及任何后续操作。
参考：有关详细指导、示例和约束，请参阅 references/402-frameworks-quarkus-rest.md。
何时使用此技能
- 审查或改进 Quarkus 项目中的 JAX-RS 资源
- 在 Quarkus 上设计具有验证和错误处理的 HTTP API
- 添加 API 版本化、幂等、ETag 并发或弃用头
- 实现分页、排序或 RFC 7807 Problem Details 错误响应
- 改进 Quarkus REST 资源和异常映射器
适用场景
适用于使用 Quarkus 与 Jakarta REST 构建或维护 HTTP API 的后端开发工作，尤其是需要统一错误响应格式、引入版本化与弃用策略、处理并发与缓存、规范参数查询或引入 API-first 契约的项目。
限制
应用更改前项目必须能够编译；若编译失败须立即停止，由用户解决编译错误后方可继续。应用改进后需运行完整验证。详细规则与示例见 references/402-frameworks-quarkus-rest.md。资料未提供关于收费、价格、平台支持范围或实际效果的信息。