RESTful API 设计规范与 HTTP 请求方法

围绕资源设计接口,并正确区分读取、创建、替换与修改

🎯 引言

学完这篇文章,你能围绕资源设计接口,并正确区分读取、创建、替换与修改。

🧱 先确定资源,再确定操作

资源是接口对外管理的数据对象,例如用户、文章或文件。RESTful 风格常用名词路径表示资源,用方法表达动作:

需求接口成功结果
用户列表GET /users200,数组
用户详情GET /users/7200,对象
创建用户POST /users201,新用户与地址
替换可编辑资料PUT /users/7200 或 204
修改昵称字段PATCH /users/7200 或 204
删除用户DELETE /users/7204

复数名词是一种常见约定,关键是项目内一致。不要同时设计 /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,但必须与实际正文一致。


🧪 小练习

设计头像的查询、上传替换和删除接口,分别写出方法、路径、成功状态,以及重复请求后的预期效果。

// 请在这里编写代码或记录验证结果