URI 链接 (URI Links) _ Spring Framework 6.0.23-SNAPSHOT 中文文档(官方文档中文翻译) —

此版本仍在开发中，尚未被视为稳定版本。对于最新的稳定版本，请使用 Spring Framework 6.1.10！Spring中文文档

本节介绍 Spring Framework 中可用于处理 URI 的各种选项。Spring中文文档

UriComponents

Spring MVC 和 Spring WebFluxSpring中文文档

UriComponentsBuilder帮助从具有变量的 URI 模板生成 URI，如以下示例所示：Spring中文文档

JavaSpring中文文档
KotlinSpring中文文档

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`

前面的例子可以合并成一个链，并用缩短为，如以下示例所示：buildAndExpandSpring中文文档

JavaSpring中文文档
KotlinSpring中文文档

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中文文档

JavaSpring中文文档
KotlinSpring中文文档

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中文文档

JavaSpring中文文档
KotlinSpring中文文档

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")

1	具有 URI 模板的静态工厂方法。
2	添加或替换 URI 组件。
3	请求对 URI 模板和 URI 变量进行编码。
4	构建一个 .`UriComponents`
5	展开变量并获取 .`URI`

1	具有 URI 模板的静态工厂方法。
2	添加或替换 URI 组件。
3	请求对 URI 模板和 URI 变量进行编码。
4	构建一个 .`UriComponents`
5	展开变量并获取 .`URI`

UriBuilder的

Spring MVC 和 Spring WebFluxSpring中文文档

UriComponentsBuilder 实现。您可以依次创建一个，并带有 .一起，并提供一种可插入机制，以基于 URI 模板构建 URI 共享配置，例如基本 URL、编码首选项和其他详细信息。UriBuilderUriBuilderUriBuilderFactoryUriBuilderFactoryUriBuilderSpring中文文档

您可以配置和来自定义 URI 的准备。是默认值在内部使用和公开共享配置选项。RestTemplateWebClientUriBuilderFactoryDefaultUriBuilderFactoryUriBuilderFactoryUriComponentsBuilderSpring中文文档

以下示例演示如何配置：RestTemplateSpring中文文档

JavaSpring中文文档
KotlinSpring中文文档

// 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

以下示例配置：WebClientSpring中文文档

JavaSpring中文文档
KotlinSpring中文文档

// 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()

此外，您也可以直接使用。它类似于 use，但它不是静态工厂方法，而是一个实际实例它包含配置和首选项，如以下示例所示：DefaultUriBuilderFactoryUriComponentsBuilderSpring中文文档

JavaSpring中文文档
KotlinSpring中文文档

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中文文档

UriComponentsBuilder在两个级别公开编码选项：Spring中文文档

UriComponentsBuilder#encode（）：首先对 URI 模板进行预编码，然后在展开时严格编码 URI 变量。Spring中文文档
UriComponents#encode（）：在展开 URI 变量后对 URI 组件进行编码。Spring中文文档

这两个选项都将非 ASCII 和非法字符替换为转义八位字节。但是，第一种选择还会替换 URI 变量中显示的具有保留含义的字符。Spring中文文档

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

在大多数情况下，第一个选项可能会给出预期的结果，因为它处理 URI 变量作为要完全编码的不透明数据，而第二个选项在 URI 时很有用变量确实有意包含保留字符。第二个选项也很有用当根本不扩展 URI 变量时，因为这也将编码任何顺便说一句，看起来像一个 URI 变量。Spring中文文档

下面的示例使用第一个选项：Spring中文文档

JavaSpring中文文档
KotlinSpring中文文档

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中文文档

JavaSpring中文文档
KotlinSpring中文文档

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中文文档

JavaSpring中文文档
KotlinSpring中文文档

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")

和展开和编码 URI 模板内部通过策略。两者都可以使用自定义策略进行配置，如以下示例所示：WebClientRestTemplateUriBuilderFactorySpring中文文档

JavaSpring中文文档
KotlinSpring中文文档

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()

该实现在内部使用展开并编码 URI 模板。作为工厂，它提供了一个单一的配置位置基于以下编码模式之一的编码方法：DefaultUriBuilderFactoryUriComponentsBuilderSpring中文文档

TEMPLATE_AND_VALUES：用途，对应于前面列表中的第一个选项，用于对 URI 模板进行预编码，并在以下情况下严格编码 URI 变量扩大。UriComponentsBuilder#encode()Spring中文文档
VALUES_ONLY：不对 URI 模板进行编码，而是应用严格的编码到 URI 变量，然后将它们扩展到模板。UriUtils#encodeUriVariablesSpring中文文档
URI_COMPONENT：使用对应于前面列表中的第二个选项的在 URI 变量展开后对 URI 组件值进行编码。UriComponents#encode()Spring中文文档
NONE：不应用编码。Spring中文文档

设置为历史原因和向后兼容性。依赖于默认值 in ，从 in 更改而来 5.0.x 到 5.1 中。RestTemplateEncodingMode.URI_COMPONENTWebClientDefaultUriBuilderFactoryEncodingMode.URI_COMPONENTEncodingMode.TEMPLATE_AND_VALUESSpring中文文档

相对 Servlet 请求

您可以使用创建相对于当前请求的 URI，如以下示例所示：ServletUriComponentsBuilderSpring中文文档

JavaSpring中文文档
KotlinSpring中文文档

HttpServletRequest request = ...

// Re-uses scheme, host, port, path, and query string...

URI uri = ServletUriComponentsBuilder.fromRequest(request)
		.replaceQueryParam("accountId", "{id}")
		.build("123");

val request: HttpServletRequest = ...

// Re-uses scheme, host, port, path, and query string...

val uri = ServletUriComponentsBuilder.fromRequest(request)
		.replaceQueryParam("accountId", "{id}")
		.build("123")

您可以创建相对于上下文路径的 URI，如以下示例所示：Spring中文文档

JavaSpring中文文档
KotlinSpring中文文档

HttpServletRequest request = ...

// Re-uses scheme, host, port, and context path...

URI uri = ServletUriComponentsBuilder.fromContextPath(request)
		.path("/accounts")
		.build()
		.toUri();

val request: HttpServletRequest = ...

// Re-uses scheme, host, port, and context path...

val uri = ServletUriComponentsBuilder.fromContextPath(request)
		.path("/accounts")
		.build()
		.toUri()

您可以创建相对于 Servlet 的 URI（例如，），如以下示例所示：/main/*Spring中文文档

JavaSpring中文文档
KotlinSpring中文文档

HttpServletRequest request = ...

// Re-uses scheme, host, port, context path, and Servlet mapping prefix...

URI uri = ServletUriComponentsBuilder.fromServletMapping(request)
		.path("/accounts")
		.build()
		.toUri();

val request: HttpServletRequest = ...

// Re-uses scheme, host, port, context path, and Servlet mapping prefix...

val uri = ServletUriComponentsBuilder.fromServletMapping(request)
		.path("/accounts")
		.build()
		.toUri()

从 5.1 开始，忽略来自和标头的信息，这些标头指定客户端源自地址。请考虑使用 ForwardedHeaderFilter 提取并使用或丢弃这样的标头。ServletUriComponentsBuilderForwardedX-Forwarded-*

控制器链接

Spring MVC 提供了一种机制来准备指向控制器方法的链接。例如以下 MVC 控制器允许创建链接：Spring中文文档

JavaSpring中文文档
KotlinSpring中文文档

@Controller
@RequestMapping("/hotels/{hotel}")
public class BookingController {

	@GetMapping("/bookings/{booking}")
	public ModelAndView getBooking(@PathVariable Long booking) {
		// ...
	}
}

@Controller
@RequestMapping("/hotels/{hotel}")
class BookingController {

	@GetMapping("/bookings/{booking}")
	fun getBooking(@PathVariable booking: Long): ModelAndView {
		// ...
	}
}

可以通过按名称引用方法来准备链接，如以下示例所示：Spring中文文档

JavaSpring中文文档
KotlinSpring中文文档

UriComponents uriComponents = MvcUriComponentsBuilder
	.fromMethodName(BookingController.class, "getBooking", 21).buildAndExpand(42);

URI uri = uriComponents.encode().toUri();

val uriComponents = MvcUriComponentsBuilder
	.fromMethodName(BookingController::class.java, "getBooking", 21).buildAndExpand(42)

val uri = uriComponents.encode().toUri()

在前面的示例中，我们提供了实际的方法参数值（在本例中为 long 值：）用作路径变量并插入到 URL 中。此外，我们还提供 value，填充任何剩余的 URI 变量，例如继承的变量从类型级请求映射。如果该方法有更多的参数，我们可以为 URL 不需要参数。一般来说，只有和参数与构造 URL 相关。2142hotel@PathVariable@RequestParamSpring中文文档

还有其他方法可以使用 .例如，您可以使用一种技术类似于通过代理进行模拟测试，以避免按名称引用控制器方法，如以下示例所示（该示例假设静态导入：MvcUriComponentsBuilderMvcUriComponentsBuilder.onSpring中文文档

JavaSpring中文文档
KotlinSpring中文文档

UriComponents uriComponents = MvcUriComponentsBuilder
	.fromMethodCall(on(BookingController.class).getBooking(21)).buildAndExpand(42);

URI uri = uriComponents.encode().toUri();

val uriComponents = MvcUriComponentsBuilder
	.fromMethodCall(on(BookingController::class.java).getBooking(21)).buildAndExpand(42)

val uri = uriComponents.encode().toUri()

控制器方法签名在其设计中受到限制，而它们应该可用于使用 .除了需要适当的参数签名外，返回类型（即生成运行时代理）存在技术限制），因此返回类型不能为。特别视图名称的通用返回类型在这里不起作用。您应该改用甚至普通（带有返回值）。fromMethodCallfinalStringModelAndViewObjectString

前面的示例在中使用的静态方法。在内部，他们依赖 on 从方案、主机、端口、上下文路径和当前请求的 servlet 路径。这在大多数情况下效果很好。但是，有时，它可能是不够的。例如，您可能不在上下文中请求（例如准备链接的批处理），或者可能需要插入路径前缀（例如从请求路径中删除的区域设置前缀，需要重新插入到链接中）。MvcUriComponentsBuilderServletUriComponentsBuilderSpring中文文档

对于这种情况，可以使用接受的静态重载方法来使用基 URL。或者，您可以使用基 URL 创建实例，然后使用基于实例的方法。例如，以下列表用途：fromXxxUriComponentsBuilderMvcUriComponentsBuilderwithXxxwithMethodCallSpring中文文档

JavaSpring中文文档
KotlinSpring中文文档

UriComponentsBuilder base = ServletUriComponentsBuilder.fromCurrentContextPath().path("/en");
MvcUriComponentsBuilder builder = MvcUriComponentsBuilder.relativeTo(base);
builder.withMethodCall(on(BookingController.class).getBooking(21)).buildAndExpand(42);

URI uri = uriComponents.encode().toUri();

val base = ServletUriComponentsBuilder.fromCurrentContextPath().path("/en")
val builder = MvcUriComponentsBuilder.relativeTo(base)
builder.withMethodCall(on(BookingController::class.java).getBooking(21)).buildAndExpand(42)

val uri = uriComponents.encode().toUri()

从 5.1 开始，忽略来自和标头的信息，这些标头指定客户端源自地址。请考虑使用 ForwardedHeaderFilter 提取并使用或丢弃这样的标头。MvcUriComponentsBuilderForwardedX-Forwarded-*

视图中的链接

在 Thymeleaf、FreeMarker 或 JSP 等视图中，可以构建指向带注释的控制器的链接通过引用每个请求映射的隐式或显式分配的名称。Spring中文文档

请看以下示例：Spring中文文档

JavaSpring中文文档
KotlinSpring中文文档

@RequestMapping("/people/{id}/addresses")
public class PersonAddressController {

	@RequestMapping("/{country}")
	public HttpEntity<PersonAddress> getAddress(@PathVariable String country) { ... }
}

@RequestMapping("/people/{id}/addresses")
class PersonAddressController {

	@RequestMapping("/{country}")
	fun getAddress(@PathVariable country: String): HttpEntity<PersonAddress> { ... }
}

给定前面的控制器，您可以准备来自 JSP 的链接，如下所示：Spring中文文档

<%@ taglib uri="http://www.springframework.org/tags" prefix="s" %>
...
<a href="${s:mvcUrl('PAC#getAddress').arg(0,'US').buildAndExpand('123')}">Get Address</a>

前面的示例依赖于 Spring 标记库中声明的函数（即 META-INF/spring.tld），但很容易定义自己的函数或准备一个其他模板技术也类似。mvcUrlSpring中文文档

这是如何工作的。在启动时，每个都会被分配一个默认名称 through ，其默认实现使用类和方法名称的大写字母（例如，中的方法变为“TC#getThing”）。如果存在名称冲突，则可以使用来分配显式名称或实现自己的名称。@RequestMappingHandlerMethodMappingNamingStrategygetThingThingController@RequestMapping(name="..")HandlerMethodMappingNamingStrategySpring中文文档