java: 4种API 参数传递方式

关注

原创最新推荐文章于 2026-09-08 15:19:05 发布 930 阅读 AI 写同款· GEO 优化 ›

Java中调用第三方API：全面指南涵盖JSON/XML参数传递、加密认证、SSL处理与Token认证在与第三方API交互时，确保通信的安全性、数据格式的正确性以及高效的错误处理是至关重要的。结合本文所述的各个方面，以下是一个综合示例，展示如何在Java中调用第三方API，包括JSON参数传递、HMAC加密认证、SSL配置、Bearer Token认证、错误处理与日志记录。Token认证是一种常见的认证方式，通常用于API的身份验证和授权。通常，获取Token需要先通过某种认证方式（如用户名密码、API Key等）向认证服务器发送请求，获取Token后在后续的API请求中使用该Token。阅读详情

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