## 直接说结论
API接口设计没有银弹，但有一堆血泪教训。核心就三件事：路径用名词别用动词、状态码别乱用、版本号放URL里。把这三点刻进DNA，你的接口至少不会被人骂。今天我把踩过的坑全倒出来。
## 路径设计：名词是主角，动词是配角
我最早做接口时，写过`/getUserInfo`这种路径，后来被前端同事吐槽到怀疑人生。RESTful风格的精髓是用HTTP方法表达动作，路径里只放资源。`/users/123`配上GET、PUT、DELETE，比`/getUser`、`/updateUser`清爽一百倍。
有个细节特别容易忽略：复数还是单数？我建议统一用复数，`/users`而不是`/user`，因为资源是集合概念。嵌套资源也别太深，超过两层就该考虑拆分了，不然`/users/123/orders/456/items/789`这种URL，维护起来想砸电脑。
## 状态码：别全返回200
我见过最离谱的接口，不管成功失败都返回200，然后body里塞个`code: 1`表示失败。这种设计让调用方得写两层判断，纯粹给自己挖坑。HTTP状态码是现成的，为什么不用？
200表示成功，400表示参数错误，401未认证，403没权限，404资源不存在，500服务器内部错误。我后来强制团队遵守：状态码只代表传输层结果，业务错误码放body里，但状态码必须语义化。这样日志排查和监控报警都省事。
## 版本管理：URL里写v1，别玩花样
我踩过最大的坑是接口升级后旧版本直接删了，结果第三方应用全挂了。从那以后我坚持版本号放URL路径，`/v1/users`和`/v2/users`共存，至少留半年过渡期。别用Header或者参数传版本号，肉眼排查麻烦，网关转发也容易出错。
还有个坑是向后兼容。新增字段没问题，但别改字段名或删字段。真要改，必须发新版本。我见过一个团队把`userName`改成`name`，结果前端白屏一整天。
## 参数与响应：命名统一，结构稳定
参数命名上，我吃过`user_id`和`userId`混用的亏。后来定死规则：接口内部用驼峰，对外统一蛇形（`user_id`），因为数据库和日志系统对下划线更友好。响应结构我固定成`{code, message, data}`，data里是业务数据，分页就固定`{list, total, page, size}`，大家写起来都省心。
错误信息别只给个”系统错误”，至少得让调用方知道哪个字段错了。我见过一个接口返回`{“error”: “invalid parameter”}`，前端排查半天不知道是哪个参数，气得直跺脚。
## 常见问题
**Q：接口要不要做幂等设计？**
A：要，尤其是支付、下单这类操作。用唯一请求ID或token做幂等键，重复请求直接返回第一次的结果，避免重复扣款或重复创建订单。
**Q：接口文档用什么工具维护？**
A：推荐OpenAPI（Swagger）规范，代码注解自动生成文档。别用Word或Markdown手写，维护成本太高，文档和代码必然脱节。
**Q：接口鉴权怎么做？**
A：简单场景用JWT，复杂场景用OAuth2.0。别自己发明token机制，安全漏洞防不胜防。JWT记得设置过期时间，别搞永久有效。
**Q：接口性能优化从哪下手？**
A：先做缓存（Redis），再考虑数据库索引和SQL优化。接口响应时间超过500ms就该查了，别等用户投诉才动手。
**Q：接口测试怎么保证质量？**
A：单元测试覆盖核心逻辑，集成测试跑通主流程，再加契约测试防止接口定义被改坏。CI/CD里必须跑，别靠人肉测试。
## 写在最后
这些规范看着简单，但每一条都是我拿加班和线上事故换来的。接口设计本质是沟通，让调用方少踩坑，就是给自己省心。你有没有遇到过特别离谱的接口设计？评论区聊聊，让我看看谁比我还惨。
📚 相关专题：未分类