企业官网建设流程全解析

• 文档
• 教程
• 知识库

HTTP（Hypertext Transfer Protocol，超文本传输协议）方法定义了客户端可以向服务器发起的请求类型，是 API 设计中客户端与服务端交互的骨架。本文以 HTTP Methods 主题文档为核心，系统讲解 GET、POST、PUT、DELETE、PATCH 等常用方法的核心语义、安全性与幂等性，并结合本仓库中的幂等性、HTTP 状态码、CRUD 等关联文档以及真实源码调用，帮助你掌握如何为接口选择正确的方法，设计出健壮、可读、易调试的 API。读完本文，你将具备独立设计 RESTful 资源接口、正确使用方法语义并规避常见误用（如用 GET 修改状态、DELETE 不幂等等）的实战能力。

什么是 HTTP 方法

HTTP 方法是 HTTP 协议中请求消息的组成部分，它向服务器声明"客户端希望执行什么类型的操作"。在 API 设计中，方法定义了客户端与服务器之间的交互框架：同一个资源 URI 可以通过不同的方法表达完全不同的语义，从而让一套接口覆盖增、删、改、查等多种业务场景。

在 RESTful 风格的 API 中，方法通常与"资源"（Resource）配合使用：URI 标识资源，方法表达对资源执行的操作。正如 RESTful APIs 文档所述，RESTful API 正是"利用 HTTP 方法来读取、更新和删除数据"，并提供统一、可扩展的接口约定。

在 HTTP in API Design 文档中也有强调：HTTP 决定了请求与响应应如何构造和处理，它规定了端点如何定义、数据如何传输、应使用哪些状态码来表达特定场景。方法正是这套规范中最核心的语义载体。

五大核心方法详解

API 设计中最常使用的 HTTP 方法有五个：GET、POST、PUT、DELETE 和 PATCH。每种方法都表示一种不同类型的请求，使客户端能够以多种方式与 API 端点交互。

GET：读取资源

GET 用于从服务器读取资源，是使用频率最高的方法。

• 语义：只请求资源的表示（representation），不应在服务器上产生任何副作用。
• 响应：成功时返回资源内容，通常为 JSON/XML，配合200 OK状态码。
• 特点：请求可被缓存、可被浏览器直接访问、可重复发送。

典型示例：

GET /api/v1/users/42 Accept: application/json

HTTP/1.1 200 OK Content-Type: application/json { "id": 42, "name": "Alice", "email": "alice@example.com" }

对应的curl命令：

curl -X GET https://api.example.com/api/v1/users/42

POST：创建资源或提交处理

POST 用于向服务器提交数据，最常见的用途是在集合资源下创建新资源，也可以用于提交表单、触发复杂处理流程（如搜索、计算）等不适合其他方法的操作。

• 语义：将请求体（body）中的数据处理后，在服务器上产生新资源或执行特定动作。
• 响应：创建成功后返回201 Created，并通常通过Location响应头给出新资源的 URI。
• 特点：非幂等——重复提交同一 POST 请求可能会产生多个资源或多次副作用，因此网络重试时需要额外谨慎（详见下文"幂等性"章节）。

典型示例：

POST /api/v1/users Content-Type: application/json { "name": "Bob", "email": "bob@example.com" }

HTTP/1.1 201 Created Location: /api/v1/users/99 { "id": 99, "name": "Bob", "email": "bob@example.com" }

对应的curl命令：

curl -X POST https://api.example.com/api/v1/users \ -H "Content-Type: application/json" \ -d '{"name":"Bob","email":"bob@example.com"}'

PUT：整体替换资源

PUT 用于完整替换指定 URI 上的资源，或在已知 URI 下创建资源。

• 语义：请求体应包含资源的完整表示，服务器用其整体替换目标资源；若目标不存在，部分实现允许按此 URI 创建。
• 响应：更新成功返回200 OK，创建成功返回201 Created，无内容更新可返回204 No Content。
• 特点：幂等——无论调用一次还是多次，服务器最终状态一致（详见下文"幂等性"章节）。

典型示例：

PUT /api/v1/users/42 Content-Type: application/json { "id": 42, "name": "Alice Smith", "email": "alice.smith@example.com" }

对应的curl命令：

curl -X PUT https://api.example.com/api/v1/users/42 \ -H "Content-Type: application/json" \ -d '{"id":42,"name":"Alice Smith","email":"alice.smith@example.com"}'

DELETE：删除资源

DELETE 用于删除指定 URI 标识的资源。

