RESTful API 设计规范与 HTTP 请求方法
🎯 引言
学完这篇文章,你能围绕资源设计接口,并正确区分读取、创建、替换与修改。
🧱 先确定资源,再确定操作
资源是接口对外管理的数据对象,例如用户、文章或文件。RESTful 风格常用名词路径表示资源,用方法表达动作:
| 需求 | 接口 | 成功结果 |
|---|---|---|
| 用户列表 | GET /users | 200,数组 |
| 用户详情 | GET /users/7 | 200,对象 |
| 创建用户 | POST /users | 201,新用户与地址 |
| 替换可编辑资料 | PUT /users/7 | 200 或 204 |
| 修改昵称字段 | PATCH /users/7 | 200 或 204 |
| 删除用户 | DELETE /users/7 | 204 |
复数名词是一种常见约定,关键是项目内一致。不要同时设计 /getUser、/users/query、/userInfo 来表示同一种读取操作。
📖 GET 只读取,不顺便修改
GET 可能被浏览器预加载、缓存或重复请求,不应触发删除、扣减等操作。下面的请求应该只返回用户信息:
GET /users/7 HTTP/1.1
Host: api.example.com
如果“浏览一次链接就删除用户”,错误点击或自动请求都可能产生副作用。删除应使用明确的方法,并先做权限检查。
🆕 POST 表示提交创建或执行操作
创建用户可以发送:
POST /users HTTP/1.1
Content-Type: application/json
{"name":"小明"}
服务器生成 ID 后返回 201 和 Location: /users/7。用户 ID 应由服务端或数据库控制,不能让客户端任意指定内部字段。
不适合简单增删改查的动作也可以建模成明确操作,例如 POST /reports/7/exports 创建一次导出记录。不要为了模仿名词路径而牺牲含义清晰。
🛠 PUT 与 PATCH 先约定字段语义
PUT 表示按契约替换目标表示,遗漏的可编辑字段是否清空要在文档中明确;PATCH 表示局部修改,未提交的字段通常保留。
PATCH /users/7 HTTP/1.1
Content-Type: application/json
{"name":"新名字"}
这份 PATCH 只改变名字,不应该顺便清空头像。null 和“字段缺失”也可以有不同含义,例如 null 表示清空,缺失表示不改,必须写进契约。
🔁 幂等描述重复后的效果
幂等指相同请求重复执行,对服务器最终状态的影响与执行一次相同。将名字设为“新名字”可以是幂等的;每次调用都给计数加 1 则不是。
PUT、DELETE 的语义要求幂等,但重复响应不必完全相同:第一次删除返回 204,第二次因记录不存在返回 404,资源仍然处于已删除状态。POST 默认不保证幂等,需要额外防重复设计。
不要把“方法叫 PUT”当成实现已经正确。如果处理函数每次都累加数值,它仍违背这个契约。
❓ 知识问答
Q1:PATCH 一定不幂等吗?
不一定。设置字段为固定值通常幂等,执行增加一次的操作可能不幂等,取决于补丁语义。
Q2:接口必须严格只有增删改查吗?
不必。应明确资源和动作,复杂操作可以通过创建任务等方式表达,避免晦涩命名。
Q3:DELETE 成功为什么不用返回完整对象?
如果调用者只关心是否完成,204 已足够。需要返回数据时也可约定 200,但必须与实际正文一致。
🧪 小练习
设计头像的查询、上传替换和删除接口,分别写出方法、路径、成功状态,以及重复请求后的预期效果。
// 请在这里编写代码或记录验证结果
