主题
skill分享 - Spring Web API架构协议
简介
这是一个专为 Spring 框架构建外部 API 设计的架构协议 skill。它定义了强制性的分层规则、数据模型边界、验证策略、异常处理和框架级检查，确保 API 的稳定性、可维护性和向后兼容性。特别适合使用 Spring MVC / Spring Boot 开发 RESTful API 的项目。
核心价值
- ✅ 清晰的分层架构：Controller → Service → Repository，职责明确
- ✅ 严格的边界隔离：DTO 与 Entity 分离，防止内部模型泄露
- ✅ 统一的异常处理：集中式错误处理，避免异常信息泄露
- ✅ 规范的验证策略：API 边界验证 + 业务规则验证分离
- ✅ 向后兼容性保障：强制兼容性规则，确保 API 稳定演进
如何使用
方法一：直接复制使用（推荐）
将下面的完整内容复制，发送给 Codex，告诉它"请帮我制作成 skill"即可。
方法二：手动创建 skill
如果你熟悉 skill 的创建流程，可以手动创建一个名为 spring-web-api-architecture-protocol 的 skill，并将下面的内容作为 skill 的配置。
Skill 完整内容
markdown
name: spring-web-api-architecture-protocol
description: 为使用 Spring 框架构建外部 API 定义强制性的架构、分层、数据模型边界、验证、异常处理和框架级检查。
# Spring Web API 架构协议
## 适用范围（必须遵守）
此 skill 适用于：
- 使用 Spring（Spring MVC / Spring Boot）构建或修改面向外部的 API
- 定义 controllers、services、repositories、DTOs 或 API 错误模型
- 引入验证、异常处理或框架级行为
**此 skill 不定义内部 Java 结构规则。**
内部结构由 `java-code-structure-minimalism` 管理。
---
## 分层规则（必须遵守）
**允许的层次：**
Controller → Service → Repository
### Controller（控制器）
- 仅处理请求解析和响应映射
- **禁止包含业务逻辑**
- **禁止直接访问 repositories**
- **必须保持无状态**
### Service（服务层）
- 拥有业务逻辑
- 拥有事务边界
- 协调 repositories 和外部系统
### Repository（持久层）
- 仅负责持久化访问
- **不包含业务逻辑**
### 额外层次（禁止，除非特定情况）
**禁止额外层次**（Facade / Manager / Adapter / Orchestrator），除非：
- 协调 ≥2 个 services，或
- 协调 ≥2 个外部系统
---
## 数据模型边界（必须遵守）
### DTO（数据传输对象）
- **仅用于 API 边界**
- **禁止重用为领域实体**
- **禁止包含业务逻辑**
### Entity / Domain Model（实体/领域模型）
- **禁止在 controllers 中暴露**
- **禁止直接序列化到 API 响应**
### 映射规则
- 映射逻辑属于 **Service 层**
- 仅当映射逻辑被重用时，才允许专用的 mapper 类
- **默认不引入 mapper 层**
- DTO 的存在**不能**作为引入额外抽象层的理由
---
## 验证规则（必须遵守）
- **输入验证必须在 API 边界进行**
- 一致使用 Bean Validation（`@Valid`、`@NotNull` 等）
- 验证失败必须映射到统一的 API 错误响应
- **业务规则验证必须在 Service 层**
---
## 异常处理（必须遵守）
- **Controllers 禁止捕获业务异常**
- 使用集中式异常处理（`@ControllerAdvice`）
- API 必须暴露稳定的错误模型，至少包含：
- `errorCode`（错误码）
- `message`（消息）
- 可选的 `details`（详情）
- **内部异常类型和堆栈跟踪禁止泄露到 API 响应**
---
## Spring 特定检查（必须遵守）
- `@Transactional` **仅允许在 Service 层**
- **Controllers 绝不声明事务**
- **Controllers 绝不访问 repositories**
- Jackson 配置（未知字段、日期格式、命名）必须集中化
- API 行为在默认 Spring 配置下必须是确定性的
---
## 兼容性与演进（必须遵守）
- **API 变更必须向后兼容**，除非明确声明
- 字段移除或语义变更需要版本控制或回退处理
- 默认值和可选字段必须保持稳定
- 兼容性规则适用于所有情况，**不受内部重构影响**
---
## 与其他 Skills 的关系
- **API 结构和框架规则**由此 skill 管理
- **内部 Java 代码结构**由 `java-code-structure-minimalism` 管理
- **文档义务**由 `design-change-documentation-protocol` 管理
---
## 非目标
此 skill **不定义**：
- 代码格式化或样式约定
- 性能优化
- 非 Spring 框架行为使用建议
适用场景：
- 使用 Spring Boot / Spring MVC 开发 RESTful API
- 需要明确分层架构和职责划分的项目
- 对 API 稳定性和兼容性有严格要求的场景
调用方式：在对话中告诉 Codex"使用 spring-web-api-architecture-protocol skill"
最佳实践：
- 在项目初期就引入此 skill，建立清晰的架构规范
- 结合代码审查，确保分层规则被严格遵守
- 使用
@ControllerAdvice统一异常处理，避免在每个 Controller 中重复代码 - DTO 与 Entity 严格分离，避免内部模型泄露到外部 API
- 在 Service 层使用
@Transactional管理事务边界
常见错误：
- ❌ 在 Controller 中直接访问 Repository
- ❌ 将 Entity 直接返回给前端
- ❌ 在 Controller 中编写业务逻辑
- ❌ 在 Controller 中使用
@Transactional - ❌ 创建不必要的 Mapper/Facade/Manager 层
架构示例
正确的分层调用
java
@RestController
public class OrderController {
@Autowired
private OrderService orderService;
@PostMapping("/orders")
public OrderDTO createOrder(@Valid @RequestBody CreateOrderRequest request) {
// ✅ 仅负责请求解析和响应映射
return orderService.createOrder(request);
}
}
@Service
public class OrderService {
@Autowired
private OrderRepository orderRepository;
@Transactional // ✅ 事务在 Service 层
public OrderDTO createOrder(CreateOrderRequest request) {
// ✅ 业务逻辑在 Service 层
Order order = new Order();
// ... 业务处理
Order savedOrder = orderRepository.save(order);
return mapToDTO(savedOrder); // ✅ 映射逻辑在 Service 层
}
}错误的分层调用
java
@RestController
public class OrderController {
@Autowired
private OrderRepository orderRepository; // ❌ Controller 不应直接访问 Repository
@Transactional // ❌ Controller 不应声明事务
@PostMapping("/orders")
public Order createOrder(@RequestBody Order order) { // ❌ 不应直接暴露 Entity
// ❌ 业务逻辑不应在 Controller
if (order.getAmount() > 1000) {
order.setStatus("PENDING_APPROVAL");
}
return orderRepository.save(order);
}
}相关资源
- skill 介绍 - 了解 skill 的基本概念
- skill分享 - Java编码规范 - Java 代码风格规范
- 进阶教程 - skill 使用指南 - 详细的 skill 教程