当前位置： 首页 > web >正文

Spring Framework 中 UriComponentsBuilder工具类

web 2025/6/30 7:45:14

前言

在 Spring Framework 中，UriComponentsBuilder 是一个功能强大的工具类，用于构建和操作 URI（统一资源标识符）。无论是构建 RESTful API 的请求 URL、动态拼接路径参数，还是处理查询参数和编码问题，UriComponentsBuilder 都能提供优雅且安全的解决方案。

一、UriComponentsBuilder 的核心概念

1.1 什么是 UriComponentsBuilder？

UriComponentsBuilder 是 Spring 提供的一个链式调用工具类，用于逐步构建 URI 的各个部分（如协议、主机、路径、查询参数、片段等）。它支持灵活的 URI 拼接、模板变量替换和自动编码，避免了手动拼接字符串可能导致的安全问题（如注入攻击）。

1.2 UriComponents 与 UriComponentsBuilder 的关系

  • UriComponents：一个不可变的 URI 组件对象，由 UriComponentsBuilder 构建而成。它包含了 URI 的所有组成部分（协议、主机、路径、查询参数等）。
  • UriComponentsBuilder：用于构建 UriComponents 的可变构建器，支持链式调用。

二、UriComponentsBuilder 的核心 API

1. 创建 UriComponentsBuilder 实例的静态方法

(1) newInstance()
  • 作用：从头开始构建一个空的 UriComponentsBuilder 实例。
  • 使用场景：需要完全自定义 URI 的各个部分（协议、主机、路径等）。
  • 示例：
    UriComponentsBuilder builder = UriComponentsBuilder.newInstance().scheme("https").host("example.com").path("/api/data");
System.out.println(builder.build().toUriString());
// 输出: https://example.com/api/data
(2) fromHttpUrl(String url)
  • 状态：已弃用（推荐使用 fromUriString）。
  • 作用：从 HTTP/HTTPS URL 字符串构建实例。
  • 使用场景：仅适用于 HTTP/HTTPS 协议的 URL。
  • 示例：
    // 不推荐（弃用）
UriComponentsBuilder builder = UriComponentsBuilder.fromHttpUrl("https://example.com/api/data");
System.out.println(builder.build().toUriString());
(3) fromUriString(String uri)
  • 推荐替代方法：替代 fromHttpUrl。
  • 作用：从完整的 URI 字符串构建实例（支持任意协议）。
  • 使用场景：通用的 URI 构建，支持 HTTP/HTTPS 以外的协议（如 ftp://）。
  • 示例：
    UriComponentsBuilder builder = UriComponentsBuilder.fromUriString("https://example.com/api/data");
System.out.println(builder.build().toUriString());
(4) fromUri(URI uri)
  • 作用：从 java.net.URI 对象构建实例。
  • 使用场景：已有 URI 对象，需进一步修改其路径或参数。
  • 示例：
    URI originalUri = new URI("https://example.com/api/data");
UriComponentsBuilder builder = UriComponentsBuilder.fromUri(originalUri).path("/v2");
System.out.println(builder.build().toUriString());
// 输出: https://example.com/api/data/v2
(5) fromPath(String path)
  • 作用：从路径字符串构建实例（忽略协议、主机等信息）。
  • 使用场景：仅需构建相对路径（如 /api/users）。
  • 示例：
    UriComponentsBuilder builder = UriComponentsBuilder.fromPath("/api/users");
System.out.println(builder.build().toUriString());
// 输出: /api/users
(6) fromHttpRequest(HttpRequest request)
  • 作用：从 HTTP 请求对象构建 URI（提取协议、主机、端口等信息）。
  • 使用场景：基于当前请求动态构建 URI。
  • 示例：
    // 假设 request 是一个 HttpServletRequest 对象
UriComponentsBuilder builder = UriComponentsBuilder.fromHttpRequest(request).path("/new-path");
System.out.println(builder.build().toUriString());
(7) fromOriginHeader(String origin)
  • 作用：从跨域请求的 Origin 头构建 URI（仅包含协议、主机和端口）。
  • 使用场景：处理跨域请求时，动态构建目标 URI。
  • 示例：
    UriComponentsBuilder builder = UriComponentsBuilder.fromOriginHeader("https://example.com").path("/api/data");
System.out.println(builder.build().toUriString());
// 输出: https://example.com/api/data

2. 构建 URI 的组成部分

(1) 添加路径
  • 方法：path(String path)
  • 作用：追加路径到当前 URI。
  • 使用场景：动态拼接多级路径（如 /api/users/123）。
  • 示例：
    UriComponentsBuilder builder = UriComponentsBuilder.newInstance().scheme("https").host("example.com").path("/api").path("/users").path("/{id}");
