imicola HTTP Method
HTTP Method

HTTP Method

933 字 · 约 2 分钟

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     → Delete

GET

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"
}
json

PUT 是幂等方法:多次发送相同 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"
}
json

PUT 和 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 提及笔记
局部关系图谱 悬停高亮 · 点击跳转