1. 概述
在 Web API 设计中，客户端需要通过多种方式向服务端传递参数。根据 HTTP 协议和 RESTful 风格，常见的参数传递方式包括：Query Parameters、Path Parameters、Body Parameters 和 Header Parameters。本规范文档对各类参数的用途、特点与使用场景进行统一说明。
2. 参数传递方式分类
2.1 Query Parameters（查询参数）
位置：
附加在 URL 的 ? 之后，以 key=value 形式出现，多个参数使用 & 分隔。
示例：
GET /api/dish?page=1&pageSize=10&name=鱼香肉丝特点：
-
参数直接暴露在 URL 上。
-
适用于筛选、分页、搜索等查询类条件。
-
一般用于
GET请求（但其他方法也可以使用）。 -
参数长度受 URL 长度限制，不适合传输大数据。
典型场景：
-
列表分页
-
条件检索
-
排序字段传递
2.2 Path Parameters（路径参数）
位置：
作为 URL 路径的一部分，用于定位资源。
示例：
GET /api/dish/10特点：
-
表达资源层级结构，更符合 RESTful 风格。
-
参数不可省略，通常代表唯一性标识（如 ID）。
-
仅在 URL 中传递，不出现在请求体中。
典型场景：
-
获取某条记录（如 /user/1）
-
删除某条记录
-
查询某个资源的子资源
2.3 Body Parameters（请求体参数）
位置：
放置在 HTTP 请求体（Request Body）中。
常见数据格式：
-
JSON（最常用）
-
application/x-www-form-urlencoded（传统表单格式）
-
multipart/form-data（文件上传）
-
XML（现较少使用）
-
binary（二进制，如图片、视频）
示例（JSON）：
{
"name": "鱼香肉丝",
"price": 20,
"status": 1
}特点：
-
参数不暴露在 URL 上，适合传输复杂对象。
-
不受 URL 长度限制。
-
主要用于
POST、PUT、PATCH请求。
典型场景：
-
新增资源
-
修改资源
-
批量提交数据
-
上传文件
2.4 Header Parameters（请求头参数）
位置：
写入 HTTP Header 中。
示例：
Authorization: Bearer eyJhbGciOi...
Content-Type: application/json
token: xxxxxxx特点：
-
参数不显示在 URL 和 Body 中。
-
主要用于传递认证信息、格式声明等元数据。
-
不推荐用于传递业务数据。
典型场景：
-
JWT Token 身份认证
-
设置 Content-Type
-
API 版本信息
-
语言设置（Accept-Language）
3. 非主流但常见的方式
3.1 Cookies
用于在浏览器环境中自动携带状态信息，常见于登录状态维持。
特点：
-
浏览器自动附带，无需手动传递。
-
后端可读取 Cookie 获取用户凭证或偏好设置。
3.2 URL Fragment（片段标识符）
例如 #section1
不参与 HTTP 请求，在 API 中不使用，仅用于前端页面定位。
4. 四类主要参数的对比
| 传参方式 | 出现位置 | 是否可见 | 典型场景 | 限制 |
|---|---|---|---|---|
| Query Params | URL ? 后 |
是 | 搜索、分页、查询条件 | URL 长度限制 |
| Path Params | URL 路径 | 是 | 定位资源（如 ID） | 必须存在，类型简单 |
| Body Params | 请求体 | 否 | 新增、修改、上传 | 仅 POST/PUT 等支持 |
| Header Params | HTTP Header | 否 | 认证、元信息 | 不适合业务数据 |
5. 使用建议（最佳实践）
-
查询参数使用 Query。如分页 page、pageSize。
-
资源标识使用 Path。如 /user/{id}。
-
新增/修改使用 Body（JSON）。
-
认证信息使用 Header（如 Authorization）。
-
避免在 Header 中传递业务字段。
-
避免在 Query 或 Path 中传输过多复杂数据。
6. 总结
API 参数传递主要包含四种方式：Query、Path、Body 和 Header。它们各自适用于不同场景，合理选择传参方式有助于接口保持语义清晰、结构规范、易于维护。