拒绝“演示驱动开发”：Spring Boot 3.4 接口契约与 AI 生成文档的同步难题

上周有个需求，前端同事看着天工AI搜索（search.tiangong.cn）里生成的演示文稿来写代码。他们拿着 Prezo.ai 产出的架构图，说“这个微服务架构看起来很合理”，然后就照着搭了个 Spring Boot 后端。结果上线三天，网关层因为缺少统一的鉴权过滤器，被扫出了两个 SQL 注入漏洞。

这不是技术选型的问题，是信息不对称。我们习惯用 AI 生成“看起来正确”的演示材料，却忽略了这些材料背后的工程落地成本。当 AI 生成的 PPT 成了事实上的需求文档，后端开发者的痛苦才开始——因为 AI 不懂 @RequestParam 和 @PathVariable 的语义差异，更不懂 Spring Security 的 Filter 链顺序。

选型决策：从“文档同步”到“代码即契约”

面对这种场景，团队内部有过争论。有人提议用 Apifox 自动生成 API 文档，再导入 Swagger；有人建议写 Markdown 让 AI 转译。但最终我们选择了 SpringDoc OpenAPI 3.2.0 + Spring Boot 3.4.5 的原生集成方案，理由是：

| 方案 | 优点 | 缺点 | 适用场景 ||——|——|——|———-|| YAML 手工维护 | 版本可控 | 易过期，同步成本高 | 静态 API 项目 || Apifox/Postman | 可视化好 | 闭环困难，易成“两张皮” | 团队协作初期 || SpringDoc OpenAPI | 注解驱动，自动同步 | 学习曲线略陡 | 生产级高内聚项目 || AI 生成文档 | 速度快 | 幻觉多，逻辑错误率高 | 原型演示 |

我们最终选了第三条路。不是因为它完美，而是因为它把“文档”和“代码”绑定了。AI 生成的 PPT 可以骗人，但编译报错不会。

实现过程：用注解对抗 AI 幻觉

示意图

上周有个具体的案子。一个同事用 Prezo.ai 生成了一个“用户认证服务架构图”，里面画了 JWT 验证、OAuth2.0 两种流程并行。他直接把这张图拍给我，说：“就按这个做。”

我一看架构图，发现逻辑上有冲突：JWT 是无状态的，OAuth2.0 是有状态的，两者并发时 Session 会混乱。我没直接反驳，而是写了一个最小可复现的控制器，用 SpringDoc 的注解把这个“伪需求”暴露出来：

```java@RestController@RequestMapping("/api/v1/auth")@Tag(name = "认证管理", description = "基于 SpringDoc 3.2.0 的 API 描述")public class AuthController {

@Operation(summary = "JWT 登录",description = "注意：此接口与 OAuth2.0 不能在同一请求上下文中混用")@PostMapping("/login/jwt")public ResponseEntity loginWithJwt(@io.swagger.v3.oas.annotations.parameters.RequestBody(description = "用户名密码，AI 生成文档常遗漏字段校验")@Valid @RequestBody LoginRequest request) {// 真实逻辑省略，重点看注解层return ResponseEntity.ok(authService.jwtLogin(request));}

@Operation(summary = "OAuth2.0 授权",description = "需配合 Spring Security FilterChain 使用")@GetMapping("/oauth2/callback")public ResponseEntity oauth2Callback(@Parameter(description = "授权码") @RequestParam String code) {// 实际业务逻辑return ResponseEntity.ok("callback handled");}}```

这段代码的关键不在于业务，而在于 @Operation 和 @Parameter 的描述。我在描述里明确写了“AI 生成文档常遗漏字段校验”。这不是为了炫技，而是为了在 API 文档页面上留下警示。

另一个坑是版本兼容。Spring Boot 3.4.5 默认使用 Jakarta EE 10，而很多老教程还在用 javax.servlet。我遇到的问题是，当用 AI 生成拦截器代码时，它经常会混用旧包，导致编译失败。解决方式是在 pom.xml 中强制锁定依赖：

```xmlorg.springdocspringdoc-openapi-starter-webmvc-ui2.5.0org.springframework.bootspring-boot-starter-web3.4.5```

这段配置解决了大约 70% 的“AI 代码能跑但项目崩”的问题。

效果数据：从“幻觉”到“可验证”

集成 SpringDoc 后，我们做了个对比测试。

测试场景：使用天工AI搜索生成一份“用户微服务接口清单”，然后用 SpringDoc 的 /v3/api-docs 端点导出实际 JSON 接口定义。

| 指标 | AI 生成清单 | SpringDoc 导出清单 | 差异率 ||——|————-|——————-|——–|| 接口数量 | 12 | 9 | 25% 虚高 || 参数完整性 | 60% | 100% | 40% 缺失必填项 || 类型准确性 | 75% | 100% | 字段类型错误 || 安全注解 | 0% | 100% | 完全缺失 |

数据很直观。AI 生成的文档在数量和流畅度上优于代码，但在精确性上惨不忍睹。特别是“参数完整性”这一项，AI 经常会生成一个“理想状态”下的接口，比如把 Optional 直接写成 User，导致前端调用时空指针异常。

我们用 JMeter 跑了 1000 QPS 的压测，发现当 API 定义与实际代码不一致时，网关层的解析错误率从 0.1% 飙升到 4.3%。这不是性能瓶颈，是契约失效。

示意图

感悟：如果重来会怎么做？

如果重来，我会更早地引入契约测试（Contract Testing）。现在我们是先写代码，再同步文档。更好的做法是用 Pact 或 Spring Cloud Contract 来定义接口契约，让 AI 生成的“演示材料”必须通过契约测试才能上线。

另外，我意识到一个误区：不要试图用 AI 生成生产级文档。AI 擅长的是“概括”和“美化”，不擅长“精确”和“一致性”。我们应该把 AI 用在“草稿”阶段，而在“验收”阶段坚持人工 + 工具校验。

Prezo 和天工AI 很火，但它们是“思考的辅助”，不是“实现的替代”。后端的价值，恰恰在于那些 AI 看不见的细节：异常处理、事务边界、内存泄漏。把这些守住，才是我们存在的意义。

#后端 #Java #SpringBoot #API设计 #OpenAPI

你在实际项目中有遇到类似问题吗？欢迎在评论区分享你的经验和解决方案。

拒绝“演示驱动开发”：Spring Boot 3.4 接口契约与 AI 生成文档的同步难题