java: 4种API 参数传递方式

原创于 2025-12-06 19:13:03 发布 · 596 阅读

CC 4.0 BY-SA版权

文章标签：

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。它们各自适用于不同场景，合理选择传参方式有助于接口保持语义清晰、结构规范、易于维护。