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

Spring Framework 中 UriComponentsBuilder工具类

news 2025/8/6 8:43:36

前言

在 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.lqws.cn/news/120295.html

相关文章：

  • Educational Codeforces Round 179 (Rated for Div. 2)(A-E)
  • Python训练营打卡DAY44
  • DuckDB + Spring Boot + MyBatis 构建高性能本地数据分析引擎
  • 掌握 MotionLayout：交互动画开发
  • UniApp 全生命周期钩子详解
  • python版若依框架开发：python版若依部署
  • 【后端开发】goland分布式锁的几种实现方式（mysql,redis,etcd,zookeeper,mq,s3）
  • #Java篇：学习node后端之sql常用操作
  • 前端面试三之控制语句
  • Linux kill 暂停命令
  • vue3+elementplus表格表头加图标及文字提示
  • Starrocks中RoaringBitmap杂谈
  • Spring Boot MVC自动配置与Web应用开发详解
  • 低代码采购系统搭建：鲸采云+能源行业订单管理自动化案例
  • 国产三维CAD皇冠CAD在「金属压力容器制造」建模教程：蒸汽锅炉
  • setting up Activiti BPMN Workflow Engine with Spring Boot
  • 一起学Spring AI：核心概念
  • 沉金PCB电路板制造有哪些操作要点需要注意？
  • 中小制造企业转型：低成本国产工业软件替代方案实践
  • 力扣刷题Day 70：在排序数组中查找元素的第一个和最后一个位置（34）
  • 如何借助Hyper - V在Windows 10中构建安全软件测试环境
  • parquet :开源的列式存储文件格式
  • [蓝桥杯]密文搜索
  • ios版本的Tiktok二次安装不上，提示：Unable to Install “TikTok”
  • AI 时代下语音与视频伪造的网络安全危机
  • vue-16（Vuex 中的模块）
  • Python 中 Django 中间件：原理、方法与实战应用
  • stm32——UART和USART
  • Mac/iOS 如何解压 RAR 格式压缩包：常用工具与详细操作步骤
  • [Java 基础]抽象类和接口