RESTful 前后端传参参数格式总结

本文总结了RESTful API前后端交互的四种传参方式：路径参数（用于资源标识）、查询参数（用于筛选分页）、请求体参数（传输复杂数据）和请求头参数（处理元数据和认证）。

详细说明了各参数类型的特点、适用HTTP方法及使用场景，对比了JSON、FormData等请求体格式的优缺点，并提供了混合使用示例。

重点强调了参数选择原则：路径参数用于必需资源标识，查询参数用于可选操作，请求体用于完整数据，请求头用于元数据。

同时指出了常见误区，如避免在查询参数中传递敏感信息等，旨在帮助开发者设计更符合RESTful原则、高可读性和可维护性的API。

RESTful 前后端传参参数格式总结

参数类型	传参位置	格式示例	常见HTTP方法	特点与用途
路径参数 (Path Parameters)	URL路径中	`/users/123` `/products/2024`	GET, PUT, DELETE, PATCH	1. 用于标识特定资源 2. 是URL的一部分 3. 通常是必需的 4. 更符合RESTful资源定位语义
查询参数 (Query Parameters)	URL问号后	`/users?page=1&limit=20` `/search?q=keyword&sort=desc`	GET	1. 用于筛选、排序、分页等可选参数 2. 键值对形式，用`&`连接 3. 长度有限制（因浏览器而异） 4. 可缓存
请求体参数 (Body Parameters)	HTTP请求体中	JSON: `{"name":"John", "age":30}` Form: `name=John&age=30` XML: `<user><name>John</name></user>`	POST, PUT, PATCH	1. 传输数据量大，无长度限制 2. 支持复杂数据结构 3. 不可缓存（GET方法通常不应使用） 4. 需设置Content-Type头部
请求头参数 (Header Parameters)	HTTP头部	`Authorization: Bearer token123` `Content-Type: application/json`	所有方法	1. 用于元数据、认证、内容协商 2. 键值对形式 3. 大小有限制（通常8KB以内） 4. 自动包含在请求中

详细说明与最佳实践

1. 路径参数

用途: 标识唯一资源或资源层次结构
示例 : DELETE /api/users/{userId}/posts/{postId}
Content-Type: 不适用（参数在URL中）

2. 查询参数

用途: 过滤、排序、分页、搜索等可选操作
示例 : GET /api/products?category=electronics&minPrice=100&sort=price&page=2
Content-Type: 不适用

3. 请求体参数（常见格式对比）

格式	Content-Type	优点	缺点	适用场景
JSON	`application/json`	1. 数据结构清晰 2. 前端JS原生支持 3. 可读性好	1. 相比二进制格式体积稍大 2. 不支持文件上传	REST API主要推荐格式，复杂数据结构
Form Data	`application/x-www-form-urlencoded`	1. 浏览器原生支持 2. 简单键值对	1. 不支持嵌套结构 2. 值需要URL编码	简单表单提交，传统Web应用
Multipart	`multipart/form-data`	1. 支持文件上传 2. 可混合文本和文件	1. 格式复杂 2. 体积较大	文件上传，包含文件的表单
XML	`application/xml`	1. 严格的数据结构 2. 丰富的元数据支持	1. 冗长，体积大 2. 解析复杂	传统企业系统，SOAP API

4. 混合使用示例

复制代码

# 认证令牌在头部，ID在路径，分页在查询，更新数据在请求体
PUT /api/users/123/orders?notify=true
Authorization: Bearer xyz789
Content-Type: application/json

{
  "status": "shipped",
  "trackingNumber": "TRK123456"
}

选择原则总结

路径参数 : 用于必须的资源标识
查询参数 : 用于可选的过滤、排序等
请求体 : 用于创建/更新资源的完整数据
请求头 : 用于元数据 和认证信息

常见误区避免

❌ 用查询参数传递敏感信息（会在日志、浏览器历史中暴露）
❌ GET请求使用请求体传递参数（不符合HTTP语义，且可能不被支持）
❌ 路径参数用于可选信息（会改变资源标识）
✅ 保持参数位置的一致性（同类型参数总在相同位置）

这种传参结构设计能够使API更符合RESTful原则，提高可读性、可维护性和缓存效率。