- 约1183字
- 技术
- 2026年3月20日
很多开发者觉得API设计是个"差不多就行"的事——反正能跑能用，直到有一天你发现：
改一个字段名要通知5个前端同事，加一个参数要改3个版本的兼容逻辑。
这就是糟糕API设计的代价。
现象
我见过最离谱的一个接口，700多行代码，40多个参数，文档写了20页。前端同事每次对接都要专门拉个会，后端同事每次改动都提心吊胆。一个看似简单的需求，因为接口设计不当，硬是拖了兩周。
这不是个例。根据我过去三年的项目统计，超过60%的前后端协作问题，都能在API设计阶段找到根源。
判断
API设计不是表面功夫，而是一次性交付给未来的协作效率。 设计得好，后端省心、前端安心、需求变更时大家都不闹心。设计得差，那就是给团队埋雷。
最要命的是，API的寿命往往比你想的更长。一个接口上线后，可能要维护三到五年，甚至更久。每次改动都是一次风险，能在源头规避的问题千万别留给未来。
依据
过去一年我参与了8个后端项目的API设计，发现下面5个错误出现频率最高：
1. 命名不一致
有的接口用userId，有的用uid，有的用user_id。前端对接时需要来回对照文档排查字段，一不小心就踩坑。
2. 返回结构不统一
A接口返回{code, data, message}，B接口返回{status, result, msg}，C接口直接返回数组。同样的错误处理逻辑要写三套，前端苦不堪言。
3. 缺乏版本管理 接口直接改，不留版本号。老接口一旦变更，所有调用方同步崩溃。线上事故往往就出在这种"无害"的小改动上。
4. 分页参数混乱
有的用page+size，有的用offset+limit，有的用start+count。前端光记各种接口的分页规则就要疯。
5. 错误码不完整
成功返回200，失败也返回200，靠msg字段传递错误信息。监控系统根本无法区分正常请求和异常请求。
行动建议
针对上面5个问题，我的建议是：
统一命名规范：接口文档开头就写死字段命名规则，比如所有ID统一用xxxId格式，禁止出现uid、user_id之类的变体。
固定响应结构：定义标准的返回格式，比如{code: number, data: any, message: string}，所有接口都必须遵循。code=0表示成功，非0表示具体错误类型。
强制版本号：URL路径加版本前缀，如/api/v1/users，变更时升级版本号而非直接在原接口上修改。
统一分页参数：全站统一用page+pageSize或其他固定组合，并在文档中明确默认值和上限。
完善错误码体系：定义一套完整的错误码文档，比如1001代表参数校验失败、1002代表权限不足等。让错误可追踪、可监控。
好的API设计，本质上是在为未来的协作效率买单。前期多花半小时梳理结构，后期可能省下的是上百小时的沟通和改 bug 时间。
如果你正在设计新接口，建议先把上面5个点过一遍。如果你接手了一个"历史遗留"接口，那从今天开始，逐步规范化吧。