写给后端同学的API设计指南：从“能用”到“好用”，你踩过几个坑？
咱们做开发的，谁没被奇葩的API接口“喂过翔”？有的接口命名像猜谜语，有的返回数据结构堪比俄罗斯套娃，还有的，你调用一次和调用十次，服务器状态都不一样，让人心惊胆战。
写代码久了，我发现一个道理：写一个“能用”的API很简单，但设计一个“好用”的API，真的是一门艺术，也是一项良心活。 它直接决定了前端同学（或者其他调用方）的工作幸福指数，也间接反映了我们后端开发者的专业素养。
今天不聊高深的架构，就想和大家掏心窝子聊聊API设计里那些老生常谈但又极其重要的话题：RESTful、幂等性、版本控制和安全性。希望能帮你避开一些我曾经踩过的坑。
一、 别把RESTful当成“四个动词”
很多新手，包括当年的我，都以为RESTful就是用GET查、POST增、PUT/PATCH改、DELETE删。没错，这是核心，但这只是“形”，还没到“神”。
RESTful的核心思想是**“资源（Resource）”**。你的API操作的一切都应该是资源。比如，一个用户、一篇博客、一张订单，都是资源。而URL（统一资源定位符）就是这个资源在互联网上的唯一“地址”。
所以，一个好的RESTful API，URL设计的应该是名词，而不是动词。
- 反例：
/getUserInfo?id=123、/createNewOrder - 正例：
/users/123、/orders
把HTTP动词和资源地址结合起来，才能体现出REST的优雅。这里我整理了一个表格，把最常用的HTTP方法、对应的操作和幂等性放在了一起，一目了然。
表格一：常用HTTP方法与CRUD操作对应表
| HTTP 方法 | 操作 | 幂等性 (Idempotency) | 常用场景与备注 |
|---|---|---|---|
| GET | 读取 (Read) | 是 | 最常用的查询操作。调用N次，结果都应一样（不考虑数据本身变化）。 |
| POST | 创建 (Create) | 否 | 用于创建新资源。连续调用两次，会创建两个资源，所以不幂等。 |
| PUT | 更新/替换 (Update/Replace) | 是 | 语义是“替换”。比如PUT /users/123，是把123号用户的所有信息替换成请求体里的内容。重复调用，结果不变。 |
| PATCH | 更新/修改 (Update/Modify) | 否 | 语义是“局部更新”。比如PATCH /users/123，只更新请求体里包含的字段（如只改个昵称）。严格来说它不幂等，但可以实现成幂等。 |
| DELETE | 删除 (Delete) | 是 | 删除指定资源。第一次调用成功删除，后续调用返回404（找不到），但从最终结果看，资源确实是“没了”，所以是幂等的。 |
敲黑板： PUT和PATCH的区别，面试常问，也是很多人容易混淆的地方。简单记：PUT是整体替换，PATCH是局部更新。
二、 幂等性：关键时刻的“安全网”
“幂等性”这个词听起来很学术，说白了就是：一个操作，你执行一次和执行N次，对系统的影响应该是一样的。
为什么要关注这个？想象一个支付场景：用户点击“支付”按钮，请求发到后端。但因为网络抖动，客户端没收到成功响应，于是它自动重试了。如果你的支付接口不幂等，用户可能就被扣了两次钱！这种事故，想想都后怕。
如何保证幂等性？
最常见的方法是引入一个唯一的请求ID（Request ID）。
- 客户端：每次发起关键操作（如支付、下单）时，生成一个唯一的ID（比如UUID），放在请求头或请求体里。
- 服务端：
- 收到请求后，先去缓存（如Redis）或数据库里查这个Request ID是否存在。
- 如果存在，说明是重复请求，直接返回上一次的处理结果，不要执行业务逻辑。
- 如果不存在，正常处理业务逻辑，然后把Request ID和处理结果存起来（记得设置一个过期时间）。
这个机制就像一个“门卫”，能挡住所有重复的请求，是高可用服务必备的“安全网”。
三、 版本控制：给未来的自己留条后路
没有哪个API能一成不变。只要业务在发展，需求在迭代，API的变更就在所难免。
千万不要在旧的API上直接做破坏性修改！ 这会让正在使用旧版API的客户端直接崩溃。产品经理会找你，前端会“问候”你，老板会约谈你。
所以，从第一天起，就要有版本意识。常见的版本控制策略有三种，各有优劣。
表格二：API版本控制策略对比
| 策略 | 示例 | 优点 | 缺点 |
|---|---|---|---|
| 路径版本 (URL Path) | https://api.example.com/v1/users |
最直观，浏览器地址栏就能看出来，调试方便，认知成本低。 | 侵入性强，URL显得不那么“纯粹”。 |
| 查询参数 (Query Parameter) | https://api.example.com/users?version=v1 |
比较灵活，对URL的侵入性小。 | 不如路径版本直观，容易被忽略。 |
| 自定义请求头 (Custom Header) | Accept: application/vnd.example.api.v1+json |
REST理念的最佳实践。URL最干净，保持了资源的唯一性。 | 调试不方便（不能直接从浏览器看），需要借助工具，对调用方要求更高。 |
我的建议是： 对于大多数团队，路径版本（/v1/） 是最实用、最不容易出错的选择。虽然它不那么“原教旨主义”，但简单、清晰、直观的优点足以覆盖它的缺点。等你的团队和API生态系统都非常成熟了，再考虑请求头的方式也不迟。
四、 安全性：不是可选项，而是底线
API裸奔，等于把家门钥匙挂在门外。这里不展开讲复杂的攻防，只说几个最最基本的安全底线。
- 必须使用HTTPS：现在都2024年了，这个不用多说了吧？HTTPS可以防止你的数据在传输过程中被窃听和篡改。免费的SSL证书也很多，没理由不用。
- 身份认证 (Authentication)：明确“你是谁”。常见的
JWT (JSON Web Token)就是一个很好的选择。用户登录后，服务端签发一个Token给客户端，客户端在后续请求的Authorization头里带上这个Token。 - 权限控制 (Authorization)：明确“你能干什么”。即使通过了身份认证，也不是所有API都能调。管理员能删除用户，普通用户就不行。这需要在你的业务逻辑里做精细的权限判断。
- 数据校验 (Validation)：永远不要相信客户端传来的任何数据！对所有输入参数做严格的校验，包括类型、长度、格式、范围等。这能挡住绝大多数的SQL注入、XSS等攻击。
写在最后
设计一个优秀的API，更像是在和未来的自己、和你的同事进行一场“跨时空的对话”。你现在多花一点心思，未来的维护成本就会指数级下降，团队协作也会顺畅得多。
当然，API设计远不止这些，还有统一的返回格式、错误处理、文档（Swagger/OpenAPI yyds!）等等。但今天聊的这几点，可以说是地基中的地基。
希望这篇文章能给你带来一些启发。如果你有更好的想法或者踩过更“惨”的坑，欢迎在评论区分享交流，我们一起进步，一起少掉点头发。
- 点赞
- 收藏
- 关注作者
评论（0）