对于最新稳定版本，请使用 Spring Framework 7.0.6！spring-doc.cadn.net.cn

URI 链接

参见 Servlet 栈中的等效内容spring-doc.cadn.net.cn

本节介绍了 Spring 框架中用于准备 URI 的各种可用选项。spring-doc.cadn.net.cn

UriComponents

Spring MVC 和 Spring WebFluxspring-doc.cadn.net.cn

UriComponentsBuilder 用于根据包含变量的 URI 模板构建 URI，如下例所示：spring-doc.cadn.net.cn

UriComponents uriComponents = UriComponentsBuilder
		.fromUriString("https://example.com/hotels/{hotel}") (1)
		.queryParam("q", "{q}") (2)
		.encode() (3)
		.build(); (4)

URI uri = uriComponents.expand("Westin", "123").toUri(); (5)
1 带有 URI 模板的静态工厂方法。
2 添加或替换 URI 组件。
3 请求对URI模板和URI变量进行编码。
4 构建一个 UriComponents。
5 展开变量并获取 URI。 
val uriComponents = UriComponentsBuilder
		.fromUriString("https://example.com/hotels/{hotel}") (1)
		.queryParam("q", "{q}") (2)
		.encode() (3)
		.build() (4)

val uri = uriComponents.expand("Westin", "123").toUri() (5)
1 带有 URI 模板的静态工厂方法。
2 添加或替换 URI 组件。
3 请求对URI模板和URI变量进行编码。
4 构建一个 UriComponents。
5 展开变量并获取 URI。

前面的示例可以合并为一个链，并通过 buildAndExpand 进行简化，如下例所示：spring-doc.cadn.net.cn

URI uri = UriComponentsBuilder
		.fromUriString("https://example.com/hotels/{hotel}")
		.queryParam("q", "{q}")
		.encode()
		.buildAndExpand("Westin", "123")
		.toUri();
val uri = UriComponentsBuilder
		.fromUriString("https://example.com/hotels/{hotel}")
		.queryParam("q", "{q}")
		.encode()
		.buildAndExpand("Westin", "123")
		.toUri()

你可以通过直接使用 URI（这隐含了编码）进一步缩短它，如下例所示：spring-doc.cadn.net.cn

URI uri = UriComponentsBuilder
		.fromUriString("https://example.com/hotels/{hotel}")
		.queryParam("q", "{q}")
		.build("Westin", "123");
val uri = UriComponentsBuilder
		.fromUriString("https://example.com/hotels/{hotel}")
		.queryParam("q", "{q}")
		.build("Westin", "123")

你可以通过使用完整的 URI 模板进一步缩短它，如下例所示：spring-doc.cadn.net.cn

URI uri = UriComponentsBuilder
		.fromUriString("https://example.com/hotels/{hotel}?q={q}")
		.build("Westin", "123");
val uri = UriComponentsBuilder
		.fromUriString("https://example.com/hotels/{hotel}?q={q}")
		.build("Westin", "123")

UriBuilder

Spring MVC 和 Spring WebFluxspring-doc.cadn.net.cn

UriComponentsBuilder 实现 UriBuilder。您可以使用 UriBuilderFactory 创建一个 UriBuilder。UriBuilderFactory 和 UriBuilder 共同提供了一种可插拔的机制，用于基于共享配置（如基础 URL、编码偏好和其他细节）从 URI 模板构建 URI。spring-doc.cadn.net.cn

您可以使用 RestTemplate 来配置 WebClient 和 UriBuilderFactory，以自定义 URI 的构建方式。DefaultUriBuilderFactory 是 UriBuilderFactory 的默认实现，其内部使用 UriComponentsBuilder，并提供共享的配置选项。spring-doc.cadn.net.cn

以下示例展示了如何配置一个 RestTemplate：spring-doc.cadn.net.cn

// import org.springframework.web.util.DefaultUriBuilderFactory.EncodingMode;

String baseUrl = "https://example.org";
DefaultUriBuilderFactory factory = new DefaultUriBuilderFactory(baseUrl);
factory.setEncodingMode(EncodingMode.TEMPLATE_AND_VALUES);

RestTemplate restTemplate = new RestTemplate();
restTemplate.setUriTemplateHandler(factory);
// import org.springframework.web.util.DefaultUriBuilderFactory.EncodingMode

val baseUrl = "https://example.org"
val factory = DefaultUriBuilderFactory(baseUrl)
factory.encodingMode = EncodingMode.TEMPLATE_AND_VALUES

val restTemplate = RestTemplate()
restTemplate.uriTemplateHandler = factory

以下示例配置了一个 WebClient：spring-doc.cadn.net.cn

// import org.springframework.web.util.DefaultUriBuilderFactory.EncodingMode;

String baseUrl = "https://example.org";
DefaultUriBuilderFactory factory = new DefaultUriBuilderFactory(baseUrl);
factory.setEncodingMode(EncodingMode.TEMPLATE_AND_VALUES);

WebClient client = WebClient.builder().uriBuilderFactory(factory).build();
// import org.springframework.web.util.DefaultUriBuilderFactory.EncodingMode

val baseUrl = "https://example.org"
val factory = DefaultUriBuilderFactory(baseUrl)
factory.encodingMode = EncodingMode.TEMPLATE_AND_VALUES

val client = WebClient.builder().uriBuilderFactory(factory).build()

此外，您也可以直接使用 DefaultUriBuilderFactory。它与使用 UriComponentsBuilder 类似，但不同于静态工厂方法，它是一个实际的实例， 用于保存配置和偏好设置，如下例所示：spring-doc.cadn.net.cn