System.out.println(builder.buildAndExpand("123").toUriString());
// 输出: https://example.com/api/users/123
(2) 替换路径
  • 方法：replacePath(String path)
  • 作用：覆盖当前路径。
  • 使用场景：需要完全替换现有路径（如从 /old 改为 /new）。
  • 示例：
    UriComponentsBuilder builder = UriComponentsBuilder.fromHttpUrl("https://example.com/old").replacePath("/new");
System.out.println(builder.build().toUriString());
// 输出: https://example.com/new
(3) 添加查询参数
  • 方法：queryParam(String name, Object... values)
  • 作用：添加查询参数（支持重复参数）。
  • 使用场景：构建带分页或过滤条件的 API 请求。
  • 示例：
    UriComponentsBuilder builder = UriComponentsBuilder.fromHttpUrl("https://example.com/api/data").queryParam("page", 1).queryParam("size", 20);
System.out.println(builder.build().toUriString());
// 输出: https://example.com/api/data?page=1&size=20
(4) 替换查询参数
  • 方法：replaceQueryParam(String name, Object... values)
  • 作用：替换指定查询参数的值。
  • 使用场景：动态更新查询参数（如从 page=1 改为 page=2）。
  • 示例：
    UriComponentsBuilder builder = UriComponentsBuilder.fromHttpUrl("https://example.com/api/data?page=1").replaceQueryParam("page", 2);
System.out.println(builder.build().toUriString());
// 输出: https://example.com/api/data?page=2
(5) 添加片段（Fragment）
  • 方法：fragment(String fragment)
  • 作用：添加 URI 片段（即 # 后的内容）。
  • 使用场景：构建带有锚点的 URL（如 /page#section1）。
  • 示例：
    UriComponentsBuilder builder = UriComponentsBuilder.fromHttpUrl("https://example.com/page").fragment("section1");
System.out.println(builder.build().toUriString());
// 输出: https://example.com/page#section1
(6) 编码
  • 方法：encode() / encode(Charset charset)
  • 作用：对 URI 的各部分进行编码（默认 UTF-8）。
  • 使用场景：确保生成的 URI 符合 RFC 3986 标准（如处理中文参数）。
  • 示例：
    UriComponentsBuilder builder = UriComponentsBuilder.fromHttpUrl("https://example.com/search").queryParam("q", "1 + 2 = 3");
System.out.println(builder.encode().build().toUriString());
// 输出: https://example.com/search?q=1%20%2B%202%20%3D%203
(7) 构建最终 URI
  • 方法：build() / buildAndExpand(Object... values)
  • 作用：
    • build()：构建不可变的 UriComponents 对象。
    • buildAndExpand(...)：构建并替换路径/查询参数中的占位符（如 {id}）。
  • 使用场景：动态替换模板变量（如 /users/{id}）。
  • 示例：
    // 使用 buildAndExpand 替换占位符
UriComponentsBuilder builder = UriComponentsBuilder.fromHttpUrl("https://example.com/users/{id}");
System.out.println(builder.buildAndExpand("123").toUriString());
// 输出: https://example.com/users/123
(8) 转换为 URI 或字符串
  • 方法：
    • toUri()：返回 java.net.URI 对象。
    • toUriString()：返回编码后的 URI 字符串。
  • 使用场景：将构建的 URI 用于 HTTP 客户端或日志记录。
  • 示例：
    UriComponentsBuilder builder = UriComponentsBuilder.fromHttpUrl("https://example.com/data").queryParam("sort", "name");
URI uri = builder.build().toUri();
String uriString = builder.build().toUriString();
System.out.println(uri); // java.net.URI 对象
System.out.println(uriString); // 字符串形式

二、变量替换与模板化构建

1. 路径模板

  • 使用场景：动态替换路径中的变量（如 /users/{id}）。
  • 示例：
    UriComponentsBuilder builder = UriComponentsBuilder.fromHttpUrl("https://example.com/users/{id}").queryParam("action", "{action}");
System.out.println(builder.buildAndExpand("123", "delete").toUriString());
// 输出: https://example.com/users/123?action=delete

2. 查询参数模板

  • 使用场景：动态替换查询参数中的变量（如 q={query}）。
  • 示例：
    UriComponentsBuilder builder = UriComponentsBuilder.newInstance().path("/search").queryParam("q", "{query}");
System.out.println(builder.buildAndExpand("Spring").toUriString());
// 输出: /search?q=Spring

三、编码规则与注意事项

1. 默认编码

  • 规则：UriComponentsBuilder 使用 RFC 3986 编码规则。
  • 示例：
    UriComponentsBuilder builder = UriComponentsBuilder.fromHttpUrl("https://example.com/search").queryParam("q", "1 + 2 = 3");
