关于 302-frameworks-spring-boot-rest
用于在 Spring Boot 应用中落实 REST API 设计实践的技能，涵盖端点语义、验证、API 契约、错误处理、安全性及 HTTP 行为，并要求变更前后执行构建检查。
主要功能
- 01HTTP 方法与 URI 设计
- 02DTO 与 API 版本管理
- 03边界验证与分页
- 04缓存与条件请求
- 05Problem Details 与错误处理
- 06安全性与 OpenAPI 契约
适用场景
- 01审查 Spring Boot REST 控制器
- 02设计请求与响应 DTO
- 03添加分页或幂等行为
- 04统一 API 错误与契约
安装
复制下面的命令，在终端中运行。
$
npx skills add https:/安装后在 Claude Code 中输入/302-frameworks-spring-boot-rest确认已加载。
附带文件references/302-frameworks-spring-boot-rest.md
详细介绍
Java REST API 设计原则
为 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、身份验证、授权、输入验证）
- API 契约：将 OpenAPI 文件作为 API 优先开发的事实来源（OpenAPI Generator）
- 控制器通知和问题详情（RFC 7807）
范围： 根据参考规则和优劣代码示例应用建议。
约束
应用任何 REST API 更改之前，确保项目能够编译。如果编译失败，立即停止。改进完成后，运行完整验证。
- 强制要求：应用任何更改之前，运行
./mvnw compile或mvn compile - 安全要求：如果编译失败，立即停止
- 验证要求：应用改进后，运行
./mvnw clean verify或mvn clean verify - 应用之前：阅读参考文档，了解详细规则和优劣模式
- 边界情况：如果请求范围不明确，先停止并提出澄清问题，再应用更改
- 边界情况：如果缺少必需的输入、文件或工具，请说明缺少的内容，并询问是否要继续获取设置指导
何时使用此 Skill
- 审查 Spring Boot REST API 的 Java 代码
- 在 Java 代码中应用 Spring Boot REST API 最佳实践
- 设计 Spring Boot REST 控制器和 DTO
- 在 Spring Boot REST 中添加 Problem Details 错误响应
- 改进 Spring API 中的分页验证或幂等性
工作流
- 阅读参考文档并评估项目上下文
阅读 references/302-frameworks-spring-boot-rest.md，并检查当前项目设置，然后再提出更改建议。
- 确定范围并选定目标改进
明确预期结果、约束，以及要应用的最小安全更改集。
- 应用符合框架规范的更改
遵循参考模式和项目惯例，实现或重构配置/代码。
- 运行验证并报告结果
执行适当的构建/测试，并总结更改内容、验证情况以及任何后续操作。
参考资料
详细指南、示例和约束请参阅 references/302-frameworks-spring-boot-rest.md。
评论
支持 Markdown