Mastering Spring's UriComponentsBuilder: Build and Encode URIs Efficiently

Environment: Spring 2.7.16

1. UriComponents

UriComponentsBuilder helps build a URI from a template with variables. Example:

UriComponents uriComponents = UriComponentsBuilder
    .fromUriString("http://www.pack.com/users/{name}")
    .queryParam("q", "{q}")
    .encode()
    .build();
URI uri = uriComponents.expand("name", "pack").toUri();
System.out.println(uri);

Output: http://www.pack.com/hotels/name?q=pack You can also build directly with a URI:

URI uri = UriComponentsBuilder
    .fromUriString("http://www.pack.com/users/{name}")
    .queryParam("q", "{q}")
    .build("name", "pack");
System.out.println(uri);

Or use a compact template form:

URI uri = UriComponentsBuilder
    .fromUriString("http://www.pack.com/users/{name}?q={q}")
    .build("name", "pack");

2. UriBuilder

UriComponentsBuilder implements UriBuilder. UriBuilderFactory can create UriBuilder instances, allowing shared configuration (base URL, encoding mode, etc.) for RestTemplate and WebClient. DefaultUriBuilderFactory is the default implementation.

Example with RestTemplate:

String baseUrl = "http://www.pack.com";
DefaultUriBuilderFactory factory = new DefaultUriBuilderFactory(baseUrl);
factory.setEncodingMode(EncodingMode.TEMPLATE_AND_VALUES);

RestTemplate restTemplate = new RestTemplate();
restTemplate.setUriTemplateHandler(factory);

Example with WebClient:

DefaultUriBuilderFactory factory = new DefaultUriBuilderFactory(baseUrl);
factory.setEncodingMode(EncodingMode.TEMPLATE_AND_VALUES);

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

Creating a URI directly:

DefaultUriBuilderFactory uriBuilderFactory = new DefaultUriBuilderFactory(baseUrl);
URI uri = uriBuilderFactory.uriString("/users/{name}")
    .queryParam("q", "pack")
    .build("name", "pack");
System.out.println(uri);

Output:

http://www.pack.com/users/name?q=pack

3. URI Encoding

UriComponentsBuilder provides two encoding options:

UriComponentsBuilder#encode(): pre‑encodes the URI template and then strictly encodes variables during expansion.

UriComponents#encode(): encodes the URI components after variable expansion.

Usually the first option yields the expected result, while the second is useful when variables intentionally contain reserved characters or when no expansion occurs.

URI uri = UriComponentsBuilder.fromPath("/users list/{name}")
    .queryParam("q", "{q}")
    .encode()
    .buildAndExpand("name", "pack")
    .toUri();
System.out.println(uri);

Output: /users%20list/name?q=pack Simplified version:

URI uri = UriComponentsBuilder.fromPath("/users list/{name}")
    .queryParam("q", "{q}")
    .build("name", "pack");

Full template example:

URI uri = UriComponentsBuilder.fromUriString("/users list/{name}?q={q}")
    .build("name", "pack");

4. Servlet Request

ServletUriComponentsBuilder can create a URI relative to the current request:

MockHttpServletRequest request = new MockHttpServletRequest();
request.setRequestURI("/users");
URI uri = ServletUriComponentsBuilder.fromRequest(request)
    .replaceQueryParam("id", "{id}")
    .build("666");
System.out.println(uri);

Output: http://localhost/users?id=666 You can also build a URI relative to the context path:

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

5. Linking to a Controller

Spring MVC’s MvcUriComponentsBuilder can generate a link to a controller method:

MockHttpServletRequest request = new MockHttpServletRequest();
ServletRequestAttributes requestAttribute = new ServletRequestAttributes(request);
RequestContextHolder.setRequestAttributes(requestAttribute);
UriComponents uriComponents = MvcUriComponentsBuilder
    .fromMethodName(UserController.class, "queryById", 666L)
    .buildAndExpand();
URI uri = uriComponents.encode().toUri();
System.out.println(uri);

Output: http://localhost/users/666 That concludes the article.