java中4种API参数传递方式统一说明_Java

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	否	认证、元信息	不适合业务数据