HTTP API 速查表
Node 24 的 fetch 用法与 HTTP API 契约参考，涵盖方法、状态码、媒体类型、缓存、重试、分页、认证和版本控制。
Node 24 打印为 1 页
资源与方法
GET /orders/ord-42 读取资源表示且不改变资源状态；安全且幂等 HEAD /orders/ord-42 只读取响应元数据，不返回响应内容；安全且幂等 POST /orders 让集合处理一个表示；常用于创建成员，本身不保证幂等 PUT /orders/ord-42 在已知目标创建或替换表示；幂等 PATCH /orders/ord-42 按补丁媒体类型定义的规则执行部分修改；本身不保证幂等 DELETE /orders/ord-42 请求删除目标；预期效果是幂等的 OPTIONS /orders 查询目标支持的通信选项；安全且幂等 Node 客户端
const response = await fetch('https://api.example.com/orders') 用 Node 24 的全局 fetch 发送 GET 请求 await fetch(url, { method: 'POST', headers: { 'content-type': 'application/json' }, body: JSON.stringify(order) }) 发送 JSON，并明确指定请求媒体类型 response.ok 检查状态码是否在 200–299 范围内 response.headers.get('content-type') 以不区分大小写的方式读取响应头 const data = await response.json() 一次性消费响应内容并解析为 JSON await fetch(url, { signal: AbortSignal.timeout(5000) }) 五秒后中止请求 成功响应
200 OK 返回成功的表示或操作结果 201 Created 说明请求已经创建资源 Location: /orders/ord-42 在 201 响应中标识新建资源 202 Accepted 说明处理已接受但尚未完成；还要定义客户端如何观察完成状态 204 No Content 说明操作成功且没有响应内容 客户端错误
400 Bad Request 拒绝语法、消息构造或请求输入有误的请求 401 Unauthorized 拒绝缺少认证或凭据无效的请求，并返回质询 403 Forbidden 拒绝调用方无权执行但服务端已经理解的请求 404 Not Found 说明资源不存在，或隐藏调用方不应发现的资源 409 Conflict 说明请求与资源当前状态冲突 412 Precondition Failed 拒绝条件请求头求值为假的请求 422 Unprocessable Content 拒绝格式正确但指令无法处理的内容 服务端压力
429 Too Many Requests 说明该客户端已超过速率限制 500 Internal Server Error 说明服务端发生意外故障，不暴露内部细节 502 Bad Gateway 说明网关收到无效的上游响应 503 Service Unavailable 说明服务因过载或维护而暂时不可用 504 Gateway Timeout 说明网关未能及时收到上游响应 Retry-After: 120 在 429 或 503 后要求客户端等待 120 秒 表示格式
Content-Type: application/json 标明请求或响应内容的媒体类型 Accept: application/json 请求 JSON 响应表示 Content-Type: application/problem+json 标明 RFC 9457 问题详情文档 406 Not Acceptable 说明可用响应表示都不满足 Accept 415 Unsupported Media Type 拒绝格式或编码不受支持的请求内容 Content-Encoding: gzip 声明表示数据采用 gzip 内容编码 缓存
Cache-Control: no-store 要求缓存不要存储此响应 Cache-Control: private, max-age=60 允许私有缓存在响应新鲜期间复用它 Cache-Control: public, max-age=300 在契约允许时，让共享缓存复用响应 ETag: "order-7" 为选定表示附加不透明验证器 If-None-Match: "order-7" 用实体标签重新验证缓存的表示 304 Not Modified 复用缓存的表示；该响应不携带消息内容 Vary: Accept-Encoding 为接受不同编码的请求保留独立缓存条目 并发与重试
If-Match: "order-7" 仅在当前强实体标签匹配时执行修改 428 Precondition Required 要求客户端发送条件请求 idempotent: GET, HEAD, OPTIONS, PUT, DELETE 重复相同请求的预期效果与发送一次相同 not inherently idempotent: POST, PATCH 仅当应用契约提供安全去重语义时重试 Idempotency-Key: 7b1d7a90 同一逻辑操作的每次重试都复用应用定义的同一键和请求体 分页
GET /orders?status=pending 用文档明确的查询参数过滤集合 GET /orders?limit=50 请求有界的页大小；服务端仍要强制执行上限 GET /orders?cursor=eyJpZCI6Im9yZC00MiJ9 用绑定到相同过滤条件与排序的不透明游标继续读取 ORDER BY created_at DESC, id DESC 用唯一决胜字段形成完整且确定的分页顺序 Link: </orders?cursor=next>; rel="next" 给出下一页目标，客户端无需自行构造 认证与 CORS
Authorization: Bearer ACCESS_TOKEN 通过 TLS 向资源服务器发送 Bearer 访问令牌 WWW-Authenticate: Bearer realm="orders" 质询缺少或使用无效 Bearer 凭据的请求 Origin: https://app.example.com 标明发起请求的浏览器源；它不能认证用户 Access-Control-Allow-Origin: https://app.example.com 允许该源的浏览器代码读取跨源响应 Access-Control-Allow-Methods: GET, POST 列出预检响应允许的方法 Access-Control-Allow-Headers: Authorization, Content-Type 列出预检允许的非简单请求头 Access-Control-Allow-Credentials: true 只与明确允许的源搭配，以准许浏览器携带凭据 契约演进
GET /api/v1/orders 通过路径选择主版本 API 契约 Accept: application/vnd.example.orders.v2+json 通过内容协商选择版本化表示 Vary: Accept 防止缓存混用由 Accept 选择的不同表示 Deprecation: @1798761600 用 RFC 9651 日期标明弃用时刻，但不改变当前行为 Sunset: Thu, 01 Jul 2027 00:00:00 GMT 标明资源预计何时停止响应 契约检查
import assert from 'node:assert/strict' 在 API 契约测试中使用 Node 严格断言 assert.equal(response.status, 201) 锁定操作的确切成功状态码 assert.equal(response.headers.get('location'), '/orders/ord-42') 锁定必需的响应头 assert.deepEqual(await response.json(), expectedBody) 锁定契约承诺的响应表示 assert.equal(await response.text(), '') 验证 204 响应没有内容 assert.equal(response.headers.get('etag'), expectedEtag) 锁定条件请求所需的验证器