• 语义：服务器删除目标资源；若资源不存在，部分规范约定返回404 Not Found，但实现上也可以返回204 No Content表示"删除操作已执行"。
• 响应：成功通常返回204 No Content或200 OK（若附带被删资源的描述）。
• 特点：幂等——第一次删除后资源已不存在，再次删除不应产生新的状态变化。

典型示例：

DELETE /api/v1/users/42

HTTP/1.1 204 No Content

对应的curl命令：

curl -X DELETE https://api.example.com/api/v1/users/42

PATCH：部分更新资源

PATCH 用于对资源进行部分修改，只提交需要变更的字段，而不是像 PUT 那样提交完整表示。

• 语义：请求体描述"变更指令"（通常为 JSON Patch 或部分字段的 JSON），服务器据此局部修改资源。
• 响应：成功返回200 OK（携带更新后的资源）或204 No Content。
• 特点：从语义上说，PATCH不保证幂等（取决于补丁指令的具体实现），这是它与 PUT 的关键区别。

典型示例：

PATCH /api/v1/users/42 Content-Type: application/json { "name": "Alice Wang" }

对应的curl命令：

curl -X PATCH https://api.example.com/api/v1/users/42 \ -H "Content-Type: application/json" \ -d '{"name":"Alice Wang"}'

方法语义速查表

安全方法与幂等方法

在设计 API 时，方法选择的关键依据是两条核心性质：安全性（Safe）与幂等性（Idempotent）。

• 安全方法：执行后不改变服务器状态、不产生副作用的方法。规范上只有 GET、HEAD、OPTIONS、TRACE 属于安全方法。安全的含义不是"响应内容不变"，而是"不会修改服务器资源状态"。
• 幂等方法：多次发送同一请求与发送一次请求的效果相同（服务器最终状态一致）。PUT、DELETE 是典型幂等方法；GET 同时满足安全与幂等；POST 两者皆不满足。

正如 Idempotency in API Design 文档所强调的：幂等性是 API 可靠性的基石，它允许客户端在网络不稳定时安全重试而不会产生副作用，降低分布式系统的复杂度。该文档特别指出，幂等性"通常适用于 RESTful API 中的PUT、DELETE，有时也适用于POST"。

为什么幂等对重试至关重要

在网络环境不稳定、请求超时时，客户端无法确定请求是否已被服务器处理，唯一稳妥的做法就是重试。此时：

• 使用 GET/PUT/DELETE，重复请求不会破坏数据；
• 使用 POST，重复请求可能产生多条重复记录（重复下单、重复扣款）。

对于确实需要保证幂等的 POST（如创建订单、支付），常见的工程方案是引入幂等键（Idempotency Key）：客户端为每个请求生成唯一标识（如 UUID），放在自定义请求头（例如Idempotency-Key）中；服务器记录已处理过的键，对相同键的重复请求直接返回首次的结果，而不重新执行副作用。这是"POST 有时也需要幂等"的典型落地方式。

安全方法的一个反例陷阱

一个常见误用是"用 GET 修改状态"，例如：

GET /api/v1/users/42/activate

这违背了 GET 的安全语义：GET 请求可能被缓存代理、爬虫或浏览器预取，导致"激活"操作被意外重复触发多次。正确做法是把这类动作建模为 POST：

POST /api/v1/users/42/activate

方法、CRUD 与资源建模

HTTP 方法与数据库的 CRUD 操作存在经典的映射关系，这是 Handling CRUD Operations in API Design 文档的核心内容：无论是银行应用还是社交平台，创建、读取、更新、删除数据的需求是通用的，而 HTTP 方法恰好为这四种操作提供了标准语义。

资源层级与方法的配合

URI 设计（参见 URI Design in API）利用 URL 的层级结构组织资源，而方法在此基础上表达操作：

/users GET -> 列出用户（可配合过滤、分页） /users POST -> 创建用户 /users/{id} GET -> 读取单个用户 /users/{id} PUT -> 整体替换用户 /users/{id} PATCH -> 部分更新用户 /users/{id} DELETE -> 删除用户 /users/{id}/orders GET -> 读取该用户的订单集合

其中{id}是路径参数（Path Parameter），用于把可变数据嵌入 URI；查询参数（Query Parameter）则用于过滤、排序或选择返回字段，详见 URL, Query & Path Parameters 文档。

方法与状态码的配合