System.out.println(builder.build().toUriString());
// 输出: https://example.com/search?q=1%20%2B%202%20%3D%203

2. 自定义编码

  • 场景：需要使用 java.net.URLEncoder 的编码方式。
  • 示例：
    String encodedValue = URLEncoder.encode("1 + 2 = 3", "UTF-8");
UriComponentsBuilder builder = UriComponentsBuilder.fromHttpUrl("https://example.com/search").queryParam("q", encodedValue);
System.out.println(builder.build(true).toUriString()); // build(true) 表示参数已编码

四、典型应用场景

1. 构建 RESTful API 请求 URL

UriComponentsBuilder builder = UriComponentsBuilder.fromHttpUrl("https://api.example.com/users").path("/{id}").queryParam("sort", "name").buildAndExpand("123");
System.out.println(builder.toUriString());
// 输出: https://api.example.com/users/123?sort=name

2. 动态生成带分页的 URL

UriComponentsBuilder builder = UriComponentsBuilder.fromHttpUrl("https://api.example.com/data").queryParam("page", 2).queryParam("size", 10);
System.out.println(builder.build().toUriString());
// 输出: https://api.example.com/data?page=2&size=10

3. 处理跨域请求的 Origin

UriComponentsBuilder builder = UriComponentsBuilder.fromOriginHeader("https://example.com").path("/api/data");
System.out.println(builder.build().toUriString());
// 输出: https://example.com/api/data

五、常见问题与解决方案

1. 如何避免重复编码？

  • 解决方案：如果手动编码参数，调用 build(true) 告知 UriComponentsBuilder 参数已编码：
    String encodedValue = URLEncoder.encode("test", "UTF-8");
builder.queryParam("q", encodedValue).build(true);

2. 如何处理特殊字符？

  • 解决方案：依赖 encode() 方法自动编码，或手动处理特殊字符（如 +、=）。

3. 如何从现有 URI 修改？

  • 解决方案：使用 fromUri(URI) 或 fromUriString(String) 读取现有 URI，再修改路径或参数。

六、总结

方法用途推荐场景
fromUriString通用 URI 构建替代 fromHttpUrl，支持所有协议
path/queryParam构建路径和查询参数动态拼接 API 地址
buildAndExpand替换模板变量路径或查询参数中包含占位符（如 {id}）
encode自动编码生成符合 RFC 3986 标准的 URI

七、扩展阅读

  • 官方文档：Spring Framework URI Building
  • 相关工具类：
    • ServletUriComponentsBuilder：基于当前请求构建 URI。
    • MvcUriComponentsBuilder：基于控制器方法构建 URI（与 @RequestMapping 一起使用）。
http://www.xdnf.cn/news/11861.html

相关文章：

  • 【开源工具】基于PyQt5工作时长计算器工具开发全解析
  • 【多线程初阶】wait() notify()
  • 高效获取淘宝商品实时数据：API 接口开发与接入指南
  • 使用PyQt5的图形用户界面（GUI）开发教程
  • 基于对比学习的带钢表面缺陷分类研究，整合SimCLR自监督预训练与YOLOv8目标检测框架的技术解析及Python实现方案
  • mac版excel如何制作时长版环形图
  • 从npm库 Vue 组件到独立SDK：打包与 CDN 引入的最佳实践
  • 利用 USB 设备重定向实现无缝远程办公
  • win7 系统盘如何瘦身！ 可整理出4-5G。
  • TopView(赢富)数据图片怎么看
  • python3.7的下载，以及详细的安装教程
  • go strings.TrimPrefix() 和 strings.TrimLeft()
  • LaTeX 常用语法格式总结 列表计数、图、公式、表格、参考文献环境
  • 【C#】轻松理解AutoResetEvent 和 ManualResetEvent
  • C#源码大汇总
  • Python搭建网站的基本模板,python搭建网站最快多久
  • 电脑提示Explorer.exe系统错误该怎么办？
  • dnf正在连接服务器然后选择角色卡,dnf选择角色卡死（选择角色进入游戏后卡住的解决方法）...
  • Blue Ocean Robotics收购世界领先的远距临场机器人Beam
  • outlook支持yahoo的正确设置方法
  • django 模型models 常用字段
  • 北京公交IC 卡充值地点
  • pc电脑上浏览手机网站在线wap浏览器或模拟器软件
  • Java 里的异常(Exception)详解
  • 解决鼠标指针移动时出现停顿卡的原因
  • CentOS5.4版本发布
  • ARM926EJ-S/ARM920T 协处理器 CP14, CP15详解
  • oracle agile 性能,Oracle Agile PLM安全漏洞(CVE-2016-3554)
  • Android Studio开发学习（三）——Button、EditText
  • Redhat6.2升级为6.3之后再降级为Redhat6.2 （linux内核降级）