リクエストマッピング
@RequestMapping メソッドは URL パターンを使用してマッピングできます。Spring MVC は PathPattern を使用しています。これは、 PathContainer として事前に解析された URL パスと照合される、事前解析済みのパターンです。Web での使用向けに設計されたこのソリューションは、エンコードとパスパラメーターを効果的に処理し、効率的にマッチングを行います。パスマッチングオプションのカスタマイズについては、MVC 設定を参照してください。
AntPathMatcher バリアントは効率が低く、文字列パス入力ではエンコードや URL のその他の課題を効果的に処理することが難しいため、非推奨となりました。"/spring" matches "/spring"
"/pages/t?st.html" matches "/pages/test.html" and "/pages/t3st.html"
パスセグメント内の 0 個以上の文字に一致します
"/resources/*.png" matches "/resources/file.png"
"/projects/*/versions" matches "/projects/spring/versions" but does not match "/projects/spring/boot/versions" .
"/projects/*" matches "/projects/spring" but does not match "/projects" as the path segment is not present.
"/resources/**" matches "/resources" , "/resources/file.png" and "/resources/images/file.png"
"/**/info" matches "/info" , "/spring/info" and "/spring/framework/info"
"/resources/**/file.png" is invalid as ** is not allowed in the middle of the path.
"/**/spring/**" is not allowed, as only a single ** / instance is allowed per pattern.
* に似ていますが、パスセグメントを "name" という名前の変数としてキャプチャーします。
"/projects//versions" matches "/projects/spring/versions" and captures project=spring
"/projects//versions" does not match "/projects/spring/framework/versions" as it captures a single path segment.
正規表現 "[a-z]+" を "name" という名前のパス変数として一致させます
"/projects//versions" matches "/projects/spring/versions" but not "/projects/spring1/versions"
** に似ていますが、パスセグメントを "path" という名前の変数としてキャプチャーします。
"/resources/" matches "/resources/images/file.png" and captures file=/images/file.png
"/resources" matches "/spring/framework/resources" and captures path=/spring/framework
パスの途中では が許可されないため、 "/resources//file.png" は無効です。
パターンごとに 1 つの ** / インスタンスのみが許可されるため、 "//spring/**" は許可されません。
キャプチャーされた URI 変数は @PathVariable でアクセスできます。例：
@GetMapping("/owners//pets/") public Pet findPet(@PathVariable Long ownerId, @PathVariable Long petId) < // . > @GetMapping("/owners//pets/") fun findPet(@PathVariable ownerId: Long, @PathVariable petId: Long): Pet < // . >次の例に示すように、クラスおよびメソッドレベルで URI 変数を宣言できます。
@Controller @RequestMapping("/owners/") public class OwnerController < @GetMapping("/pets/") public Pet findPet(@PathVariable Long ownerId, @PathVariable Long petId) < // . >> @Controller @RequestMapping("/owners/") class OwnerController < @GetMapping("/pets/") fun findPet(@PathVariable ownerId: Long, @PathVariable petId: Long): Pet < // . >>URI 変数は適切な型に自動的に変換されるか、 TypeMismatchException が発生します。単純型（ int 、 long 、 Date など）はデフォルトでサポートされており、他のデータ型のサポートを登録できます。型変換および DataBinder を参照してください。
URI 変数に明示的に名前を付けることができますが (たとえば、 @PathVariable("customId") )、名前が同じで、コードが -parameters コンパイラーフラグでコンパイルされている場合は、その詳細を省略できます。
構文 は、 の構文を持つ正規表現で URI 変数を宣言します。例: URL "/spring-web-3.0.5.jar" を指定すると、次のメソッドは名前、バージョン、ファイル拡張子を抽出します。
@GetMapping("/-") public void handle(@PathVariable String name, @PathVariable String version, @PathVariable String ext) < // . > @GetMapping("/-") fun handle(@PathVariable name: String, @PathVariable version: String, @PathVariable ext: String) < // . >- 埋め込み $ プレースホルダは、起動時にローカル、システム、環境、その他のプロパティソースに対して PropertySourcesPlaceholderConfigurer を介して解決されます。これは、たとえば外部設定に基づいてベース URL をパラメーター化する場合に役立ちます。
- SpEL 式 # 。
パターン比較
複数のパターンが URL に一致する場合は、最適なものを選択する必要があります。これは、解析された PathPattern の使用が有効になっているかどうかに応じて、次のいずれかで実行されます。
- PathPattern.SPECIFICITY_COMPARATOR (Javadoc)
- AntPathMatcher.getPatternComparator(String path) (Javadoc)
どちらも、より具体的なパターンを上位にしてパターンを並べ替えるのに役立ちます。URI 変数の数 (1 としてカウント)、単一のワイルドカード (1 としてカウント)、および二重ワイルドカード (2 としてカウント) の数が少ないほど、パターンはより具体的になります。スコアが等しい場合、より長いパターンが選択されます。同じスコアと長さの場合、ワイルドカードよりも多くの URI 変数を含むパターンが選択されます。
デフォルトのマッピングパターン（ /** ）はスコアリングから除外され、常に最後にソートされます。また、プレフィックスパターン（ /public/** など）は、二重ワイルドカードを持たない他のパターンよりも特定性が低いと見なされます。
サフィックスマッチと RFD
反射ファイルダウンロード（RFD）攻撃は、レスポンスに反映されるリクエスト入力（クエリパラメーターや URI 変数など）に依存するという点で XSS に似ています。ただし、JavaScript を HTML に挿入する代わりに、ブラウザーを切り替えてダウンロードを実行し、後でダブルクリックしたときにレスポンスを実行可能なスクリプトとして処理することに依存します。
Spring MVC では、 @ResponseBody および ResponseEntity メソッドが危険にさらされます。これは、クライアントが URL パス拡張を介してリクエストできるさまざまなコンテンツ型をレンダリングできるためです。サフィックスパターンマッチングを無効にし、コンテンツネゴシエーションにパス拡張を使用すると、リスクは低下しますが、RFD 攻撃を防ぐには不十分です。
RFD 攻撃を防ぐために、Spring MVC は、レスポンス本文をレンダリングする前に、固定された安全なダウンロードファイルを提案する Content-Disposition:inline;filename=f.txt ヘッダーを追加します。これは、URL パスに、コンテンツネゴシエーションに対して安全として許可されておらず、明示的に登録されていないファイル拡張子が含まれている場合にのみ行われます。ただし、URL をブラウザーに直接入力すると、副作用が生じる可能性があります。
多くの一般的なパス拡張は、デフォルトで安全として許可されています。カスタム HttpMessageConverter 実装を使用するアプリケーションは、コンテンツネゴシエーションのファイル拡張子を明示的に登録して、それらの拡張子に Content-Disposition ヘッダーが追加されないようにすることができます。コンテンツタイプを参照してください。
RFD に関連する追加の推奨事項については、CVE-2015-5211 (英語) を参照してください。
消費可能なメディア型
次の例に示すように、リクエストの Content-Type に基づいてリクエストマッピングを絞り込むことができます。
@PostMapping(path = "/pets", consumes = "application/json") (1) public void addPet(@RequestBody Pet pet) < // . > 1 consumes 属性を使用して、コンテンツ型ごとにマッピングを絞り込みます。 @PostMapping("/pets", consumes = ["application/json"]) (1) fun addPet(@RequestBody pet: Pet) < // . > 1 consumes 属性を使用して、コンテンツ型ごとにマッピングを絞り込みます。consumes 属性は否定表現もサポートします。たとえば、 !text/plain は text/plain 以外のコンテンツ型を意味します。
クラスレベルで共有 consumes 属性を宣言できます。ただし、他のほとんどのリクエストマッピング属性とは異なり、クラスレベルで使用する場合、メソッドレベルの consumes 属性はクラスレベルの宣言を継承するのではなくオーバーライドします。
MediaType は、 APPLICATION_JSON_VALUE や APPLICATION_XML_VALUE などの一般的に使用されるメディア型に定数を提供します。生産可能なメディア型
次の例に示すように、 Accept リクエストヘッダーとコントローラーメソッドが生成するコンテンツ型のリストに基づいて、リクエストマッピングを絞り込むことができます。
@GetMapping(path = "/pets/", produces = "application/json") (1) @ResponseBody public Pet getPet(@PathVariable String petId) < // . > 1 produces 属性を使用して、コンテンツ型ごとにマッピングを絞り込みます。 @GetMapping("/pets/", produces = ["application/json"]) (1) @ResponseBody fun getPet(@PathVariable petId: String): Pet < // . > 1 produces 属性を使用して、コンテンツ型ごとにマッピングを絞り込みます。メディア型は文字セットを指定できます。否定式がサポートされています。たとえば、 !text/plain は、"text/plain" 以外のすべてのコンテンツ型を意味します。
クラスレベルで共有 produces 属性を宣言できます。ただし、他のほとんどのリクエストマッピング属性とは異なり、クラスレベルで使用する場合、メソッドレベルの produces 属性はクラスレベルの宣言を継承するのではなくオーバーライドします。
MediaType は、 APPLICATION_JSON_VALUE や APPLICATION_XML_VALUE などの一般的に使用されるメディア型に定数を提供します。パラメーター、ヘッダー
リクエストパラメーターの条件に基づいて、リクエストマッピングを絞り込むことができます。リクエストパラメーターの存在（ myParam ）、パラメーターの不在（ !myParam ）、特定の値（ myParam=myValue ）をテストできます。次の例は、特定の値をテストする方法を示しています。
@GetMapping(path = "/pets/", params = "myParam=myValue") (1) public void findPet(@PathVariable String petId) < // . > 1 myParam が myValue と等しいかどうかのテスト。 @GetMapping("/pets/", params = ["myParam=myValue"]) (1) fun findPet(@PathVariable petId: String) < // . > 1 myParam が myValue と等しいかどうかのテスト。 @GetMapping(path = "/pets/", headers = "myHeader=myValue") (1) public void findPet(@PathVariable String petId) < // . > 1 myHeader が myValue と等しいかどうかのテスト。 @GetMapping("/pets/", headers = ["myHeader=myValue"]) (1) fun findPet(@PathVariable petId: String) < // . > 1 myHeader が myValue と等しいかどうかのテスト。 Content-Type および Accept をヘッダー条件と一致させることができますが、代わりに consumes と produces を使用することをお勧めします。API バージョン
API バージョンを指定する標準的な方法はないため、MVC 構成で API バージョン管理を有効にする場合は、バージョン解決方法を指定する必要があります。MVC 構成は ApiVersionStrategy を作成し、リクエストのマッピングに使用されます。
API のバージョン管理を有効にすると、リクエストをバージョンにマッピングできるようになります。 @RequestMapping 、 version 属性は以下をサポートします。
- 固定バージョン（ "1.2" ） — 指定されたバージョンのみに一致します
- ベースラインバージョン（ "1.2+" ） — 上記の指定されたサポートされているバージョンと一致します
- 値がありません — どのバージョンにも一致しますが、より具体的なバージョンの一致によって置き換えられます
バージョン "1.3" のリクエストの場合:
- (1) はどのバージョンにも一致する
- (2) 一致しない
- (3) は 1.2 以上と一致し、最も高い一致として選択される。
- (4) の方が高く、一致しない
バージョン "1.5" のリクエストの場合:
- (1) はどのバージョンにも一致する
- (2) 一致しない
- (3) は 1.2 以上に一致するため一致する
- (4) が一致し、最も高い一致として選択される
バージョン "1.6" のリクエストには一致するものがありません。(1) および (3) は一致しますが、(4) によって置き換えられます。(4) は厳密な一致のみを許可するため、一致しません。このシナリオでは、 NotAcceptableApiVersionException は 400 レスポンスを返します。
基盤となるインフラストラクチャと API バージョン管理のサポートの詳細については、API のバージョニングを参照してください。
HTTP HEAD, OPTIONS
@GetMapping （および @RequestMapping(method=HttpMethod.GET) ）は、リクエストマッピングのために HTTP HEAD を透過的にサポートします。コントローラーのメソッドを変更する必要はありません。 jakarta.servlet.http.HttpServlet で適用されるレスポンスラッパーは、 Content-Length ヘッダーが（実際にレスポンスに書き込まずに）書き込まれたバイト数に設定されるようにします。
デフォルトでは、HTTP OPTIONS は、 Allow レスポンスヘッダーを、一致する URL パターンを持つすべての @RequestMapping メソッドにリストされている HTTP メソッドのリストに設定することによって処理されます。
HTTP メソッド宣言のない @RequestMapping の場合、 Allow ヘッダーは GET,HEAD,POST,PUT,PATCH,DELETE,OPTIONS に設定されます。コントローラーメソッドは、サポートされている HTTP メソッドを常に宣言する必要があります（たとえば、HTTP メソッド固有のバリアント（ @GetMapping 、 @PostMapping など）を使用する）。
@RequestMapping メソッドを明示的に HTTP HEAD および HTTP OPTIONS にマップできますが、これは一般的なケースでは必要ありません。
カスタムアノテーション
Spring MVC は、リクエストマッピングのための構成済みアノテーションの使用をサポートしています。それらは、それ自体が @RequestMapping でメタアノテーションが付けられたアノテーションであり、 @RequestMapping 属性のサブセット (またはすべて) をより狭く、より具体的な目的で再宣言するように構成されています。
@GetMapping 、 @PostMapping 、 @PutMapping 、 @DeleteMapping 、 @PatchMapping は、合成されたアノテーションの例です。これらが提供されるのは、おそらく、デフォルトですべての HTTP メソッドに一致する @RequestMapping を使用するのではなく、ほとんどのコントローラーメソッドを特定の HTTP メソッドにマップする必要があるためです。合成されたアノテーションを実装する方法の例が必要な場合は、それらがどのように宣言されているかを確認してください。
@RequestMapping は、同じ要素 (クラス、インターフェース、メソッド) で宣言されている他の @RequestMapping アノテーションと組み合わせて使用することはできません。同じ要素で複数の @RequestMapping アノテーションが検出された場合、警告がログに記録され、最初のマッピングのみが使用されます。これは、 @GetMapping 、 @PostMapping などの合成 @RequestMapping アノテーションにも当てはまります。Spring MVC は、カスタムリクエストマッチングロジックを使用したカスタムリクエストマッピング属性もサポートしています。これは、 RequestMappingHandlerMapping のサブクラス化と getCustomMethodCondition メソッドのオーバーライドを必要とするより高度なオプションであり、カスタム属性をチェックして独自の RequestCondition を返すことができます。
明示的な登録
ハンドラーメソッドをプログラムで登録できます。これは、動的な登録や、異なる URL での同じハンドラーの異なるインスタンスなどの高度なケースに使用できます。次の例では、ハンドラーメソッドを登録します。
@Configuration public class MyConfiguration < // Inject the target handler and the handler mapping for controllers @Autowired public void setHandlerMapping(RequestMappingHandlerMapping mapping, UserHandler handler) throws NoSuchMethodException < // Prepare the request mapping meta data RequestMappingInfo info = RequestMappingInfo .paths("/user/").methods(RequestMethod.GET).build(); // Get the handler method Method method = UserHandler.class.getMethod("getUser", Long.class); // Add the registration mapping.registerMapping(info, handler, method); > > @Configuration class MyConfiguration < // Inject the target handler and the handler mapping for controllers @Autowired fun setHandlerMapping(mapping: RequestMappingHandlerMapping, handler: UserHandler) < // Get the handler method val info = RequestMappingInfo.paths("/user/").methods(RequestMethod.GET).build() // Get the handler method val method = UserHandler::class.java.getMethod("getUser", Long::class.java) // Add the registration mapping.registerMapping(info, handler, method) > >@HttpExchange
@HttpExchange の主な目的は、生成されたプロキシを用いて HTTP クライアントコードを抽象化することですが、このようなアノテーションが配置されるインターフェースは、クライアントとサーバーの使用形態に中立な契約です。クライアントコードを簡素化するだけでなく、HTTP サービスクライアントはサーバーがクライアントアクセス用に API を公開するための便利なメソッドとなる場合もあります。これはクライアントとサーバーの結合度を高めるため、特にパブリック API の場合は必ずしも良い選択とは言えませんが、内部 API の場合はまさに理想的な選択肢となる可能性があります。これは Spring Cloud で一般的に使用されるアプローチであり、コントローラークラスにおけるサーバー側処理において @RequestMapping の代替として @HttpExchange がサポートされているのもこのためです。
@HttpExchange("/persons") interface PersonService < @GetExchange("/") Person getPerson(@PathVariable Long id); @PostExchange void add(@RequestBody Person person); > @RestController class PersonController implements PersonService < public Person getPerson(@PathVariable Long id) < // . >@ResponseStatus(HttpStatus.CREATED) public void add(@RequestBody Person person) < // . >> @HttpExchange("/persons") interface PersonService < @GetExchange("/") fun getPerson(@PathVariable id: Long): Person @PostExchange fun add(@RequestBody person: Person) > @RestController class PersonController : PersonService < override fun getPerson(@PathVariable id: Long): Person < // . >@ResponseStatus(HttpStatus.CREATED) override fun add(@RequestBody person: Person) < // . >>@HttpExchange と @RequestMapping には違いがあります。 @RequestMapping はパスパターン、HTTP メソッドなどによって任意の数のリクエストにマップできますが、 @HttpExchange は具体的な HTTP メソッド、パス、コンテンツ型を使用して単一のエンドポイントを宣言します。
メソッドパラメーターと戻り値については、通常、 @HttpExchange は @RequestMapping が行うメソッドパラメーターのサブセットをサポートします。特に、サーバー側固有のパラメーター型は除外されます。詳細は @HttpExchange、@RequestMapping の一覧を参照してください。
@HttpExchange は、クライアント側の @RequestMapping(headers=) と同様に "name=value" -like ペアを受け入れる headers() パラメーターもサポートします。サーバー側では、これは @RequestMapping がサポートする完全な構文に拡張されます。
- 7.1.0-SNAPSHOT
- 7.0.7-SNAPSHOT
- 6.2.18-SNAPSHOT
- Spring の関連ドキュメント
- Spring Boot
- Spring Framework
- Spring Cloud
- Spring Cloud Build
- Spring Cloud Bus
- Spring Cloud Circuit Breaker
- Spring Cloud Commons
- Spring Cloud Config
- Spring Cloud Consul
- Spring Cloud Contract
- Spring Cloud Function
- Spring Cloud Gateway
- Spring Cloud Kubernetes
- Spring Cloud Netflix
- Spring Cloud OpenFeign
- Spring Cloud Stream
- Spring Cloud Task
- Spring Cloud Vault
- Spring Cloud Zookeeper
- Spring Data Cassandra
- Spring Data Commons
- Spring Data Couchbase
- Spring Data Elasticsearch
- Spring Data JPA
- Spring Data KeyValue
- Spring Data LDAP
- Spring Data MongoDB
- Spring Data Neo4j
- Spring Data Redis
- Spring Data JDBC & R2DBC
- Spring Data REST
- Spring Authorization Server
- Spring LDAP
- Spring Security Kerberos
- Spring Session
- Spring Vault
Copyright © 2005 - Broadcom. All Rights Reserved. The term "Broadcom" refers to Broadcom Inc. and/or its subsidiaries.Terms of Use • Privacy • Trademark Guidelines • Thank you • Your California Privacy Rights
Apache®, Apache Tomcat®, Apache Kafka®, Apache Cassandra™, and Apache Geode™ are trademarks or registered trademarks of the Apache Software Foundation in the United States and/or other countries. Java™, Java™ SE, Java™ EE, and OpenJDK™ are trademarks of Oracle and/or its affiliates. Kubernetes® is a registered trademark of the Linux Foundation in the United States and other countries. Linux® is the registered trademark of Linus Torvalds in the United States and other countries. Windows® and Microsoft® Azure are registered trademarks of Microsoft Corporation. “AWS” and “Amazon Web Services” are trademarks or registered trademarks of Amazon.com Inc. or its affiliates. All other trademarks and copyrights are property of their respective owners and are only mentioned for informative purposes. Other names may be trademarks of their respective owners.