Back to Details

302-frameworks-spring-boot-rest

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Java REST API Design Principles

Java REST API设计原则

Apply REST API design principles for Spring Boot applications.
What is covered in this Skill?
  • HTTP methods (GET, POST, PUT, PATCH, DELETE) — semantic consistency
  • Resource URI design
  • HTTP status codes
  • Request/response DTOs with lean contracts
  • API versioning (URI, header, or media type — applied consistently)
  • Bean Validation at the boundary (@Valid/@Validated on controller inputs, 400 on failure)
  • Pagination, sorting, and filtering (Page/Pageable with caps)
  • ISO-8601 instants with offset (OffsetDateTime, Instant) in JSON contracts
  • Content negotiation (JSON default; vendor media types when meaningful)
  • Idempotency-Key support for POST creates; 409 Conflict for collisions
  • ETag concurrency with If-Match/If-None-Match; 412 Precondition Failed / 304 Not Modified
  • HTTP caching discipline (Cache-Control, ETag, Last-Modified)
  • Deprecation and sunset headers (Deprecation, Sunset, Link rel="successor-version")
  • Error handling
  • API security (TLS, authentication, authorization, input validation)
  • Documentation (OpenAPI)
  • Controller advice and problem details (RFC 7807)
Scope: Apply recommendations based on the reference rules and good/bad code examples.
为Spring Boot应用应用REST API设计原则。
本Skill涵盖哪些内容？
  • HTTP方法（GET、POST、PUT、PATCH、DELETE）——语义一致性
  • 资源URI设计
  • HTTP状态码
  • 具备精简契约的请求/响应DTO
  • API版本控制（URI、标头或媒体类型——保持一致应用）
  • 边界处的Bean Validation（控制器输入上的@Valid/@Validated，验证失败时返回400）
  • 分页、排序与过滤（带限制的Page/Pageable）
  • JSON契约中带偏移的ISO-8601时间戳（OffsetDateTime、Instant）
  • 内容协商（默认JSON；有意义时使用供应商媒体类型）
  • 支持POST创建操作的Idempotency-Key；冲突时返回409 Conflict
  • 结合If-Match/If-None-Match的ETag并发；返回412 Precondition Failed / 304 Not Modified
  • HTTP缓存规范（Cache-Control、ETag、Last-Modified）
  • 弃用与日落标头（Deprecation、Sunset、Link rel="successor-version"）
  • 错误处理
  • API安全性（TLS、身份验证、授权、输入验证）
  • 文档（OpenAPI）
  • 控制器通知与问题详情（RFC 7807）
**范围：**基于参考规则和代码示例的优劣来应用建议。

Constraints

约束条件

Before applying any REST API changes, ensure the project compiles. If compilation fails, stop immediately. After applying improvements, run full verification.
  • 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 good/bad patterns
在应用任何REST API变更之前，确保项目可编译。如果编译失败，立即停止。应用优化后，运行完整验证。
  • 强制要求：应用任何变更前运行
    ./mvnw compile
    或
    mvn compile
  • 安全要求：如果编译失败，立即停止
  • 验证要求：应用优化后运行
    ./mvnw clean verify
    或
    mvn clean verify
  • 应用前须知：阅读参考文档以了解详细规则和优劣模式

When to use this skill

何时使用本Skill

  • Review Java code for Spring Boot REST API
  • Apply best practices for Spring Boot REST API in Java code
  • 评审Java代码中的Spring Boot REST API
  • 在Java代码中应用Spring Boot REST API的最佳实践

Reference

参考资料

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