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)
  • API contract: OpenAPI file as source of truth for API-first (OpenAPI Generator)
  • 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创建请求的幂等键支持；冲突时返回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、认证、授权、输入验证）
  • API契约：以OpenAPI文件作为API优先的事实来源（OpenAPI Generator）
  • 控制器通知与问题详情（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
  • EDGE CASE: If request scope is ambiguous, stop and ask a clarifying question before applying changes
  • EDGE CASE: If required inputs, files, or tooling are missing, report what is missing and ask whether to proceed with setup guidance
在应用任何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
  • Design Spring Boot REST controllers and DTOs
  • Add Problem Details error responses in Spring Boot REST
  • Improve pagination validation or idempotency in Spring APIs
  • 评审Spring Boot REST API的Java代码
  • 在Java代码中应用Spring Boot REST API最佳实践
  • 设计Spring Boot REST控制器与DTO
  • 在Spring Boot REST中添加问题详情错误响应
  • 优化Spring API的分页验证或幂等性

Workflow

工作流程

  1. Read reference and assess project context
Read 
references/302-frameworks-spring-boot-rest.md
and inspect the current project setup before proposing changes.
  1. Gather scope and decide target improvements
Identify requested outcomes, constraints, and the minimum safe set of changes to apply.
  1. Apply framework-aligned changes
Implement or refactor configuration/code following the reference patterns and project conventions.
  1. Run verification and report results
Execute appropriate build/tests and summarize what changed, what was verified, and any follow-up actions.
  1. 阅读参考文档并评估项目上下文
阅读
references/302-frameworks-spring-boot-rest.md
并检查当前项目设置，再提出变更建议。
  1. 收集范围并确定目标优化点
明确请求的结果、约束条件以及要应用的最小安全变更集。
  1. 应用符合框架的变更
遵循参考模式和项目约定实现或重构配置/代码。
  1. 执行验证并报告结果
执行相应的构建/测试，总结变更内容、验证情况以及后续行动。

Reference

参考文档

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