HTTP 方法

HTTP - 方法

HTTP 定义了一组请求方法，用于指示对给定资源要执行的期望动作。这些方法名称区分大小写，并且必须使用大写形式。虽然常用方法集是明确定义的，但可以扩展。每种方法都有特定的语义，包括安全（safety）和幂等（idempotency）等属性。

安全（Safety）： 安全方法是指不改变服务器状态的 HTTP 方法。本质上，它们用于只读操作。GET、HEAD、OPTIONS 和 TRACE 被定义为安全方法。

幂等（Idempotency）： 幂等方法意味着执行多次相同的请求会产生与单次请求相同的效果。GET、HEAD、PUT、DELETE、OPTIONS 和 TRACE 是幂等方法。POST 和 PATCH 通常不是幂等的。

序号	方法	描述与属性
1	GET	检索目标资源的表示。应该只检索数据，不对服务器产生其他影响。安全且幂等。
2	HEAD	与 GET 相同，但服务器响应中不能包含消息体。用于获取头部信息。安全且幂等。
3	POST	向指定的资源提交实体，通常会改变状态或产生副作用（例如，创建新资源、提交表单数据）。通常既不安全也不幂等。
4	PUT	用请求体替换目标资源的所有当前表示。如果资源不存在，PUT 可能会创建它。不安全，但幂等。
5	DELETE	删除指定的资源。不安全，但幂等。
6	PATCH	对资源应用部分修改。不安全，并且通常不幂等（取决于补丁的语义）。
7	CONNECT	建立一个通向目标资源（由主机名和端口标识）的隧道。主要用于通过 HTTP 代理进行 HTTPS 隧道连接。既不安全也不幂等。
8	OPTIONS	描述目标资源或服务器可用的通信选项（例如，允许的方法、CORS 头部）。安全且幂等。
9	TRACE	沿目标资源的路径执行消息环回测试。用于调试。安全且幂等，但出于安全考虑（XST），通常在生产服务器上禁用。

GET 方法

GET 方法请求指定资源的表示。数据可以通过 URL 的查询字符串传递。GET 请求应该是安全和幂等的。它们可以被缓存和收藏。

客户端请求：

GET /products?category=electronics&page=1 HTTP/1.1
Host: api.example.com
User-Agent: MyClient/1.0
Accept: application/json

服务器响应（示例）：

HTTP/1.1 200 OK
Date: Tue, 22 Feb 2022 10:00:00 GMT
Server: MyAPI-Server/1.2
Content-Type: application/json; charset=utf-8
Content-Length: 256
Cache-Control: max-age=60

{
  "page": 1,
  "category": "electronics",
  "items": [
    { "id": 101, "name": "Laptop" },
    { "id": 102, "name": "Keyboard" }
  ]
}

HEAD 方法

HEAD 方法与 GET 相同，但服务器不得返回消息体。它用于检索资源的元数据（头部），例如 Content-Type、Content-Length 或 Last-Modified 日期，而无需传输资源本身。对于检查资源是否存在或是否已修改很有用。

客户端请求：

HEAD /documents/report.pdf HTTP/1.1
Host: www.example.com
User-Agent: MyClient/1.0

服务器响应（示例）：

HTTP/1.1 200 OK
Date: Tue, 22 Feb 2022 10:05:00 GMT
Server: WebServerX/2.0
Content-Type: application/pdf
Content-Length: 1024567
Last-Modified: Mon, 21 Feb 2022 15:30:00 GMT

(No message body)

POST 方法

POST 方法用于向指定资源提交要处理的数据。这可能导致创建新资源或更新现有资源，或在服务器上进行其他处理。POST 请求通常包含包含数据的消息体。POST 既不安全也不幂等。

客户端请求（使用 JSON 创建新用户）：

POST /api/users HTTP/1.1
Host: api.example.com
User-Agent: MyClient/1.0
Content-Type: application/json; charset=utf-8
Content-Length: 42
Accept: application/json

{
  "name": "Jane Doe",
  "email": "jane@example.com"
}

服务器响应（示例，指示资源创建）：

HTTP/1.1 201 Created
Date: Tue, 22 Feb 2022 10:10:00 GMT
Server: MyAPI-Server/1.2
Content-Type: application/json; charset=utf-8
Content-Length: 65
Location: /api/users/123

{
  "id": 123,
  "name": "Jane Doe",
  "email": "jane@example.com"
}

PUT 方法

PUT 方法请求将随附的实体存储在提供的 Request-URI 下。如果 Request-URI 指向已存在的资源，则应将随附的实体视为源服务器上资源的修改版本。如果 Request-URI 不指向现有资源，并且该 URI 可以由请求用户代理定义为新资源，则源服务器可以使用该 URI 创建资源。PUT 是幂等的，但不安全。

客户端请求（更新或创建特定用户）：

PUT /api/users/123 HTTP/1.1
Host: api.example.com
User-Agent: MyClient/1.0
Content-Type: application/json; charset=utf-8
Content-Length: 50
Accept: application/json

