Back to Details

402-frameworks-quarkus-rest

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Quarkus REST API Guidelines

Quarkus REST API 指南

Apply REST API design principles on Quarkus using Jakarta REST (JAX-RS).
What is covered in this Skill?
  • Resource classes, @Path, HTTP method mapping, and resource URI design
  • Status codes, Location headers, and Response building
  • DTOs and Bean Validation at the boundary; ISO-8601 for date/time fields
  • ExceptionMapper for consistent error JSON (RFC 7807 Problem Details)
  • API versioning strategies (URI path, Accept header)
  • Idempotency with Idempotency-Key header
  • Optimistic concurrency: ETag, If-Match, If-None-Match
  • HTTP caching with Cache-Control headers
  • API deprecation: Sunset and Deprecation headers
  • Pagination, sorting, and filtering query parameters
  • OpenAPI documentation with SmallRye (MicroProfile OpenAPI)
  • Reactive vs blocking considerations; @RunOnVirtualThread
  • Security integration at the filter layer
Scope: Apply recommendations based on the reference rules and good/bad code examples.
在Quarkus上使用Jakarta REST（JAX-RS）应用REST API设计原则。
本Skill涵盖哪些内容？
  • 资源类、@Path、HTTP方法映射及资源URI设计
  • 状态码、Location标头与Response构建
  • 边界处的DTO与Bean Validation；日期/时间字段的ISO-8601规范
  • 用于生成一致错误JSON的ExceptionMapper（遵循RFC 7807问题详情）
  • API版本控制策略（URI路径、Accept标头）
  • 基于Idempotency-Key标头的幂等性实现
  • 乐观并发：ETag、If-Match、If-None-Match
  • 基于Cache-Control标头的HTTP缓存
  • API弃用：Sunset与Deprecation标头
  • 分页、排序与过滤查询参数
  • 基于SmallRye的OpenAPI文档（MicroProfile OpenAPI）
  • 响应式与阻塞式考量；@RunOnVirtualThread
  • 过滤器层的安全集成
适用范围： 基于参考规则与代码示例（好/坏案例）应用建议。

Constraints

约束条件

Before applying REST changes, ensure the project compiles. After applying improvements, run full verification.
  • MANDATORY: Run 
    ./mvnw compile
    or 
    mvn compile
    before applying any change
  • PREREQUISITE: Project must compile before applying REST API improvements
  • SAFETY: If compilation fails, stop immediately
  • BLOCKING CONDITION: Compilation errors must be resolved by the user before proceeding
  • VERIFY: Run 
    ./mvnw clean verify
    or 
    mvn clean verify
    after applying improvements
  • BEFORE APPLYING: Read the reference for detailed rules and examples
在应用REST相关更改前，确保项目可以编译。在应用改进后，执行完整验证。
  • 强制要求：在应用任何更改前运行
    ./mvnw compile
    或
    mvn compile
  • 先决条件：项目必须能编译才能应用REST API改进
  • 安全要求：如果编译失败，立即停止操作
  • 阻塞条件：用户必须先解决编译错误才能继续
  • 验证步骤：应用改进后运行
    ./mvnw clean verify
    或
    mvn clean verify
  • 应用前准备：阅读参考文档获取详细规则与示例

When to use this skill

何时使用本Skill

  • Review or improve JAX-RS resources in a Quarkus project
  • Design HTTP APIs with validation and error handling on Quarkus
  • Add API versioning, idempotency, ETag concurrency, or deprecation headers
  • Implement pagination, sorting, or RFC 7807 Problem Details error responses
  • 评审或改进Quarkus项目中的JAX-RS资源
  • 在Quarkus上设计带有验证与错误处理的HTTP API
  • 添加API版本控制、幂等性、ETag并发或弃用标头
  • 实现分页、排序或遵循RFC 7807问题详情的错误响应

Reference

参考资料

For detailed guidance, examples, and constraints, see references/402-frameworks-quarkus-rest.md.
如需详细指南、示例与约束条件，请查看references/402-frameworks-quarkus-rest.md。