SpringのUriComponentsBuilderガイド
1. 前書き
このチュートリアルでは、SpringUriComponentsBuilder.に焦点を当てます。具体的には、さまざまな実用的な実装例について説明します。
ビルダーは、UriComponentsクラス(URIコンポーネントの不変コンテナー)と連携して機能します。
新しいUriComponentsBuilderクラスは、構築、テンプレート変数からの展開、エンコードなど、URIの準備のすべての側面をきめ細かく制御できるため、UriComponentsインスタンスの作成に役立ちます。
2. Mavenの依存関係
3. ユースケース
UriComponentsBuilderには、対応するURIコンポーネントで許可されていない文字のコンテキストエンコーディングから始まり、URLの一部を動的に置き換えるまで、多くの実用的なユースケースがあります。
UriComponentsBuilderの最大の利点の1つは、we can inject it right into a controller methodです。
@RequestMapping(method = RequestMethod.POST)
public ResponseEntity createCustomer(UriComponentsBuilder builder) {
// implementation
}
役立つ例を1つずつ説明していきましょう。 JUnitフレームワークを使用して、実装をすぐにテストします。
3.1. URIの構築
最も単純なものから始めましょう。 単純なリンクを作成するためだけにUriComponentsBuilderを使用します。
@Test
public void constructUri() {
UriComponents uriComponents = UriComponentsBuilder.newInstance()
.scheme("http").host("www.example.com").path("/junit-5").build();
assertEquals("/junit-5", uriComponents.toUriString());
}
ご覧のとおり、UriComponentsBuilderの新しいインスタンスを作成してから、スキームタイプ、ホスト、およびリクエストの宛先へのパスを指定しました。
この簡単な例は、Webサイトの他の部分/リンクへのリダイレクトを実行する場合に役立つ可能性があります。
3.2. エンコードされたURIの構築
単純なリンクを作成することに加えて、最終結果をエンコードすることもできます。 これを実際に見てみましょう:
@Test
public void constructUriEncoded() {
UriComponents uriComponents = UriComponentsBuilder.newInstance()
.scheme("http").host("www.example.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.example.com").path("/{article-name}")
.buildAndExpand("junit-5");
assertEquals("/junit-5", uriComponents.toUriString());
}
この例の違いは、パスの宣言方法と最終URIの作成方法です。 キーワードに置き換えられるテンプレートは、path()メソッド内の括弧–\{…},で示されます。 最終リンクの生成に使用されるキーワードは、buildAndExpand(…)という名前のメソッドで使用されます。
置き換えられるキーワードが複数ある場合があることに注意してください。 また、URIへのパスは相対パスにすることができます。
この例は、URIを構築するためのベースとなるSpringControllerにモデルオブジェクトを渡したい場合に非常に役立ちます。
3.4. クエリパラメータを使用したURIの構築
別の非常に便利なケースは、クエリパラメータを使用してURIを作成することです。
URIクエリパラメータを指定するには、UriComponentsBuilderからquery()を使用する必要があります。 次の例を見てみましょう。
@Test
public void constructUriWithQueryParameter() {
UriComponents uriComponents = UriComponentsBuilder.newInstance()
.scheme("http").host("www.google.com")
.path("/").query("q={keyword}").buildAndExpand("example");
assertEquals("http://www.google.com/?q=example", uriComponents.toUriString());
}
クエリはリンクのメイン部分に追加されます。 角かっこ\{…}.を使用して、複数のクエリパラメータを指定できます。これらはbuildAndExpand(…)という名前のメソッドのキーワードに置き換えられます。
このUriComponentsBuilderの実装は、たとえば、RESTAPIのクエリ言語を構築するために使用される可能性があります。
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());
}
上記の例では、リンクの中央部分に必要なのはa-zからの文字と、1-5の間の範囲の長さだけであることがわかります。
また、singletonMapを使用して、キーワードnameを値testに置き換えています。
この例は、ユーザーがリンクを動的に指定できるようにする場合に特に役立ちますが、有効なリンクのみがWebアプリケーションで機能するようなセキュリティを提供したいと考えています。
4. 結論
このチュートリアルでは、UriComponentsBuilderの便利な例を紹介します。
UriComponentsBuilderの主な利点は、URIテンプレート変数を使用できる柔軟性と、SpringControllerメソッドに直接注入できることです。
すべての例と構成は、ここGitHubで入手できます。