URI Links

이 섹션은 URI를 준비하기 위해 Spring Framework에서 사용할 수 있는 다양한 옵션을 설명합니다.

UriComponents

Spring MVC and Spring WebFlux

UriComponentsBuilder는 다음 예제에서 보듯이 변수들을 가진 URI 템플릿으로부터 URI를 빌드하는 데 도움을 줍니다:

1UriComponents uriComponents = UriComponentsBuilder
2		.fromUriString("https://example.com/hotels/{hotel}") // (1)
3		.queryParam("q", "{q}") // (2)
4		.encode() // (3)
5		.build(); // (4)
6
7URI uri = uriComponents.expand("Westin", "123").toUri(); // (5)


1	URI 템플릿을 사용하는 static 팩터리 메서드입니다.
2	URI 컴포넌트를 추가하거나 교체합니다.
3	URI 템플릿과 URI 변수들이 인코딩되도록 요청합니다.
4	`UriComponents`를 빌드합니다.
5	변수를 expand하고 `URI`를 얻습니다.

1val uriComponents = UriComponentsBuilder
2		.fromUriString("https://example.com/hotels/{hotel}") // (1)
3		.queryParam("q", "{q}") // (2)
4		.encode() // (3)
5		.build() // (4)
6
7val uri = uriComponents.expand("Westin", "123").toUri() // (5)


1	URI 템플릿을 사용하는 static 팩터리 메서드입니다.
2	URI 컴포넌트를 추가하거나 교체합니다.
3	URI 템플릿과 URI 변수들이 인코딩되도록 요청합니다.
4	`UriComponents`를 빌드합니다.
5	변수를 expand하고 `URI`를 얻습니다.

앞의 예제는 buildAndExpand를 사용하여 하나의 체인으로 통합하고 단축할 수 있으며, 다음 예제에서 볼 수 있습니다:

1URI uri = UriComponentsBuilder
2		.fromUriString("https://example.com/hotels/{hotel}")
3		.queryParam("q", "{q}")
4		.encode()
5		.buildAndExpand("Westin", "123")
6		.toUri();

1val uri = UriComponentsBuilder
2		.fromUriString("https://example.com/hotels/{hotel}")
3		.queryParam("q", "{q}")
4		.encode()
5		.buildAndExpand("Westin", "123")
6		.toUri()

URI로 직접 가서 (이는 인코딩을 의미합니다) 더 줄일 수 있으며, 다음 예제에서 볼 수 있습니다:

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

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

다음 예제에서 보듯이, 전체 URI 템플릿을 사용하면 더 줄일 수 있습니다:

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

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

UriBuilder

Spring MVC and Spring WebFlux

UriComponentsBuilder는 UriBuilder를 implements합니다. 그에 따라, UriBuilderFactory로 UriBuilder를 생성할 수 있습니다. UriBuilderFactory와 UriBuilder는 함께 기본 URL, 인코딩 기본 설정 및 기타 세부 사항과 같은 공유 설정을 기반으로 URI 템플릿으로부터 URI를 빌드하기 위한 플러그형 메커니즘을 제공합니다.

RestTemplate과 WebClient는 URI의 준비를 커스터마이즈하기 위해 UriBuilderFactory로 설정할 수 있습니다. DefaultUriBuilderFactory는 내부적으로 UriComponentsBuilder를 사용하고 공유 설정 옵션을 노출하는 UriBuilderFactory의 기본 구현입니다.

다음 예제는 RestTemplate을 설정하는 방법을 보여줍니다:

1// import org.springframework.web.util.DefaultUriBuilderFactory.EncodingMode;
2
3String baseUrl = "https://example.org";
4DefaultUriBuilderFactory factory = new DefaultUriBuilderFactory(baseUrl);
5factory.setEncodingMode(EncodingMode.TEMPLATE_AND_VALUES);
6
7RestTemplate restTemplate = new RestTemplate();
8restTemplate.setUriTemplateHandler(factory);

1// import org.springframework.web.util.DefaultUriBuilderFactory.EncodingMode
2
3val baseUrl = "https://example.org"
4val factory = DefaultUriBuilderFactory(baseUrl)
5factory.encodingMode = EncodingMode.TEMPLATE_AND_VALUES
6
7val restTemplate = RestTemplate()
8restTemplate.uriTemplateHandler = factory