HTTP 方法决定了"做什么"，状态码则告诉客户端"结果如何"。二者必须协同使用——HTTP Status Codes 文档指出，状态码是三位数字，第一位数字定义了响应的类别（1xx 信息、2xx 成功、3xx 重定向、4xx 客户端错误、5xx 服务器错误）。高效的 API 通过正确搭配方法与状态码来提升健壮性、可理解性和可调试性。

一个值得一提的细节是405 Method Not Allowed：当客户端对某个 URI 使用了该资源不支持的方法时返回，同时应通过Allow响应头列出该 URI 支持的方法集合，帮助客户端自我纠正。

仓库源码中的真实 HTTP 调用：实践佐证

本仓库虽然是"开发者成长路线图"内容仓库，但其工具脚本本身就是以 HTTP 方法消费第三方 API 的真实示例，可以作为上文语义的落地佐证。

GET：拉取官方路线图数据

scripts/sync-content-to-repo.ts 使用 Node.js 内置的fetch发起 GET 请求，从 roadmap.sh 拉取路线图主题列表与官方路线图数据：

// scripts/sync-content-to-repo.ts const path = `https://roadmap.sh/api/v1-list-official-roadmap-topics/${roadmapId}?secret=${secret}`; const response = await fetch(path);

这段代码展示了 GET 方法的两个典型特征：不带请求体、通过查询参数（query parameters）传递筛选与鉴权信息（secret），与上文"GET 用于读取资源、查询参数用于筛选"的语义完全一致。

GET：清理孤立内容时的只读探测

scripts/cleanup-orphaned-content.ts 同样用 GET 探测官方路线图接口：

const response = await fetch( `https://roadmap.sh/api/v1-official-roadmap/${slug}`, );

该脚本通过读取响应来比对内容，其只读性质正体现了"GET 不产生副作用、可安全重复调用"的设计原则——在自动化脚本中反复探测而不用担心破坏远端状态。

这两处源码提醒我们：即使不使用重量级 HTTP 客户端库，方法语义依然是不变的规范；正确地选择方法（只读操作用 GET、状态变更用 POST/PUT/DELETE）在服务端与客户端两侧都应被一致遵守。

选择方法时的最佳实践

综合本仓库各关联文档的要点，在为 API 端点选择方法时，建议遵循以下实践：

1. 先问语义，再定方法：这个操作是读、写、替换还是删除？不要因为"顺手"就一律使用 POST。资源读取用 GET，状态变更用 POST，完整替换用 PUT，局部修改用 PATCH，删除用 DELETE。
2. 保持幂等边界清晰：PUT、DELETE 必须实现幂等；POST 若涉及关键业务（支付、下单），务必引入幂等键机制，并参考 Idempotency in API Design 中的设计思路。
3. 绝不把副作用放进 GET：GET 可能被缓存、预取、爬虫触发，任何会改变服务器状态的操作都应使用写方法。
4. 区分 PUT 与 PATCH：客户端提交的是完整资源表示就用 PUT；只改个别字段就用 PATCH，避免全量替换带来的数据丢失风险。
5. 让状态码与方法语义对齐：创建成功返回201 Created+Location，删除成功返回204 No Content，非法请求返回400/422，资源不存在返回404，方法不支持返回405+Allow头。
6. 参考 REST 原则约束整体设计：REST 的"无状态、客户端-服务器、可缓存、统一接口"等特征（参见 REST Principles in API Design）决定了方法的正确使用方式是 API 整体可扩展、可缓存、易互操作的前提。

其他 HTTP 方法：从常用到完整

除了五大常用方法，HTTP 规范还定义了若干辅助方法，理解它们有助于设计更完整的 API：

在公开 API 中，HEAD 常用于健康检查与资源探测，OPTIONS 在跨域场景（CORS）中由浏览器自动触发，TRACE 与 CONNECT 一般不建议对外暴露，避免被利用进行攻击面探测。

总结

HTTP 方法是 API 设计中最基础也最重要的语义工具：GET 读取、POST 创建、PUT 整体替换、DELETE 删除、PATCH 局部更新。正确选法方法的关键在于理解安全性（GET/HEAD/OPTIONS 无副作用）与幂等性（PUT/DELETE 可安全重试，POST 需借助幂等键），并让方法、URI、状态码三者协同一致。这套知识不仅适用于设计 RESTful API（参见 RESTful APIs 与 Building JSON & RESTful APIs），也适用于编写消费 API 的客户端代码——正如本仓库 scripts 目录下的同步脚本所示。掌握方法语义，是走向健壮、可调试、易维护 API 的第一步。

• 文档
• 教程
• 知识库