API 参数详解：Path、Query、Header 与 Body (2026)

API 参数详解：Path、Query、Header 和 Body

你发出的每一个 API 请求都通过参数向服务器传递信息。无论是获取用户数据、过滤搜索结果还是提交表单，参数都是客户端告知服务器“要做什么”的方式。理解四种主要的参数类型、各自的使用场景以及它们如何协同工作，是使用任何 REST API 的基础。

本指南通过实际案例、对比表和可立即应用的佳实践，深入剖析每一种参数类型。

四种 API 参数类型

参数类型	位置	用途	示例
Path	URL 路径	标识特定资源	/users/42
Query	URL 中 ? 之后	过滤、排序、分页	?status=active&page=2
Header	HTTP 请求头	认证、内容类型、元数据	Authorization: Bearer token
Body	请求体	发送数据负载	{"name": "Alice"}

每种类型都有其独特用途。混淆使用会导致 API 设计混乱、安全隐患以及调试困难。让我们逐一详细了解。

Path 参数 (路径参数)

Path 参数直接嵌入在 URL 路径中。它们用于标识特定的资源或集合中的嵌套资源。

语法

Path 参数表现为 URL 中的动态段，在 API 文档中通常用花括号包裹：

GET /api/v1/users/{userId}
GET /api/v1/users/{userId}/orders/{orderId}

实际示例

# 获取 ID 为 42 的用户
curl https://api.example.com/v1/users/42

# 获取属于用户 42 的订单 789
curl https://api.example.com/v1/users/42/orders/789

何时使用 Path 参数

• 用于标识 特定资源（如某个用户、产品或订单）
• 用于表达 层级关系（如某篇文章下的评论）
• 当该参数对端点（Endpoint）而言是 必填 项时

常见错误

• 将 Path 参数用于可选值（应使用 Query 参数）
• 在 URL 路径中放置敏感数据（会被记录在服务器日志和浏览器历史记录中）
• 嵌套层次过深，超过 2-3 层（如 /a/{id}/b/{id}/c/{id}/d/{id}）

Query 参数 (查询参数)

Query 参数出现在 URL 的 ? 之后，并由 & 分隔。它们用于过滤、排序、分页和其他可选的修饰操作。

语法

GET /api/v1/products?category=electronics&sort=price&order=asc&page=1&limit=20

实际示例

# 搜索“工程”部门中状态为“活跃”的用户，第 2 页
curl "https://api.example.com/v1/users?status=active&department=engineering&page=2&limit=25"

# 按价格范围过滤产品
curl "https://api.example.com/v1/products?min_price=10&max_price=100&in_stock=true"

常见 Query 参数模式

模式	示例	用途
分页	?page=2&limit=20	在大型数据集中导航
过滤	?status=active&role=admin	缩小结果范围
排序	?sort=created_at&order=desc	控制结果顺序
搜索	?q=search+term	全文搜索
字段选择	?fields=id,name,email	减小响应体积
展开	?expand=orders,profile	包含关联资源

何时使用 Query 参数

• 用于修改数据返回方式的 可选 参数
• 用于 过滤、排序 和 分页
• 用于 搜索查询
• 当端点在没有该参数时也能正常工作（存在合理的默认值）

最佳实践

# 正确：描述性的参数名，带有合理的默认值
GET /api/v1/orders?status=pending&sort=created_at&order=desc&page=1&per_page=20

# 错误：隐晦的单字母名称
GET /api/v1/orders?s=p&o=c&d=d&p=1&n=20

Header 参数 (请求头参数)

Header 参数是 HTTP 请求头中发送的键值对。它们携带的是关于请求本身的元数据，而非业务数据。

语法

GET /api/v1/users HTTP/1.1
Host: api.example.com
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
Content-Type: application/json
Accept: application/json
X-Request-ID: 550e8400-e29b-41d4-a716-446655440000

实际示例

# 使用内容协商进行的身份验证请求
curl -X GET https://api.example.com/v1/users \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Accept: application/json" \
  -H "X-API-Version: 2026-01-01"

标准请求头 vs 自定义请求头

Header	类型	用途
Authorization	标准	身份验证凭据
Content-Type	标准	请求体的格式
Accept	标准	期望的响应格式
Cache-Control	标准	缓存指令
X-Request-ID	自定义	请求追踪
X-API-Version	自定义	API 版本选择
X-Rate-Limit-Remaining	自定义	频率限制信息（响应中）

何时使用 Header 参数

• 身份验证（API keys, bearer tokens, OAuth）
• 内容协商（Accept, Content-Type）
• 请求元数据（追踪 ID, 客户端版本）
• API 版本控制（某些 API 使用 Header 而非 URL 路径）

安全提示