다음 예제는 WebClient를 설정합니다:

1// import org.springframework.web.util.DefaultUriBuilderFactory.EncodingMode;
2
3String baseUrl = "https://example.org";
4DefaultUriBuilderFactory factory = new DefaultUriBuilderFactory(baseUrl);
5factory.setEncodingMode(EncodingMode.TEMPLATE_AND_VALUES);
6
7WebClient client = WebClient.builder().uriBuilderFactory(factory).build();

1// import org.springframework.web.util.DefaultUriBuilderFactory.EncodingMode
2
3val baseUrl = "https://example.org"
4val factory = DefaultUriBuilderFactory(baseUrl)
5factory.encodingMode = EncodingMode.TEMPLATE_AND_VALUES
6
7val client = WebClient.builder().uriBuilderFactory(factory).build()

추가로, DefaultUriBuilderFactory를 직접 사용할 수도 있습니다. 이는 UriComponentsBuilder를 사용하는 것과 비슷하지만, static 팩터리 메서드 대신에 설정과 기본 설정을 보유하는 실제 인스턴스이며, 다음 예제에서 볼 수 있습니다:

1String baseUrl = "https://example.com";
2DefaultUriBuilderFactory uriBuilderFactory = new DefaultUriBuilderFactory(baseUrl);
3
4URI uri = uriBuilderFactory.uriString("/hotels/{hotel}")
5		.queryParam("q", "{q}")
6		.build("Westin", "123");

1val baseUrl = "https://example.com"
2val uriBuilderFactory = DefaultUriBuilderFactory(baseUrl)
3
4val uri = uriBuilderFactory.uriString("/hotels/{hotel}")
5		.queryParam("q", "{q}")
6		.build("Westin", "123")

URI Parsing

Spring MVC and Spring WebFlux

UriComponentsBuilder는 두 가지 URI 파서 타입을 지원합니다:

RFC 파서 — 이 파서 타입은 URI 문자열이 RFC 3986 문법을 준수할 것으로 기대하며, 문법에서 벗어나는 것을 illegal로 취급합니다.
WhatWG 파서 — 이 파서는 URL parsing algorithm을 기반으로 하며, WhatWG URL Living standard에 있습니다. 이는 예상치 못한 입력의 다양한 경우를 관대하게 처리합니다. 브라우저는 사용자가 입력한 URL을 관대하게 처리하기 위해 이를 구현합니다. 자세한 내용은 URL Living Standard와 URL parsing test cases를 참조하십시오.

기본적으로, RestClient, WebClient, 그리고 RestTemplate은 RFC 파서 타입을 사용하며, 애플리케이션이 RFC 문법을 준수하는 URL 템플릿을 제공할 것으로 기대합니다. 이를 변경하려면 클라이언트 중 어느 것에서든 UriBuilderFactory를 커스터마이즈할 수 있습니다.

애플리케이션과 프레임워크는 그들 자신의 필요에 따라 UriComponentsBuilder에 더 의존하여 사용자가 제공한 URL을 파싱하고, scheme, host, port, path, query와 같은 URI 컴포넌트를 검사하고, 가능하다면 검증할 수 있습니다. 이러한 컴포넌트는 URL을 더 관대하게 처리하고, 리다이렉트 대상이 입력 URL이거나 브라우저에 대한 응답에 포함되는 경우 브라우저가 URI를 파싱하는 방식과 정렬하기 위해 WhatWG 파서 타입을 사용하기로 결정할 수 있습니다.

URI Encoding

Spring MVC and Spring WebFlux

UriComponentsBuilder는 두 레벨에서 인코딩 옵션을 노출합니다:

UriComponentsBuilder#encode(): 먼저 URI 템플릿을 사전 인코딩한 다음 expand될 때 URI 변수를 엄격하게 인코딩합니다.
UriComponents#encode(): URI 변수가 expand된 후에 URI 컴포넌트를 인코딩합니다.

