Guide to UriComponentsBuilder in Spring – Spring中的UriComponentsBuilder指南

最后修改: 2016年 11月 25日


1. Introduction


In this tutorial, we are going to focus on the Spring UriComponentsBuilder. More specifically, we’ll describe various practical implementation examples.

在本教程中,我们将重点介绍Spring UriComponentsBuilder。更具体地说,我们将描述各种实际的实现例子。

The builder works in conjunction with the UriComponents class – an immutable container for URI components.


A new UriComponentsBuilder class helps to create UriComponents instances by providing fine-grained control over all aspects of preparing a URI including construction, expansion from template variables, and encoding.


2. Maven Dependencies


In order to use the builder, we need to include the following section in the dependencies of our pom.xml:



The latest version can be found here.


This dependency only covers Spring Web so don’t forget to add spring-context for a full web application.

这个依赖关系只包括Spring Web,所以别忘了为一个完整的Web应用添加spring-context

We of course also need to set up logging for the project – more on that here.

当然,我们还需要为项目设置日志 – 关于这一点,请看

3. Use Cases


There are many practical use cases for the UriComponentsBuilder, starting from a contextual encoding of characters not permitted in the corresponding URI component, finishing on replacing parts of the URL dynamically.


One of the biggest advantages of UriComponentsBuilder is that we can inject it right into a controller method:


@RequestMapping(method = RequestMethod.POST)
public ResponseEntity createCustomer(UriComponentsBuilder builder) {
    // implementation

Let’s start describing useful examples one by one. We’ll use the JUnit framework to test our implementations immediately.


3.1. Constructing a URI


Let’s start with the simplest one. We want to use UriComponentsBuilder just to create simple link:


public void constructUri() {
    UriComponents uriComponents = UriComponentsBuilder.newInstance()

    assertEquals("/junit-5", uriComponents.toUriString());

As we may observe, we created a new instance of UriComponentsBuilder, then we provided scheme type, host, and a path to the request destination.


This simple example might be useful when we want to perform a redirect to other part/link of our website.


3.2. Constructing an Encoded URI


In addition to creating a simple link, we may want to encode the final result. Let’s see this in practice:


public void constructUriEncoded() {
    UriComponents uriComponents = UriComponentsBuilder.newInstance()
      .scheme("http").host("").path("/junit 5").build().encode();

    assertEquals("/junit%205", uriComponents.toUriString());

The difference in this example is that we want to add space between the word junit and number 5. Accordingly to the RFC 3986, it would not be possible. We need to encode the link to achieve the valid result, using encode() method.

这个例子的不同之处在于,我们想在单词junit和数字5之间添加空格。根据RFC 3986的规定,这是不可能的。我们需要对链接进行编码以达到有效的结果,使用encode()方法。

3.3. Constructing a URI from a Template


URI templates are allowed in the most components of a URI but their value is restricted to a particular element, that we indicate as a template. Let’s see the example to clarify:


public void constructUriFromTemplate() {
    UriComponents uriComponents = UriComponentsBuilder.newInstance()

    assertEquals("/junit-5", uriComponents.toUriString());

The difference in this example is in the way we declare the path and how we build the final URI. Template that will be replaced by keywords is indicated by brackets – {…}, inside the path() method. The keyword that is used to generate the final link is used in the method named buildAndExpand(…).

这个例子的不同之处在于我们声明路径的方式以及我们如何建立最终的URI。将被关键词替换的模板用括号表示 – {…}, path()方法中。用于生成最终链接的关键词被用于名为buildAndExpand(…)的方法中。

Please note, that there might be more than one keyword to be replaced. Also, the path to the URI can be relative.


This example will be very helpful when we would like to pass model objects to the Spring Controller based on which we’ll build a URI.


3.4. Constructing a URI With Query Parameters


Another very useful case is to create URI with query parameters.


We need to use query() from UriComponentsBuilder to specify URI query parameters. Let’s see the following example:


public void constructUriWithQueryParameter() {
    UriComponents uriComponents = UriComponentsBuilder.newInstance()

     assertEquals("", uriComponents.toUriString());

The query will be added to the main part of the link. We can provide multiple query parameters, using brackets {…}. They will be replaced by keywords in the method named buildAndExpand(…).


This implementation of UriComponentsBuilder might be used to build – for example – a query language for a REST API.

这个UriComponentsBuilder的实现可用于构建–例如–REST API的查询语言。

3.5. Expanding a URI With Regular Expressions


The last example is showing a construction of a URI with regex validation. We’ll be able to expand the uriComponents only if regex validation will be successful:


public void expandWithRegexVar() {
    String template = "/myurl/{name:[a-z]{1,5}}/show";
    UriComponents uriComponents = UriComponentsBuilder.fromUriString(template)
    uriComponents = uriComponents.expand(Collections.singletonMap("name", "test"));
    assertEquals("/myurl/test/show", uriComponents.getPath());

In the above-mentioned example, we can see that the middle part of the link needs to have only letters from a-z and the length in a range between 1-5.


Also, we’re using singletonMap, to replace keyword name with value test.


This example is particularly useful when we enable a user to specify links dynamically, but we want to provide a sort of security where only valid links work in our web application.


4. Conclusion


This tutorial presents useful examples of the UriComponentsBuilder.


The main advantages of UriComponentsBuilder are the flexibility of using URI template variables, and a possibility of injecting it directly into Spring Controller methods.


All examples and configurations are available here on GitHub.