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。