RESTful API 设计中的 7 个常见错误

看了很多项目 API，总结了几个高频错误：

1. URL 里加动词 错误：POST /api/createUser GET /api/getUserList 正确：POST /api/users GET /api/users REST 的语义在 HTTP method 里，URL 只需要名词。

2. 用错了状态码

• 创建成功永远 201，不要 200
• 参数校验失败用 422，不要 200 + "参数错误" 的 JSON
• 401 是没登录，403 是没权限，别混

3. 把所有东西塞进一个接口 一个页面调十个接口比一个接口查十张表更合理。前端可以并发，后端 join 太多反而慢。

4. 不写分页 GET /api/users 返回 10 万条？加上 page 和 pageSize，响应里带上 total。

5. 把敏感数据暴露了 password 的 hash 也是敏感数据，永远不要输出到 API 响应里。

6. 版本号放在 header 里而不是 URL 里 实践中 /api/v2/users 比 Accept: version=2 更直观，出问题也好排查。

7. 不用名词复数 /api/user/1 → /api/users/1，统一用复数，一劳永逸。