HTTP Method
Method 是什么
先建立最基础的模型。从语义层面看,一个 HTTP Request 可以先关注:
Method + Path + Header + Body其中 Method 可以先理解为客户端希望对目标资源执行的动作。例如 GET /targets/1 表示请求读取 /targets/1 所标识的资源。
HTTP Method 和 CRUD 有常见对应关系,但两者并非严格等价。例如 POST 也可以表示提交任务或触发处理,并不一定创建资源。
GET → Read
POST → Create(常见用法之一)
PUT/PATCH → Update
DELETE → DeleteGET
GET 表示获取资源的当前表示。例如 GET /targets 通常读取 Target 集合,而 GET /targets/1 读取 ID 为 1 的单个 Target。
假设服务器中存在:
Target: 1
name = "google"
address = "https://google.com"
Target: 2
name = "github"
address = "https://github.com"请求 GET /targets 时,服务器可以返回 JSON 数组:
HTTP/1.1 200 OK
Content-Type: application/json
[
{
"id": 1,
"name": "google",
"address": "https://google.com"
},
{
"id": 2,
"name": "github",
"address": "https://github.com"
}
]http如果请求 GET /targets/1,则只返回 ID 为 1 的资源;资源不存在时通常返回 404 Not Found。
GET 是安全且幂等的方法:“安全”表示客户端请求的目标不是修改服务器状态;“幂等”表示多次相同请求的预期效果与一次相同。
POST
POST 表示客户端向目标资源提交数据,请服务器按照该资源的语义进行处理。在本项目中,它用于向集合创建一个新 Target:
POST /targets
Content-Type: application/json
{
"name": "google",
"address": "https://google.com"
}http创建成功后通常返回 201 Created 和创建后的资源,也可以通过 Location 响应头告诉客户端新资源的 URI。
设计资源风格的 API 时,一般使用 POST /targets,而不是 POST /createTarget,因为 Method 已经表达了操作语义。不过这是一种常见 API 设计方式,不是 HTTP 协议强制规定。
POST 通常不是幂等方法:重复发送同一个创建请求,可能创建多个不同资源。
PUT
PUT 通常表示:
用客户端提供的完整表示替换目标资源的当前表示。
例如客户端发送:
PUT /targets/1
Content-Type: application/json
{
"name": "google",
"address": "https://google.com"
}http则服务器中的资源会被完整替换为:
{
"id": 1,
"name": "google",
"address": "https://google.com"
}jsonPUT 是幂等方法:多次发送相同 PUT 请求,其预期服务器状态与发送一次相同。在 sentinel-go 当前约定中,更新不存在的 ID 返回 404 Not Found;HTTP 标准也允许某些 API 使用 PUT 创建指定 URI 的资源,因此具体行为需要在接口契约中写清楚。
PATCH
PATCH 也表示更新。与 PUT 的完整替换不同,PATCH 请求体描述要应用到资源的一组局部修改,因此通常只提供需要变化的字段。
例如客户端发送:
PATCH /targets/1
Content-Type: application/json
{
"name": "bing"
}http更新后的资源可能是:
{
"id": 1,
"name": "bing",
"address": "https://google.com"
}jsonPUT 和 PATCH 成功后可以返回更新后的资源和 200 OK,也可以在不返回正文时使用 204 No Content;具体选择应保持一致并写入接口契约。PATCH 不保证天然幂等,其幂等性取决于补丁格式和操作语义。
DELETE
DELETE 用于删除目标资源。当客户端发送 DELETE /targets/{id} 时,就是请求删除该 ID 对应的 Target;成功且不返回正文时通常使用 204 No Content,资源不存在时通常返回 404 Not Found。
DELETE 是幂等方法。这里的“幂等”指多次相同请求的预期服务器状态与执行一次相同,而不是要求每次响应状态码完全相同;第一次删除可能返回 204,再次删除可能返回 404。
安全性与幂等性速查
| Method | 安全 | 幂等 | 当前项目中的常见用途 |
|---|---|---|---|
| GET | 是 | 是 | 查询 Target |
| POST | 否 | 通常否 | 创建 Target |
| PUT | 否 | 是 | 完整替换 Target |
| PATCH | 否 | 不一定 | 局部修改 Target |
| DELETE | 否 | 是 | 删除 Target |
参考资料
知识关联
1 反向链接 · 0 提及笔记反向链接1
提及笔记0
暂未引用其他笔记