1. Введение
В этом руководстве мы сосредоточимся на Spring UriComponentsBuilder. Более конкретно, мы опишем различные примеры практической реализации.
Построитель работает в связке с классом UriComponents — неизменяемым контейнером для компонентов URI.
Новый класс UriComponentsBuilder помогает создавать экземпляры UriComponents , обеспечивая детальный контроль над всеми аспектами подготовки URI, включая построение, расширение из переменных шаблона и кодирование.
2. Зависимости Maven
Чтобы использовать сборщик, нам нужно включить следующий раздел в зависимости нашего pom.xml :
<dependency>
<groupId>org.springframework</groupId>
<artifactId>spring-web</artifactId>
<version>5.2.2.RELEASE</version>
</dependency>
Последнюю версию можно найти здесь .
Эта зависимость распространяется только на Spring Web, поэтому не забудьте добавить spring-context для полноценного веб-приложения.
Нам конечно же нужно настроить логирование для проекта — подробнее об этом здесь .
3. Варианты использования
Существует множество практических вариантов использования UriComponentsBuilder , начиная с контекстной кодировки символов, не разрешенных в соответствующем компоненте URI, заканчивая динамической заменой частей URL-адреса.
Одним из самых больших преимуществ UriComponentsBuilder является то, что мы можем внедрить его прямо в метод контроллера :
@RequestMapping(method = RequestMethod.POST)
public ResponseEntity createCustomer(UriComponentsBuilder builder) {
// implementation
}
Давайте начнем описывать полезные примеры один за другим. Мы будем использовать среду JUnit для немедленного тестирования наших реализаций.
3.1. Создание URI
Начнем с самого простого. Мы хотим использовать UriComponentsBuilder только для создания простой ссылки:
@Test
public void constructUri() {
UriComponents uriComponents = UriComponentsBuilder.newInstance()
.scheme("http").host("www.foreach.com").path("/junit-5").build();
assertEquals("/junit-5", uriComponents.toUriString());
}
Как мы видим, мы создали новый экземпляр UriComponentsBuilder , затем предоставили тип схемы, хост и путь к месту назначения запроса.
Этот простой пример может быть полезен, когда мы хотим выполнить перенаправление на другую часть/ссылку нашего веб-сайта.
3.2. Создание закодированного URI
Помимо создания простой ссылки, мы можем захотеть закодировать окончательный результат. Давайте посмотрим это на практике:
@Test
public void constructUriEncoded() {
UriComponents uriComponents = UriComponentsBuilder.newInstance()
.scheme("http").host("www.foreach.com").path("/junit 5").build().encode();
assertEquals("/junit%205", uriComponents.toUriString());
}
Отличие в этом примере в том, что мы хотим добавить пробел между словом junit и цифрой 5 . Согласно RFC 3986 , это невозможно. Нам нужно закодировать ссылку, чтобы получить правильный результат, используя метод encode() .
3.3. Создание URI из шаблона
Шаблоны URI разрешены в большинстве компонентов URI, но их значение ограничено конкретным элементом, который мы указываем как шаблон. Давайте посмотрим на пример, чтобы пояснить:
@Test
public void constructUriFromTemplate() {
UriComponents uriComponents = UriComponentsBuilder.newInstance()
.scheme("http").host("www.foreach.com").path("/{article-name}")
.buildAndExpand("junit-5");
assertEquals("/junit-5", uriComponents.toUriString());
}
Разница в этом примере заключается в том, как мы объявляем путь и как мы строим окончательный URI. Шаблон, который будет заменен ключевыми словами, указывается в скобках — {…}, внутри метода path() . Ключевое слово, используемое для создания окончательной ссылки, используется в методе с именем buildAndExpand(…) .
Обратите внимание, что может потребоваться замена нескольких ключевых слов. Кроме того, путь к URI может быть относительным.
Этот пример будет очень полезен, когда мы хотим передать объекты модели контроллеру Spring, на основе которого мы создадим URI.
3.4. Создание URI с параметрами запроса
Еще один очень полезный случай — создать URI с параметрами запроса.
Нам нужно использовать query() из UriComponentsBuilder , чтобы указать параметры запроса URI. Давайте посмотрим на следующий пример:
@Test
public void constructUriWithQueryParameter() {
UriComponents uriComponents = UriComponentsBuilder.newInstance()
.scheme("http").host("www.google.com")
.path("/").query("q={keyword}").buildAndExpand("foreach");
assertEquals("http://www.google.com/?q=foreach", uriComponents.toUriString());
}
Запрос будет добавлен в основную часть ссылки. Мы можем указать несколько параметров запроса, используя скобки {…}. Они будут заменены ключевыми словами в методе с именем buildAndExpand(…) .
Эта реализация UriComponentsBuilder может использоваться, например, для создания языка запросов для REST API.
3.5. Расширение URI с помощью регулярных выражений
В последнем примере показана конструкция URI с проверкой регулярным выражением. Мы сможем расширить uriComponents только в том случае, если проверка регулярного выражения будет успешной:
@Test
public void expandWithRegexVar() {
String template = "/myurl/{name:[a-z]{1,5}}/show";
UriComponents uriComponents = UriComponentsBuilder.fromUriString(template)
.build();
uriComponents = uriComponents.expand(Collections.singletonMap("name", "test"));
assertEquals("/myurl/test/show", uriComponents.getPath());
}
В приведенном выше примере мы видим, что средняя часть ссылки должна содержать только буквы от az и длину в диапазоне от 1 до 5 .
Кроме того, мы используем singletonMap , чтобы заменить имя ключевого слова значением test .
Этот пример особенно полезен, когда мы позволяем пользователю динамически указывать ссылки, но мы хотим обеспечить своего рода безопасность, когда в нашем веб-приложении работают только действительные ссылки.
4. Вывод
В этом руководстве представлены полезные примеры UriComponentsBuilder .
Основными преимуществами UriComponentsBuilder являются гибкость использования переменных шаблона URI и возможность внедрения их непосредственно в методы Spring Controller.
Все примеры и конфигурации доступны здесь, на GitHub .