String baseUrl = "https://example.com";
DefaultUriBuilderFactory uriBuilderFactory = new DefaultUriBuilderFactory(baseUrl);

URI uri = uriBuilderFactory.uriString("/hotels/{hotel}")
		.queryParam("q", "{q}")
		.build("Westin", "123");
val baseUrl = "https://example.com"
val uriBuilderFactory = DefaultUriBuilderFactory(baseUrl)

val uri = uriBuilderFactory.uriString("/hotels/{hotel}")
		.queryParam("q", "{q}")
		.build("Westin", "123")

URI 编码

Spring MVC 和 Spring WebFluxspring-doc.cadn.net.cn

UriComponentsBuilder 在两个层级上提供了编码选项：spring-doc.cadn.net.cn

这两种选项都会将非ASCII字符和非法字符替换为转义的八位字节序列。然而，第一种选项还会替换出现在URI变量中具有保留意义的字符。spring-doc.cadn.net.cn

考虑“;”字符，它在路径中是合法的，但具有保留含义。第一种选项会在 URI 变量中将“;”替换为“%3B”，但在 URI 模板中不会替换。相比之下，第二种选项永远不会替换“;”，因为它是路径中的合法字符。

在大多数情况下，第一个选项更可能得到预期的结果，因为它将URI变量视为不透明数据并进行完整编码；而第二个选项则适用于URI变量中确实包含保留字符的情况。此外，当完全不展开URI变量时，第二个选项也很有用，因为这样也会对任何偶然看起来像URI变量的内容进行编码。spring-doc.cadn.net.cn

以下示例使用了第一个选项：spring-doc.cadn.net.cn

URI uri = UriComponentsBuilder.fromPath("/hotel list/{city}")
		.queryParam("q", "{q}")
		.encode()
		.buildAndExpand("New York", "foo+bar")
		.toUri();

// Result is "/hotel%20list/New%20York?q=foo%2Bbar"
val uri = UriComponentsBuilder.fromPath("/hotel list/{city}")
		.queryParam("q", "{q}")
		.encode()
		.buildAndExpand("New York", "foo+bar")
		.toUri()

// Result is "/hotel%20list/New%20York?q=foo%2Bbar"

你可以通过直接使用 URI（这隐含了编码）来简化前面的示例，如下例所示：spring-doc.cadn.net.cn

URI uri = UriComponentsBuilder.fromPath("/hotel list/{city}")
		.queryParam("q", "{q}")
		.build("New York", "foo+bar");
val uri = UriComponentsBuilder.fromPath("/hotel list/{city}")
		.queryParam("q", "{q}")
		.build("New York", "foo+bar")

你可以通过使用完整的 URI 模板进一步缩短它，如下例所示：spring-doc.cadn.net.cn

URI uri = UriComponentsBuilder.fromUriString("/hotel list/{city}?q={q}")
		.build("New York", "foo+bar");
val uri = UriComponentsBuilder.fromUriString("/hotel list/{city}?q={q}")
		.build("New York", "foo+bar")

WebClient 和 RestTemplate 通过 UriBuilderFactory 策略在内部展开并编码 URI 模板。两者均可配置自定义策略，如下例所示：spring-doc.cadn.net.cn

String baseUrl = "https://example.com";
DefaultUriBuilderFactory factory = new DefaultUriBuilderFactory(baseUrl)
factory.setEncodingMode(EncodingMode.TEMPLATE_AND_VALUES);

// Customize the RestTemplate..
RestTemplate restTemplate = new RestTemplate();
restTemplate.setUriTemplateHandler(factory);

// Customize the WebClient..
WebClient client = WebClient.builder().uriBuilderFactory(factory).build();
val baseUrl = "https://example.com"
val factory = DefaultUriBuilderFactory(baseUrl).apply {
	encodingMode = EncodingMode.TEMPLATE_AND_VALUES
}

// Customize the RestTemplate..
val restTemplate = RestTemplate().apply {
	uriTemplateHandler = factory
}

// Customize the WebClient..
val client = WebClient.builder().uriBuilderFactory(factory).build()

DefaultUriBuilderFactory 实现内部使用 UriComponentsBuilder 来展开和编码 URI 模板。作为一个工厂，它提供了一个统一的位置来配置编码方式，该方式基于以下其中一种编码模式：spring-doc.cadn.net.cn

  • TEMPLATE_AND_VALUES：使用 UriComponentsBuilder#encode()，对应于前面列表中的第一个选项，在展开时对 URI 模板进行预编码，并严格地对 URI 变量进行编码。spring-doc.cadn.net.cn

  • VALUES_ONLY：不对 URI 模板进行编码，而是在将 URI 变量展开到模板之前，通过 UriUtils#encodeUriVariables 对 URI 变量应用严格的编码。spring-doc.cadn.net.cn

  • URI_COMPONENT：使用 UriComponents#encode()（对应前面列表中的第二个选项），在 URI 变量展开后对 URI 组件值进行编码。spring-doc.cadn.net.cn

  • NONE：不应用任何编码。spring-doc.cadn.net.cn

出于历史原因和向后兼容性考虑，RestTemplate 的编码模式被设置为 EncodingMode.URI_COMPONENT。 WebClient 则依赖于 DefaultUriBuilderFactory 中的默认值，该默认值在 5.0.x 版本中为 EncodingMode.URI_COMPONENT， 而在 5.1 版本中已更改为 EncodingMode.TEMPLATE_AND_VALUES。spring-doc.cadn.net.cn