文档教程知识库【免费下载链接】developer-roadmapInteractive roadmaps, guides and other educational content to help developers grow in their careers.项目地址https://gitcode.com/GitHub_Trending/de/developer-roadmap点击查看免费下载HTTPHypertext 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/jsonHTTP/1.1 200 OK Content-Type: application/json { id: 42, name: Alice, email: aliceexample.com }对应的curl命令curl -X GET https://api.example.com/api/v1/users/42POST创建资源或提交处理POST 用于向服务器提交数据最常见的用途是在集合资源下创建新资源也可以用于提交表单、触发复杂处理流程如搜索、计算等不适合其他方法的操作。语义将请求体body中的数据处理后在服务器上产生新资源或执行特定动作。响应创建成功后返回201 Created并通常通过Location响应头给出新资源的 URI。特点非幂等——重复提交同一 POST 请求可能会产生多个资源或多次副作用因此网络重试时需要额外谨慎详见下文幂等性章节。典型示例POST /api/v1/users Content-Type: application/json { name: Bob, email: bobexample.com }HTTP/1.1 201 Created Location: /api/v1/users/99 { id: 99, name: Bob, email: bobexample.com }对应的curl命令curl -X POST https://api.example.com/api/v1/users \ -H Content-Type: application/json \ -d {name:Bob,email:bobexample.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.smithexample.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.smithexample.com}DELETE删除资源DELETE 用于删除指定 URI 标识的资源。语义服务器删除目标资源若资源不存在部分规范约定返回404 Not Found但实现上也可以返回204 No Content表示删除操作已执行。响应成功通常返回204 No Content或200 OK若附带被删资源的描述。特点幂等——第一次删除后资源已不存在再次删除不应产生新的状态变化。典型示例DELETE /api/v1/users/42HTTP/1.1 204 No Content对应的curl命令curl -X DELETE https://api.example.com/api/v1/users/42PATCH部分更新资源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}方法语义速查表方法主要用途请求体幂等安全无副作用典型成功状态码GET读取资源通常无是是200 OKPOST创建/提交处理有否否201 CreatedPUT整体替换资源有是否200 OK / 201 CreatedDELETE删除资源通常无是否204 No ContentPATCH部分更新资源有不保证否200 OK / 204 No Content安全方法与幂等方法在设计 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 请求可能被缓存代理、爬虫或浏览器预取导致激活操作被意外重复触发多次。正确做法是把这类动作建模为 POSTPOST /api/v1/users/42/activate方法、CRUD 与资源建模HTTP 方法与数据库的 CRUD 操作存在经典的映射关系这是 Handling CRUD Operations in API Design 文档的核心内容无论是银行应用还是社交平台创建、读取、更新、删除数据的需求是通用的而 HTTP 方法恰好为这四种操作提供了标准语义。CRUD 操作HTTP 方法典型 URI 模式CreatePOSTPOST /usersReadGETGET /users/GET /users/{id}UpdatePUT / PATCHPUT /users/{id}/PATCH /users/{id}DeleteDELETEDELETE /users/{id}资源层级与方法的配合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 通过正确搭配方法与状态码来提升健壮性、可理解性和可调试性。方法典型成功状态码典型错误状态码GET200 OK404 Not Found资源不存在POST201 Created含 Location 头400 Bad Request请求体非法/ 409 Conflict冲突PUT200 OK / 201 Created / 204 No Content400 Bad Request / 404 Not FoundDELETE204 No Content / 200 OK404 Not Found / 405 Method Not AllowedPATCH200 OK / 204 No Content400 Bad Request / 422 Unprocessable Entity一个值得一提的细节是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 端点选择方法时建议遵循以下实践先问语义再定方法这个操作是读、写、替换还是删除不要因为顺手就一律使用 POST。资源读取用 GET状态变更用 POST完整替换用 PUT局部修改用 PATCH删除用 DELETE。保持幂等边界清晰PUT、DELETE 必须实现幂等POST 若涉及关键业务支付、下单务必引入幂等键机制并参考 Idempotency in API Design 中的设计思路。绝不把副作用放进 GETGET 可能被缓存、预取、爬虫触发任何会改变服务器状态的操作都应使用写方法。区分 PUT 与 PATCH客户端提交的是完整资源表示就用 PUT只改个别字段就用 PATCH避免全量替换带来的数据丢失风险。让状态码与方法语义对齐创建成功返回201 CreatedLocation删除成功返回204 No Content非法请求返回400/422资源不存在返回404方法不支持返回405Allow头。参考 REST 原则约束整体设计REST 的无状态、客户端-服务器、可缓存、统一接口等特征参见 REST Principles in API Design决定了方法的正确使用方式是 API 整体可扩展、可缓存、易互操作的前提。其他 HTTP 方法从常用到完整除了五大常用方法HTTP 规范还定义了若干辅助方法理解它们有助于设计更完整的 API方法语义HEAD与 GET 相同但响应不含响应体常用于探测资源是否存在、获取元信息OPTIONS查询服务器对指定 URI 支持的通信选项常与 CORS 预检请求配合使用TRACE回显客户端发送的请求用于诊断调试出于安全原因生产环境通常禁用CONNECT建立到目标的隧道连接多用于 HTTPS 代理场景在公开 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 的第一步。赞分享文档教程知识库【免费下载链接】developer-roadmapInteractive roadmaps, guides and other educational content to help developers grow in their careers.项目地址https://gitcode.com/GitHub_Trending/de/developer-roadmap点击查看免费下载相关推荐developer-roadmap API 设计指南深入理解 BFFBackend for Frontend模式developer roadmap API 设计指南深入理解 BFFBackend for Frontend模式 BFFBackend for Fron文档教程知识库developer-roadmap API 设计指南REST、SOAP、GraphQL 与 gRPC 四种 API 风格全解析developer roadmap API 设计指南REST、SOAP、GraphQL 与 gRPC 四种 API 风格全解析 APIApplication文档教程知识库Gradio REST API接口设计指南Gradio REST API接口设计指南 概述 Gradio 是一个强大的机器学习模型部署框架其 REST API 设计遵循现代 Web 标准提供了完整前端后端AI 应用创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考