当前位置: 首页 > news >正文

处理Web请求路径参数

目录

1. 路径变量(Path Variable)

2. 查询参数(Query Parameter)

3. 表单参数(Form Data)

4. 请求体JSON参数(Request Body JSON)

5. 请求头参数(Header Parameters)

6. 矩阵变量(Matrix Variables)

特殊:参数绑定

Content-Type(补充)

接口测试

(1) Header(请求头参数)

(2) Query(查询参数)

(3) Path(路径变量)

(4) Body(请求体)

(5)binary(二进制数据)

(6)msgpack(MessagePack格式)

错误


1. 路径变量(Path Variable)

写法

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

特点:

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

ApiPost测试配置:

  • 请求URL填写:http://localhost:8080/users/123
  • 请求方法选择GET
  • 不需要额外参数设置

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测试配置:

  • 请求URL填写:http://localhost:8080/users?page=2&size=20
  • 或者使用ApiPost的"Params"选项卡添加参数:
    • 参数名:page,值:2
    • 参数名:size,值:20

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测试配置:

  • 请求URL:http://localhost:8080/users
  • 请求方法:POST
  • 在"Body"选项卡中选择"raw"和"JSON"
  • 输入JSON数据:
{"username": "testuser","password": "123456","email": "test@example.com"
}

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 {@Overridepublic 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测试配置:

  • 请求URL:http://localhost:8080/users/123;department=IT;role=admin
  • 请求方法:GET
  • 不需要额外参数设置

六种写法的完整对比

类型注解位置常用场景Content-Type示例URL
路径变量@PathVariableURL路径资源标识/users/123
查询参数@RequestParamURL后过滤/分页/users?page=1
表单参数@RequestParam请求体简单表单x-www-form-urlencoded/users (POST)
JSON参数@RequestBody请求体复杂数据application/json/users (POST)
矩阵变量@MatrixVariableURL路径段特殊场景/users/123;dept=IT
请求头@RequestHeaderHTTP头认证/元数据/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用途后端接收方式
JSONapplication/jsonREST API传输对象@RequestBody
表单x-www-form-urlencoded普通表单提交@RequestParam
文件multipart/form-data文件上传@RequestParam + MultipartFile
纯文本text/plain日志/文本数据@RequestBody String
HTMLtext/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 选项卡中添加参数,例如:
KeyValue
page1
size10
  • 最终URL会自动拼接为:http://api.example.com/users?page=1&size=10

(3) Path(路径变量)

用途:RESTful风格URL中的变量(如/users/{id})。

何时选择:

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

ApiPost配置:

  • 直接在URL中填写路径变量,例如
http://api.example.com/users/123
  • 无需额外配置(除非工具支持路径变量占位符)。

(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。
  • 与嵌入式设备或移动端通信。
特性binarymsgpack
数据格式原始二进制流结构化二进制序列化数据
典型用途文件上传、自定义协议高效传输结构化数据(替代JSON)
Content-Typeapplication/octet-streamapplication/msgpack
可读性不可读(需解析)不可读(但可反序列化为JSON)
体积取决于文件大小比JSON小30%~50%

如果只是上传文件,更推荐使用 form-data(可同时传文件和字段)。

如果追求性能但不想用msgpack,可考虑 Protocol Buffers(protobuf)。

错误

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

  • 415 Unsupported Media Type(格式不支持)
  • 400 Bad Request(解析失败)

http://www.dtcms.com/a/272020.html

相关文章:

  • 基于odoo17的设计模式详解---访问模式
  • 构建分布式光伏“四可”能力:支撑新型电力系统安全稳定运行的关键路径
  • 如何在 Ubuntu 上安装 Linux 杀毒软件 ClamAV,排除系统已经感染木马或病毒
  • 设计模式 - 教程
  • 自动驾驶控制系统
  • 低频低压减载装置
  • Go从入门到精通(20)-一个简单web项目-服务搭建
  • 循环神经网络(RNN)Python实现详解
  • 什么是VR实景漫游?VR实景的制作办法?
  • VR博物馆:概念与内涵
  • 广州华锐互动在各领域打造的 VR 成功案例展示​
  • 数字孪生技术引领UI前端设计新趋势:增强现实与虚拟现实的融合应用
  • VBA即用型代码手册:Range对象 Range Object
  • vue3 uniapp 使用ref更新值后子组件没有更新 ref reactive的区别?使用from from -item执行表单验证一直提示没有值
  • 软考(软件设计师)计算机网络-物理层,数据链路层
  • QT - Qvector用法
  • Java设计模式之行为型模式(观察者模式)介绍与说明
  • 关于k8s Kubernetes的10个面试题
  • 【AXI】读重排序深度
  • Scala实现网页数据采集示例
  • linux的用户和权限(学习笔记
  • 西门子200SMART如何无线联三菱FX3U?御控工业网关实现多站点PLC无线通讯集中控制!
  • MiniGPT4源码拆解——models
  • 膨胀卷积介绍
  • QPC框架中状态机的设计优势和特殊之处
  • 大模型在膀胱癌诊疗全流程预测及应用研究报告
  • 【Linux基础命令使用】VIM编辑器的使用
  • 【个人笔记】负载均衡
  • Linux小白学习基础内容
  • LUMP+NFS架构的Discuz论坛部署