Header 是放置敏感认证数据的正确位置。与 Path 和 Query 参数不同，当导航到其他页面时，Header 不会被存储在浏览器历史记录、服务器访问日志（默认情况下）或 Referer 头中。

# 正确：API key 放在 Header 中
curl -H "Authorization: Bearer sk-abc123" https://api.example.com/data

# 错误：API key 放在 Query 字符串中（会被随处记录）
curl "https://api.example.com/data?api_key=sk-abc123"

Body 参数 (请求体参数)

Body 参数在 POST、PUT 和 PATCH 请求中携带主要的数据负载。根据 API 的不同，Body 格式可以是 JSON、表单数据 (form data)、XML 或二进制数据。

JSON Body (最常用)

curl -X POST https://api.example.com/v1/users \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -d '{
    "name": "Alice Johnson",
    "email": "alice@example.com",
    "role": "engineer",
    "department": "platform",
    "preferences": {
      "theme": "dark",
      "notifications": true
    }
  }'

Form Data Body (表单数据)

# URL 编码的表单数据
curl -X POST https://api.example.com/v1/login \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "username=alice&password=secret123"

# 分段表单数据 (文件上传)
curl -X POST https://api.example.com/v1/upload \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -F "file=@photo.jpg" \
  -F "description=Profile photo"

Body 内容类型 (Content-Types)

Content-Type	格式	使用场景
application/json	JSON	大多数 API 数据交换
application/x-www-form-urlencoded	键值对	简单表单提交
multipart/form-data	混合内容	文件上传
application/xml	XML	遗留系统/企业级 API
application/octet-stream	原始二进制	二进制文件传输

何时使用 Body 参数

• 创建 新资源 (POST)
• 更新 现有资源 (PUT, PATCH)
• 发送 复杂或嵌套的数据 结构
• 文件上传

重要规则

1. GET 和 DELETE 请求 不应 携带 Body（某些服务器会忽略它）
2. 务必设置 Content-Type 头，使其与你的 Body 格式匹配
3. 在客户端和服务器端都要验证 Body 数据
4. 使用 PATCH 进行局部更新，使用 PUT 进行整体替换

综合示例

以下是一个在单次请求中同时使用所有四种参数类型的真实示例：

# 更新特定用户的个人资料图片
# - Path 参数: userId (42)
# - Query 参数: overwrite (true)
# - Header 参数: Authorization, Content-Type
# - Body 参数: 图像文件

curl -X PUT "https://api.example.com/v1/users/42/avatar?overwrite=true" \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiJ9..." \
  -H "Content-Type: multipart/form-data" \
  -F "avatar=@new-profile.jpg"

决策矩阵

使用此表来决定使用哪种参数类型：

问题	结论	使用类型
是否用于标识特定资源？	是	Path 参数
是否为可选/用于过滤？	是	Query 参数
是否是关于请求的元数据？	是	Header 参数
是否是身份验证数据？	是	Header 参数
是否是用于创建/更新的数据负载？	是	Body 参数
是否是文件？	是	Body 参数 (multipart)

常见陷阱及避免方法

1. 在 URL 中放置敏感数据。 API Key、Token 和密码应放在 Header 中，绝不要放在 Path 或 Query 参数中。

2. Query 字符串过载。 如果你的 Query 字符串包含 15 个参数，请考虑改用带有 JSON Body 的 POST 请求。

3. 忽略 Content-Type。 Content-Type 请求头不匹配会导致晦涩的 400 或 415 错误。始终要保持 Header 与实际 Body 格式一致。

4. 未对 Query 参数进行 URL 编码。 Query 值中的特殊字符必须编码：空格变为 %20 或 +，& 变为 %26。

# 错误：未编码的空格会破坏 URL
curl "https://api.example.com/search?q=hello world"

# 正确：经过正确编码
curl "https://api.example.com/search?q=hello%20world"

5. 在 GET 请求中发送 Body。 虽然技术上可行，但许多服务器、代理和客户端会剥离或忽略它。GET 请求请使用 Query 参数。

测试你的 API 参数

测试 API 参数最快的方法是使用 curl 或 API 客户端工具。如果你正在构建与 AI 媒体生成 API 交互的应用，Hypereal AI 提供了文档详尽的端点，并对图像、视频和音频生成的参数规格有清晰的界定，让你能直观上手，无需猜测。

总结

理解四种 API 参数类型对每位开发者都至关重要：

• Path 参数 在 URL 中标识特定资源
• Query 参数 过滤、排序和分页结果
• Header 参数 携带身份验证信息和元数据
• Body 参数 为创建或更新资源发送数据负载

为每项数据选择正确的参数类型，遵循你所使用的 API 的规范，并始终确保敏感信息不出现在 URL 中。