{
  "name": "Jane Smith",
  "email": "jane.smith@example.com"
}

服务器响应（示例，如果更新则为 200 OK，如果创建则为 201 Created，如果更新且不返回消息体则为 204 No Content）：

HTTP/1.1 200 OK
Date: Tue, 22 Feb 2022 10:15:00 GMT
Server: MyAPI-Server/1.2
Content-Type: application/json; charset=utf-8
Content-Length: 73

{
  "id": 123,
  "name": "Jane Smith",
  "email": "jane.smith@example.com",
  "updatedAt": "2022-02-22T10:15:00Z"
}

DELETE 方法

DELETE 方法删除指定的资源。它是幂等的（删除不存在的资源或多次删除一个资源应与成功删除一次达到相同的状态），但不安全。

客户端请求：

DELETE /api/users/123 HTTP/1.1
Host: api.example.com
User-Agent: MyClient/1.0
Authorization: Bearer <token>

服务器响应（示例，成功则为 200 OK 或 204 No Content，如果删除是异步的则为 202 Accepted）：

HTTP/1.1 204 No Content
Date: Tue, 22 Feb 2022 10:20:00 GMT
Server: MyAPI-Server/1.2

(No message body)

PATCH 方法

PATCH 方法用于对资源应用部分修改。与替换整个资源的 PUT 不同，PATCH 只修改指定的部分。补丁文档的格式由 Content-Type 头部指定（例如，application/json-patch+json、application/merge-patch+json）。PATCH 不安全，并且通常不幂等（其幂等性取决于补丁文档的语义）。

客户端请求（使用 JSON 合并补丁部分更新用户电子邮件）：

PATCH /api/users/123 HTTP/1.1
Host: api.example.com
User-Agent: MyClient/1.0
Content-Type: application/merge-patch+json
Content-Length: 32
Accept: application/json
Authorization: Bearer <token>

{
  "email": "new.email@example.com"
}

服务器响应（示例，如果更新则为 200 OK 并返回更新后的资源，或为 204 No Content）：

HTTP/1.1 200 OK
Date: Tue, 22 Feb 2022 10:25:00 GMT
Server: MyAPI-Server/1.2
Content-Type: application/json; charset=utf-8
Content-Length: 80

{
  "id": 123,
  "name": "Jane Smith",
  "email": "new.email@example.com",
  "updatedAt": "2022-02-22T10:25:00Z"
}

CONNECT 方法

CONNECT 方法建立一个通往目标资源（通常是主机名和端口）标识的服务器的隧道。它主要用于通过 HTTP 代理启用 HTTPS 通信。一旦隧道建立（由 200 Connection established 响应指示），客户端就可以通过代理与目标服务器启动 TLS 握手。

客户端请求（向代理）：

CONNECT www.secure-example.com:443 HTTP/1.1
Host: www.secure-example.com:443
User-Agent: MyBrowser/1.0
Proxy-Authorization: Basic <credentials_for_proxy_if_needed>

代理服务器响应：

HTTP/1.1 200 Connection established
Proxy-Agent: MyProxy/1.0

(No message body. After this, encrypted TLS traffic flows through the tunnel.)

OPTIONS 方法

OPTIONS 方法请求有关目标资源或服务器可用通信选项的信息。客户端可以指定 URL 或星号 (*) 来获取服务器范围的选项。常见用例包括检查支持哪些 HTTP 方法或用于 CORS（跨域资源共享）预检请求。

客户端请求：

OPTIONS /api/users/123 HTTP/1.1
Host: api.example.com
User-Agent: MyClient/1.0
Access-Control-Request-Method: PATCH
Access-Control-Request-Headers: Content-Type, Authorization

服务器响应（示例，用于 CORS）：

HTTP/1.1 204 No Content
Date: Tue, 22 Feb 2022 10:30:00 GMT
Server: MyAPI-Server/1.2
Allow: GET, HEAD, PUT, PATCH, DELETE, OPTIONS
Access-Control-Allow-Origin: https://client.example.com
Access-Control-Allow-Methods: GET, PATCH, DELETE, OPTIONS
Access-Control-Allow-Headers: Content-Type, Authorization
Access-Control-Max-Age: 86400

(No message body for 204, or a body for 200 OK with general server options)

TRACE 方法

TRACE 方法执行一个消息环回测试，将接收到的请求回显给客户端。这可用于调试，以查看中间代理是否对请求进行了任何更改。出于对跨站追踪（XST）等安全问题的担忧，TRACE 通常在生产服务器上禁用。

客户端请求：

TRACE / HTTP/1.1
Host: www.example.com
User-Agent: MyClient/1.0
Custom-Header: TestValue

服务器响应：

HTTP/1.1 200 OK
Date: Tue, 22 Feb 2022 10:35:00 GMT
Server: WebServerX/2.0
Content-Type: message/http

TRACE / HTTP/1.1
Host: www.example.com
User-Agent: MyClient/1.0
Custom-Header: TestValue
(Potentially other headers added by proxies, if any)