API接口设计最容易忽略的5个细节

做了几年后端开发，发现很多人 RESTful API 设计在文档里很漂亮，但真用起来各种不好使。

1. 错误响应不统一

有的接口报错返回 {"error":"not found"}，有的返回 {"code":404,"msg":"找不到"}，前端解析的时候得写一堆条件判断。统一约定一个格式，比如 {"code": 错误码, "message": "描述", "data": null}，前后端都舒服。

2. 分页不告知总数

只返回当前页数据不返回 total 和 page_count，前端就不知道有没有下一页。典型的接口需要返回 total（总数）、page（当前页）、page_size（每页大小）、has_more（是否还有更多）。

3. 更新接口用 PUT 还是 PATCH

PUT 是全量替换，PATCH 是部分更新。很多人不分，前端改一个字段也传整个对象过去。如果用了 PUT，没传的字段可能就变成空了。建议统一用 PATCH 做部分更新。

4. 枚举值不做版本兼容

代码里定义了 status 字段的值 1=待审核、2=已通过，结果某天加了 3=待重审，老版本客户端不认识，直接崩了。枚举值尽量在文档里标注版本，新值放后面，break 逻辑用 switch 加 default。

5. 敏感信息不该出现在日志里

请求体和响应体里带上密码、Token、身份证号，直接打印到日志文件里。日志文件权限没设好被泄露，等于裸奔。建议加个日志脱敏中间件，对 password、token、secret 开头的字段自动替换成 ***。