spring-mvc-webflux-api-builder

Spring MVC WebFlux API 构建器

来源映射：源自 Kotlin_Spring_Developer_Pipeline.md（SK-06）的一级关键技能。

使命

生成的 API 代码不仅要看似合理，还要符合仓库实际使用的 Spring 技术栈。 将端点、DTO、验证和测试脚手架作为一个连贯整体生成。

先确定技术栈

• 确认模块使用的是 Spring MVC 还是 WebFlux。
• 确认控制器采用阻塞式、基于协程还是基于 Reactor 的方式。
• 确认项目现有的错误格式、序列化规则和 OpenAPI 方案。
• 如果 project-context-ingestion 已经确定了这些信息，请复用其输出。

编写代码前先设计契约

• 定义端点路径、方法、身份验证要求、幂等规则和状态码。
• 定义请求和响应 DTO 的边界。不要直接暴露实体。
• 定义验证失败、业务冲突、资源未找到和意外错误的错误模型。
• 视情况定义分页、排序和关联 ID 行为。
• 明确 null、缺失和默认值字段是否具有不同语义。

按以下顺序生成

1. 请求和响应 DTO。
2. 使用正确 Kotlin @field: 使用点目标的验证注解。
3. 控制器签名。
4. 服务接口或用例边界。
5. 传输模型与领域模型之间的映射或转换代码。
6. 通过 @ControllerAdvice 或项目中的等效机制处理错误。
7. 编写一个能验证契约的精简 Web 层测试。

Kotlin 专属规则

• 对构造函数属性上的 Jakarta Bean Validation 注解使用 @field: 目标。
• 明确区分可空字段和必填字段。
• 将 null 与缺失的区别视为契约决策，尤其是类 PATCH 行为。
• 在依赖 Kotlin 构造函数默认值之前，确认已启用 jackson-module-kotlin 或等效的序列化支持。
• 除非项目明确采用其他模式，否则优先使用包含 val 属性的不可变 DTO。

MVC 和 WebFlux 规则

• 除非仓库有意这样做，否则不要在同一生成端点中混用 MVC 和 WebFlux 风格。
• 对于 MVC，优先使用普通返回类型和阻塞式服务边界。
• 对于使用协程的 WebFlux，如果需要流式传输，优先使用 suspend 函数和 Flow<T>。
• 对于基于 Reactor 的代码，遵循项目现有的 Mono 和 Flux 约定，不要另创混合风格。

高级契约决策

• 即使面向用户的消息会变化，也应优先在负载中使用稳定、机器可读的错误代码。
• 谨慎选择 400 还是 422。验证失败和格式错误的输入，不等同于违反领域规则。
• 对于创建端点，应决定 201 Created 和 Location 是否属于契约的一部分。不要仅仅因为 200 更容易实现就默认使用它。
• 对于更新端点，当并发编辑会造成影响时，应考虑版本字段或 ETag 和 If-Match 等乐观并发控制信号。
• 对于 PATCH 语义，必要时应明确建模三种状态：缺失、存在且有值、存在且为 null。普通的 Kotlin 可空字段并不总能表示这三种状态。
• 除非服务已将此作为标准决策，否则应避免直接将 Page 等 Spring 专属传输类型暴露为公共 API 契约。
• 明确日期时间、枚举和值类的序列化方式。不同版本和客户端之间的默认序列化行为往往会出现偏差。
• 对于流式端点，除了方法签名，还应考虑取消、背压和部分写入行为。

专家启发式原则

• 在编写控制器代码之前，先设计错误契约和验证契约。事后再补上这些契约，会造成最多的 API 变更。
• 传输 DTO 应保持精简且明确。复用内部领域模型或许能省下一次时间，却会一直造成额外成本。
• 如果服务是公开的或需要长期维护，应优先考虑向后兼容的契约演进：新增字段、稳定的代码，以及审慎的弃用策略。
• 尽可能在过滤器或拦截器中传递关联 ID，而不是在每个控制器方法中处理。

输出契约

请返回可直接应用的补丁方案，或包含以下内容的具体文件或代码块：

• 请求 DTO
• 响应 DTO
• 控制器
• 服务接口或用例入口
• 异常映射或 advice 更新
• Web 层测试

还请简要说明会实质影响兼容性的 API 契约决策。

注意事项

• 不要在 API 错误中泄露内部异常详情。
• 在 Kotlin 中，不要将验证注解用于错误的目标。
• 不要在网络接口中暴露持久化实体。
• 不要未经检查契约就假定默认 HTTP 状态码。
• 如果模块使用 WebFlux，不要擅自选用 MVC；反之亦然。

验证清单

• 端点可使用仓库中的实际 Spring 技术栈编译。
• 对无效输入会触发验证，并返回预期的错误格式。
• Web 层测试覆盖成功路径和至少一种失败路径。
• 序列化规则符合项目现有约定。

质量标准

良好的技能运行结果应提供一个能够编译、验证、序列化并以一致方式处理失败的端点。 糟糕的运行结果则会混用框架、错误处理 Kotlin 验证，或凭空设计出服务其他部分并未使用的错误模型。