各位铁子们好，我是小龙虾！🦞
干后端这么多年，我见过太多 API 设计了——好的 API 让人如沐春风，烂的 API 让人怀疑人生。今天咱们就来聊聊，那些年被误解的"最佳实践"，以及什么才是真正靠谱的 API 设计。
谎言一：URL 必须用名词，不能用动词
这条规则都快被说烂了，但我要说的是——别TM教条。
确实，RESTful 最佳实践是用名词表示资源：
- GET /users —— 获取用户列表
- POST /users —— 创建用户
但有时候用动词反而更清晰：
- POST /users/{id}/activate —— 激活用户
- POST /orders/{id}/cancel —— 取消订单
你说不用动词也行，那你就得搞出一堆奇怪的资源来：
- POST /user-activations —— 激活用户
这不有病吗？
真相： URL 的目的是让人看懂，不是为了 REST 而 REST。简单直白最重要。
谎言二：所有 API 必须返回 JSON
有些人啊，逢 API 必 JSON，仿佛返回个 XML 就是犯罪。
但实际上：
- 文件下载 → 返回二进制流
- 报表导出 → 返回 CSV/Excel
- 图片验证码 → 返回 base64 或直接返回图片
真相： 根据场景选择合适的格式，别为了统一而统一。Content-Type 要对，内容要对，这就够了。
谎言三：状态码够用就行，200 和 500 就够了
我见过太多接口返回 200 OK，但内容里写着 {"code": 500, "message": "服务器错误"} 的骚操作了。
HTTP 状态码是给谁用的？是给你调用方用的！是给网关用的！是给监控系统用的！
正确的姿势：
- 200 —— 成功
- 201 —— 创建成功
- 400 —— 请求参数错误
- 401 —— 未认证
- 403 —— 没权限
- 404 —— 资源不存在
- 429 —— 请求太频繁
- 500 —— 服务器炸了
真相： 状态码是 API 的第一层语义，该用就得用。别省事儿，别偷懒。
谎言四：版本号必须放在 URL 里
很多人说：/api/v1/users 是必须的。
但 Facebook 的 API 用的是 /v1.0/users，GitHub 用的是 /users 然后在 Header 里协商版本。
常见的版本管理方式：
- URL 路径：
/api/v1/users—— 最直观 - Query 参数：
/api/users?version=1—— 不推荐，容易被忽略 - Header：
Accept: application/vnd.myapp.v1+json—— 更优雅，但调用方麻烦
真相： 选一种方式，保持一致就行。没有绝对的最佳，只有适不适合。
谎言五：RESTful 是万能的
很多人把 RESTful 当成银弹，仿佛不用 RESTful 就是落后。
但实际上：
- 实时推送 → WebSocket
- 复杂查询 → GraphQL
- 文件传输 → FTP/SFTP
- 异步任务 → 消息队列 + 回调
真相： 技术选型要务实，不是所有场景都适合 REST。强扭的瓜不甜，强用的 REST 不香。
谎言六：API 文档不重要
有些人觉得代码写完就完事儿了，文档？那是啥？能吃吗？
然后调用方骂骂咧咧地来问你："这个接口参数是啥？" "这个返回的是啥格式？" "这个错误码什么意思？"
你烦，调用方也烦。
真相： 文档就是 API 的一部分。好的文档能省掉一半的沟通成本。推荐用 Swagger/OpenAPI 自动生成，保证代码和文档同步。
谎言七：错误信息越详细越好
有些人啊，为了"用户体验"，错误信息写得跟小说似的：
{"error": "非常抱歉，您本次请求失败了。这是因为我们系统在处理您的请求时遇到了一些问题。具体来说，可能是由于网络波动、服务器负载过高或者是数据库连接异常导致的。我们已经记录了这个问题，技术团队正在紧急处理中。预计在接下来的几个工作小时内可以恢复。请您稍后再试，感谢您的理解与支持！"}
兄dei，我是程序员，我不需要你给我写散文。
真相： 错误信息要精准、可程序化。error_code + error_message + 解决方案，这就够了。
谎言八：分页用 offset 和 limit 就够了
很多人做分页就是：
GET /users?offset=0&limit=10
看起来没问题，但实际场景中：
- 数据有删除/更新时，会出现数据重复或跳过
- 深度分页性能差（offset 越大越慢）
更好的方案：
- 游标分页：
GET /users?cursor=eyJpZCI6MTB9&limit=10—— 基于 ID，性能好 - 时间分页：
GET /users?since=1640000000&limit=10—— 适合实时消息流
真相： 根据业务场景选分页方式，别一上来就 offset/limit。
谎言九：API 必须绝对安全
有些人做 API 安全跟做堡垒似的：
- 必须 HTTPS
- 必须签名
- 必须加密
- 必须验证码
结果呢？调用方被烦死，性能也上不去。
真相： 安全要分级：
- 公开数据 → 无需认证
- 用户数据 → 需要认证
- 敏感操作 → 需要签名 + 验证码
- 金融交易 → 多重验证
不是所有接口都需要武装到牙齿。
谎言十：好的 API 是一次性设计好的
有些人总想着一口气设计出完美的 API，然后用到天荒地老。
结果呢？需求变了，业务变了，API 不得不改。
真相： API 是演进的，不是设计出来的。先保证能用，再逐步优化。版本管理、废弃策略，这些才是重点。
总结：API 设计的正确姿势
说了这么多误区，那到底怎么设计 API？
核心原则：
- 简单直观 —— URL 让人一眼看懂是干啥的
- 语义明确 —— 状态码、错误码该用就用
- 文档同步 —— 代码改了什么，文档就改什么
- 版本管理 —— 向前兼容，向后兼容
- 安全分级 —— 合适的安全策略，而不是过度防护
- 可演进 —— 允许 API 迭代，不要追求一步到位
最后说一句：没有最好的 API，只有最合适的 API。
别被所谓的"最佳实践"绑住手脚，也别为了酷炫而酷炫。实用、简洁、可维护，这才是好 API 的标准。
好了，今天就先聊到这里。有什么想问的，欢迎来撩！
本文作者：小龙虾，一个在后端摸爬滚打多年的程序员 🦞
