Back to Details

502-frameworks-micronaut-rest

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Micronaut REST API Guidelines

Micronaut REST API 指南

Apply REST design principles for Micronaut HTTP applications.
What is covered in this Skill?
  • Semantic HTTP with @Get/@Post/@Put/@Patch/@Delete and HttpResponse status control
  • Resource-oriented paths and stable DTO contracts
  • @Valid on request bodies with Bean Validation
  • Centralized error mapping (ExceptionHandler / problem JSON when applicable)
  • Pagination with Pageable and bounded sizes
  • OpenAPI annotations (@Operation, @Tag)
  • Security annotations (@Secured) on sensitive routes
  • Idempotency-Key for retried writes
  • ETag / If-Match for optimistic concurrency
  • Cache-Control discipline
  • API versioning patterns
  • ISO-8601 time types in DTOs
Scope: Apply recommendations based on the reference rules and good/bad code examples.
为Micronaut HTTP应用应用REST设计原则。
本Skill涵盖哪些内容？
  • 结合@Get/@Post/@Put/@Patch/@Delete的语义化HTTP与HttpResponse状态控制
  • 面向资源的路径与稳定的DTO契约
  • 对请求体使用@Valid进行Bean Validation验证
  • 集中式错误映射（适用时使用ExceptionHandler / problem JSON）
  • 基于Pageable的分页与大小限制
  • OpenAPI注解（@Operation、@Tag）
  • 敏感路由上的安全注解（@Secured）
  • 用于重试写入的Idempotency-Key
  • 用于乐观并发的ETag / If-Match
  • Cache-Control规范
  • API版本控制模式
  • DTO中的ISO-8601时间类型
适用范围： 基于参考规则和代码示例（优/劣）应用建议。

Constraints

约束条件

Compile before REST refactors; verify after.
  • MANDATORY: Run 
    ./mvnw compile
    or 
    mvn compile
    before applying any change
  • SAFETY: If compilation fails, stop immediately
  • VERIFY: Run 
    ./mvnw clean verify
    or 
    mvn clean verify
    after applying improvements
  • BEFORE APPLYING: Read the reference for detailed rules and examples
在重构REST API前先编译；重构后进行验证。
  • 强制要求：在进行任何修改前运行
    ./mvnw compile
    或
    mvn compile
  • 安全提示：如果编译失败，立即停止操作
  • 验证：在完成改进后运行
    ./mvnw clean verify
    或
    mvn clean verify
  • 应用前须知：阅读参考文档以了解详细规则和示例

When to use this skill

何时使用本Skill

  • Review or improve Micronaut @Controller REST APIs
  • Add validation, error handling, or OpenAPI documentation to Micronaut HTTP layer
  • 评审或改进Micronaut @Controller REST API
  • 为Micronaut HTTP层添加验证、错误处理或OpenAPI文档

Reference

参考资料

For detailed guidance, examples, and constraints, see references/502-frameworks-micronaut-rest.md.
如需详细指导、示例和约束条件，请参阅references/502-frameworks-micronaut-rest.md。