处理Web请求路径参数

paishishaba2025-07-11 14:54

目录

[1. 路径变量（Path Variable）](#1. 路径变量（Path Variable）)

[2. 查询参数（Query Parameter）](#2. 查询参数（Query Parameter）)

[3. 表单参数（Form Data）](#3. 表单参数（Form Data）)

[4. 请求体JSON参数（Request Body JSON）](#4. 请求体JSON参数（Request Body JSON）)

[5. 请求头参数（Header Parameters）](#5. 请求头参数（Header Parameters）)

[6. 矩阵变量（Matrix Variables）](#6. 矩阵变量（Matrix Variables）)

特殊：参数绑定

Content-Type（补充）

接口测试

[(1) Header（请求头参数）](#(1) Header（请求头参数）)

[(2) Query（查询参数）](#(2) Query（查询参数）)

[(3) Path（路径变量）](#(3) Path（路径变量）)

[(4) Body（请求体）](#(4) Body（请求体）)

[(5）binary（二进制数据）](#(5）binary（二进制数据）)

[(6）msgpack（MessagePack格式）](#(6）msgpack（MessagePack格式）)

错误

1. 路径变量（Path Variable）

写法：

复制代码 
@GetMapping("/users/{id}")
public ResponseEntity<User> getUserById(@PathVariable Long id) {
    // 业务逻辑
}

特点：

  • 使用@PathVariable注解
  • 参数直接嵌入URL路径中
  • RESTful风格推荐使用
  • 适合必传的、标识性的参数

ApiPost测试配置：

2. 查询参数（Query Parameter）

写法：

复制代码 
@GetMapping("/users")
public ResponseEntity<List<User>> getUsers(
    @RequestParam(required = false, defaultValue = "1") Integer page,
    @RequestParam(required = false, defaultValue = "10") Integer size) {
    // 业务逻辑
}

特点：

  • 使用@RequestParam注解
  • 参数以?key=value&key2=value2形式附加在URL后
  • 适合可选参数、过滤条件
  • 可以设置默认值和是否必需

ApiPost测试配置：

3. 表单参数（Form Data）

写法：

复制代码 
@PostMapping("/users")
public ResponseEntity<User> createUser(@RequestParam String username, 
                                     @RequestParam String password) {
    // 业务逻辑
}

特点：

  • 同样使用@RequestParam注解
  • 参数通过请求体发送（Content-Type: application/x-www-form-urlencoded）
  • 适合POST请求中的简单参数
  • 参数不会显示在URL中

ApiPost测试配置：

  • 请求URL填写：http://localhost:8080/users
  • 请求方法选择POST
  • 在"Body"选项卡中选择"form-data"或"x-www-form-urlencoded"
  • 添加参数：
    • 参数名：username，值：user1
    • 参数名：password，值：123456

前三种方法对比

特性 路径变量 查询参数 表单参数
注解 @PathVariable @RequestParam @RequestParam
URL可见性 路径部分可见 URL后可见 不可见
主要用途 资源标识 过滤、分页等可选参数 POST请求的简单参数
请求方法 通常GET 通常GET 通常POST/PUT
参数位置 URL路径中 URL问号后 请求体中
适合参数类型 必传、标识性参数 可选参数 简单键值对参数

选择建议

  1. 路径变量：用于标识特定资源，如/users/{id}
  2. 查询参数：用于过滤、排序、分页等，如/users?role=admin&page=1
  3. 表单参数：用于简单的POST表单提交，复杂数据建议使用JSON body

4. 请求体JSON参数（Request Body JSON）

写法：

复制代码 
@PostMapping("/users")
public ResponseEntity<User> createUser(@RequestBody UserDTO userDTO) {
    // 业务逻辑
}

特点：

  • 使用@RequestBody注解
  • 接收JSON格式的请求体（Content-Type: application/json）
  • 适合传输复杂的结构化数据
  • 需要定义对应的DTO类
  • 是REST API最常用的POST/PUT参数传递方式

ApiPost测试配置：

5. 请求头参数（Header Parameters）

写法：

复制代码 
@GetMapping("/users")
public ResponseEntity<List<User>> getUsers(
    @RequestHeader("Authorization") String authToken,
    @RequestHeader(value = "User-Agent", required = false) String userAgent) {
    // 业务逻辑
}

特点：

  • 使用@RequestHeader注解
  • 从HTTP请求头中获取参数
  • 常用于认证令牌、设备信息等
  • 可以设置是否必需

ApiPost测试配置：

  • 请求URL：http://localhost:8080/users
  • 请求方法：GET
  • 在"Headers"选项卡中添加：
    • Authorization: Bearer xxxxxxxx
    • User-Agent: ApiPost/1.0

6. 矩阵变量（Matrix Variables）

写法：

复制代码 
// 需要先启用矩阵变量（Spring Boot默认禁用）
@Configuration
public class WebConfig implements WebMvcConfigurer {
    @Override
    public void configurePathMatch(PathMatchConfigurer configurer) {
        configurer.setUseSuffixPatternMatch(false);
        configurer.setUseRegisteredSuffixPatternMatch(true);
        configurer.setUseTrailingSlashMatch(true);
    }
}

// 控制器中使用
@GetMapping("/users/{id}")
public ResponseEntity<User> getUser(
    @PathVariable String id,
    @MatrixVariable(pathVar = "id") Map<String, String> matrixVars) {
    // 业务逻辑
}

特点：

  • 使用@MatrixVariable注解
  • URL格式：/users/id;key=value;key2=value2
  • 允许在路径段中添加键值对参数
  • 需要额外配置启用
  • 使用较少，但在某些特殊场景有用

ApiPost测试配置：

六种写法的完整对比

类型 注解 位置 常用场景 Content-Type 示例URL
路径变量 @PathVariable URL路径 资源标识 无 /users/123
查询参数 @RequestParam URL后 过滤/分页 无 /users?page=1
表单参数 @RequestParam 请求体 简单表单 x-www-form-urlencoded /users (POST)
JSON参数 @RequestBody 请求体 复杂数据 application/json /users (POST)
矩阵变量 @MatrixVariable URL路径段 特殊场景 无 /users/123;dept=IT
请求头 @RequestHeader HTTP头 认证/元数据 无 /users (带Headers)

特殊：参数绑定

可以直接用对象类接收传递的 Web 请求路径参数（或查询参数）， 通常称为 "参数绑定"（Parameter Binding） 或 "对象封装"，

后端框架（如 Spring MVC）会自动将这些键值对映射到对象的属性上，前提是属性名与参数名匹配。

这种方式的优点是：

  • 避免在方法中写大量 @RequestParam 注解。
  • 直接面向业务对象编程，更符合 OOP 思想。

注意事项

  1. 属性名匹配：前端参数名必须与对象字段名一致（或通过注解配置映射关系）。
  2. 类型转换：框架会自动处理简单类型（如 String/int），但复杂类型（如日期）可能需要自定义转换器。
  3. 嵌套对象：部分框架支持嵌套对象绑定（如 user.name=John），但需明确约定参数命名格式。

1. 查询参数（Query Parameters）的典型形式

前端请求的 URL 通常如下：

复制代码 
GET /api/users?name=John&age=25&city=Beijing

后端用对象接收：

复制代码 
// Spring Boot 示例
@GetMapping("/api/users")
public ResponseEntity<?> getUsers(UserQuery query) {
    // query 会自动封装 name="John", age=25, city="Beijing"
    // ...
}

// 封装参数的对象
public class UserQuery {
    private String name;
    private Integer age;
    private String city;
    // getters/setters
}

2. 路径参数（Path Variables）

URL 示例：

复制代码 
GET /api/users/123

后端对象绑定（需配合注解）：

复制代码 
@GetMapping("/api/users/{id}")
public ResponseEntity<?> getUser(@PathVariable("id") Long id) {
    // 直接提取路径参数 id=123
}

// 如果用对象接收（需框架支持，如 Spring 的 @ModelAttribute）：
@GetMapping("/api/users/{id}")
public ResponseEntity<?> getUser(@ModelAttribute UserQuery query) {
    // 需要 query 中有 id 字段
}

3. 表单数据（Form Data）

表单 POST 请求：

前端提交 Content-Type: application/x-www-form-urlencoded，后端同样可以用对象接收。

复制代码 
// 前端请求：POST /api/users （Body: name=John&age=25，Content-Type: application/x-www-form-urlencoded）
@PostMapping("/api/users")
public ResponseEntity<?> createUser(UserForm form) {
    // form 对象会填充 name="John", age=25
}

4. JSON 请求体（Request Body）

JSON 请求体：

需用 @RequestBody 明确标识：

复制代码 
@PostMapping("/api/users")
public ResponseEntity<?> createUser(@RequestBody UserRequest request) {
    // 接收 JSON 数据，如 {"name": "John", "age": 25}
}

无注解对象绑定适用于以下两种数据传递方式：

  • 查询参数（URL 的 ?key=value，所有 HTTP 方法均支持）。
  • 表单数据（请求体的 key=value 格式，需 Content-Type: application/x-www-form-urlencoded，通常用于 POST/PUT）。

Content-Type（补充）

在HTTP请求和响应中，Content-Type是一个非常重要的头部字段，它用于指示发送或接收的数据的媒体类型（MIME类型），帮助客户端和服务器正确解析和处理数据。

Content-Type是HTTP协议的一个请求/响应头，用于指定：

  • 请求中：客户端发送给服务器的数据格式（如JSON、表单等）。
  • 响应中：服务器返回给客户端的数据格式（如HTML、JSON等）。

如果没有正确设置Content-Type，服务器可能无法正确解析请求数据，导致400 Bad Request等错误。

类型 Content-Type 用途 后端接收方式
JSON application/json REST API传输对象 @RequestBody
表单 x-www-form-urlencoded 普通表单提交 @RequestParam
文件 multipart/form-data 文件上传 @RequestParam + MultipartFile
纯文本 text/plain 日志/文本数据 @RequestBody String
HTML text/html 返回网页 通常由模板引擎处理

接口测试

在接口测试时，选择 Header、Query、Path、Body 等选项取决于你的接口设计参数传递方式。

(1) Header（请求头参数）

用途：传递认证信息（如Authorization）、客户端信息（如User-Agent）等。

何时选择：

  • 接口需要token或API-KEY。
  • 需要设置Content-Type、Accept等HTTP标准头。

ApiPost配置：

  • 在 Header 选项卡中添加键值对，例如：

    Authorization: Bearer xxxxxx
    Content-Type: application/json

(2) Query（查询参数）

用途：URL问号后的参数（如?page=1&size=10），用于过滤、分页等。

何时选择：

  • 参数是可选或非敏感数据（如分页、排序字段）。
  • 接口使用@RequestParam接收。

ApiPost配置：

  • 在 Query 选项卡中添加参数，例如：
Key Value
page 1
size 10
  • 最终URL会自动拼接为：http://api.example.com/users?page=1&size=10。

(3) Path（路径变量）

用途：RESTful风格URL中的变量（如/users/{id}）。

何时选择：

  • 接口URL包含动态路径（如/users/123）。
  • 后端使用@PathVariable接收。

ApiPost配置：

(4) Body（请求体）

用途：传输复杂数据（如JSON、表单、文件）。

何时选择：

  • POST/PUT请求需要提交数据。
  • 接口使用@RequestBody或@RequestParam（表单）。

ApiPost配置：

  • 根据数据类型选择 Body 的子选项：
类型 适用场景 对应Content-Type
none 无请求体（如GET请求） 无
form-data 上传文件或混合表单 multipart/form-data
x-www-form-urlencoded 普通表单提交（键值对） application/x-www-form-urlencoded
raw（JSON/XML等） 发送JSON/XML等结构化数据 application/json

(5）binary（二进制数据）

用途

  • 直接上传原始二进制文件（如图片、PDF、音频等），无需编码。

  • 适用于需要直接传输二进制流的接口（如文件上传、自定义协议通信）。

使用场景

  • 上传非文本类文件（如 .jpg, .pdf, .zip）。

  • 与后端通信使用自定义二进制协议。

ApiPost配置方法

  1. 在 Body 选项卡中选择 binary。

  2. 点击 "选择文件" 上传二进制文件（如 image.png）。

  3. 工具会自动设置请求头：

(6）msgpack（MessagePack格式）

用途

  • 传输 MessagePack 格式的数据（一种高效的二进制序列化格式，类似JSON但体积更小）。
  • 适用于高性能场景（如物联网设备通信、游戏后端）。

特点

  • 比JSON更紧凑，解析速度更快。
  • 支持多种语言（需前后端同时支持MessagePack库）。

使用场景

  • 需要减少网络传输体积的API。
  • 与嵌入式设备或移动端通信。
特性 binary msgpack
数据格式 原始二进制流 结构化二进制序列化数据
典型用途 文件上传、自定义协议 高效传输结构化数据（替代JSON）
Content-Type application/octet-stream application/msgpack
可读性 不可读（需解析） 不可读（但可反序列化为JSON）
体积 取决于文件大小 比JSON小30%~50%

如果只是上传文件，更推荐使用 form-data（可同时传文件和字段）。

如果追求性能但不想用msgpack，可考虑 Protocol Buffers（protobuf）。

错误

如果 Content-Type 与实际数据格式不匹配，服务器可能返回：

  • 415 Unsupported Media Type（格式不支持）
  • 400 Bad Request（解析失败）
相关推荐
全栈凯哥1 分钟前
20.缓存问题与解决方案详解教程
java·spring boot·redis·后端·缓存
hudawei9968 分钟前
kotlin中withContext,async,launch几种异步的区别
android·开发语言·kotlin
消失的旧时光-194312 分钟前
Kotlin 常用语法糖完整整理
android·开发语言·kotlin
小莫分享15 分钟前
2023年最新总结，阿里，腾讯，百度，美团，头条等技术面试题目，以及答案，专家出题人分析汇总。
java·后端·面试·职场和发展
每次的天空16 分钟前
Android-重学kotlin(协程源码第一阶段)新学习总结
开发语言·学习·kotlin
Brookty17 分钟前
【操作系统】线程
java·linux·服务器·后端·学习·java-ee·操作系统
Dovis(誓平步青云）19 分钟前
探索飞算 JavaAI 进阶：解锁高效Java开发的新维度
java·开发语言·飞算java
源码云商19 分钟前
基于 SpringBoot + Vue 的 IT 技术交流和分享平台的设计与实现
vue.js·spring boot·后端
CS semi20 分钟前
C++每日刷题day2025.7.10
开发语言·c++
还听珊瑚海吗24 分钟前
Python（一）
开发语言·python
热门推荐
01【无标题】02集群聊天服务器---MySQL数据库的建立03Coze扣子平台完整体验和实践（附国内和国际版对比）04Java类变量（静态变量）05KGG转MP3工具|非KGM文件|解密音频06扣子（coze）实战|我用扣子搭建了一个自动分析小红薯笔记内容的AI应用|详细步骤拆解07深度神经网络训练过程与常见概念08使用Ruby接入实时行情API教程09DeepSeek各版本说明与优缺点分析10RestTemplate原理分析