3、需求分析与接口定义：如何读懂接口文档、定义API契约、使用Swagger/OpenAPI
说实话，很多系统集成项目翻车，不是技术多难，而是接口没对齐。
我见过最惨的一次，前后端联调了三天，结果发现两边对「用户状态」的理解完全不一样——后端返回0、1、2，前端以为只有0和1。嗯，这种坑，踩一次就记住了。
所以这一章，咱们聊聊怎么把接口这件事，从一开始就理清楚。
3.1 接口文档到底怎么看？
很多新人拿到接口文档，第一反应是「好长，不想看」。我刚开始也这样。后来被坑了几次，才学会怎么看重点。
核心就三件事：
- 请求路径和方式：GET、POST、PUT、DELETE，别搞混。我见过有人把删除接口写成GET，结果数据全暴露了。
- 请求参数：哪些是必填，哪些是可选，参数类型是什么。尤其注意「枚举值」，我曾经因为少传一个枚举值，接口直接返回500。
- 响应结构：重点关注code、message、data这三层。很多文档会写「成功返回0，失败返回非0」，但具体非0是多少？得问清楚。
我的习惯：拿到文档先画个表格，把每个接口的入参、出参、异常情况列出来。画完基本就懂了。
3.2 定义API契约：别让接口变成「黑箱」
什么叫API契约？说白了，就是前后端、服务之间约定好的「接口规则」。谁传什么，谁返回什么，白纸黑字写清楚。
我建议这样做：
- 先定数据结构：比如用户信息，必须包含userId、userName、status，缺一不可。
- 再定状态码：200表示成功，400表示参数错误，500表示服务异常。别自己发明一套「20001代表成功，20002代表失败」，那只会让人崩溃。
- 最后定异常处理：接口超时怎么办？数据不存在返回什么？这些都得提前说好。
避坑指南：我曾经遇到一个项目，后端说「我返回null表示没有数据」，前端说「我理解的是返回空数组」。结果上线当天，页面白屏了。嗯，从那以后，我要求所有接口必须明确「空值处理」。
3.3 使用Swagger/OpenAPI：让文档自动生成
手写接口文档？太累了，而且容易过期。我推荐用Swagger（现在叫OpenAPI）。
说白了，Swagger就是一套规范，你按照它的格式写注解，它自动生成文档。前后端都能看，还能直接调试。
举个例子：
@ApiOperation(value = "获取用户信息")
@GetMapping("/user/{id}")
public Result<User> getUser(@PathVariable Long id) {
// 业务逻辑
}
加上这几行注解，Swagger就能自动生成一个接口页面，参数、返回值、示例代码全都有。
为什么推荐它？
- 文档和代码同步，改代码自动更新文档
- 支持在线调试，不用Postman也能测接口
- 团队协作时，大家看同一个文档，减少沟通成本
注意：Swagger虽然好用，但别把所有接口都暴露出去。生产环境记得关闭Swagger页面，不然等于把系统后门打开给别人看。
3.4 核心知识体系：一张图看懂
下面这张图，是我自己总结的「接口定义全流程」。你照着走，基本不会出大问题。
3.5 实战建议：从零开始定义接口
如果你现在要开始一个新项目，我建议按这个顺序来：
- 先画业务流程图：搞清楚数据怎么流转，谁调用谁。
- 再写接口文档草稿：用Excel或者在线文档，把接口名、参数、返回值列出来。
- 然后加Swagger注解：让文档自动生成，前后端都能看。
- 最后做接口评审：拉上前后端一起过一遍，确认没问题再开发。
我的经验：接口评审这一步，很多人觉得麻烦就跳过了。但恰恰是这一步，能发现80%的潜在问题。别省。
3.6 总结
需求分析和接口定义，说白了就是「把话说清楚」。你想想看，如果两个人连「用户状态」都定义不一致，后面怎么合作？
用好Swagger/OpenAPI，让文档自动生成，减少人工维护成本。再加上接口评审，基本就能把坑填平大半。
嗯，这一章就到这里。记住：接口定义越清晰，后期联调越省心。