두 옵션 모두 non-ASCII 및 illegal 문자들을 이스케이프된 옥텟으로 대체합니다. 그러나 첫 번째 옵션은 또한 URI 변수에 나타나는 예약된 의미를 가진 문자들도 대체합니다.


	path에서 legal하지만 예약된 의미를 가진 ";"를 고려해 보십시오. 첫 번째 옵션은 URI 템플릿에서는<br>";"를 그대로 두지만 URI 변수에서는 ";"를 "%3B"로 대체합니다. 반대로 두 번째 옵션은<br>path에서 legal 문자이기 때문에 ";"를 절대 대체하지 않습니다.

대부분의 경우, 첫 번째 옵션이 더 기대에 부합하는 결과를 제공할 가능성이 높습니다. 이는 URI 변수를 완전히 인코딩해야 하는 불투명 데이터로 취급하는 반면, 두 번째 옵션은 URI 변수가 의도적으로 예약 문자를 포함하는 경우에 유용합니다. 두 번째 옵션은 URI 변수를 전혀 expand하지 않을 때도 유용한데, 이 경우에도 우연히 URI 변수처럼 보이는 모든 것을 인코딩하기 때문입니다.

다음 예제는 첫 번째 옵션을 사용합니다:

1URI uri = UriComponentsBuilder.fromPath("/hotel list/{city}")
2		.queryParam("q", "{q}")
3		.encode()
4		.buildAndExpand("New York", "foo+bar")
5		.toUri();
6
7// Result is "/hotel%20list/New%20York?q=foo%2Bbar"

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

앞의 예제는 URI로 직접 가서 (이는 인코딩을 의미합니다) 줄일 수 있으며, 다음 예제에서 볼 수 있습니다:

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

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

다음 예제에서 보듯이, 전체 URI 템플릿을 사용하면 더 줄일 수 있습니다:

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

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

WebClient와 RestTemplate은 내부적으로 UriBuilderFactory 전략을 통해 URI 템플릿을 expand하고 인코딩합니다. 둘 다 커스텀 전략으로 설정할 수 있으며, 다음 예제에서 볼 수 있습니다:

1String baseUrl = "https://example.com";
2DefaultUriBuilderFactory factory = new DefaultUriBuilderFactory(baseUrl);
3factory.setEncodingMode(EncodingMode.TEMPLATE_AND_VALUES);
4
5// Customize the RestTemplate..
6RestTemplate restTemplate = new RestTemplate();
7restTemplate.setUriTemplateHandler(factory);
8
9// Customize the WebClient..
10WebClient client = WebClient.builder().uriBuilderFactory(factory).build();

1val baseUrl = "https://example.com"
2val factory = DefaultUriBuilderFactory(baseUrl).apply {
3	encodingMode = EncodingMode.TEMPLATE_AND_VALUES
4}
5
6// Customize the RestTemplate..
7val restTemplate = RestTemplate().apply {
8	uriTemplateHandler = factory
9}
10
11// Customize the WebClient..
12val client = WebClient.builder().uriBuilderFactory(factory).build()

DefaultUriBuilderFactory 구현은 내부적으로 UriComponentsBuilder를 사용하여 URI 템플릿을 expand하고 인코딩합니다. 팩터리로서, 이는 아래 인코딩 모드 중 하나를 기반으로 인코딩 접근 방식을 설정할 수 있는 단일 위치를 제공합니다:

TEMPLATE_AND_VALUES: earlier list의 첫 번째 옵션에 해당하는 UriComponentsBuilder#encode()를 사용하여 URI 템플릿을 사전 인코딩하고 expand될 때 URI 변수를 엄격하게 인코딩합니다.
VALUES_ONLY: URI 템플릿을 인코딩하지 않고, 대신 expand되기 전에 UriUtils#encodeUriVariables를 통해 URI 변수에 엄격한 인코딩을 적용하여 템플릿에 expand합니다.
URI_COMPONENT: earlier list의 두 번째 옵션에 해당하는 UriComponents#encode()를 사용하여 URI 변수가 expand된 후에 URI 컴포넌트 값을 인코딩합니다.
NONE: 어떤 인코딩도 적용되지 않습니다.

RestTemplate은 역사적인 이유와 하위 호환성을 위해 EncodingMode.URI_COMPONENT로 설정되어 있습니다. WebClient는 DefaultUriBuilderFactory의 기본값에 의존하며, 이는 5.0.x에서는 EncodingMode.URI_COMPONENT였으나 5.1에서는 EncodingMode.TEMPLATE_AND_VALUES로 변경되었습니다.