Spring Bootのヘッダー操作を徹底解説！Location・Retry-After・CORSの設定方法まとめ

Spring Bootのヘッダー操作：Location/Retry-After/CORS系の付け方

教材紹介 Spring Boot 学習のおすすめ教材

Spring Bootを使ったWebアプリケーション開発を、環境構築から実践まで一通り学びたい方には、定評のある入門書が参考になります。

Spring Boot 3 プログラミング入門をAmazonで見る

※ Amazon広告リンク

先生と生徒の会話形式で理解しよう

生徒

「先生、Spring BootでHTTPレスポンスのヘッダーを自由に設定するにはどうすればいいですか？」

先生

「良い質問ですね。LocationヘッダーやRetry-After、そしてCORS関連ヘッダーも、Spring Bootで柔軟に制御できますよ。」

生徒

「Locationってリダイレクトのとき使うやつですか？Retry-Afterは聞いたことないです…」

先生

「そのとおり。では、ヘッダー操作の基本から、Spring Bootでの実装例まで一緒に確認していきましょう！」

1. Spring BootでHTTPレスポンスヘッダーを操作する基本

Spring Bootでは、ResponseEntityやHttpServletResponseを使ってレスポンスヘッダーを自由に操作できます。HTTPヘッダーは、APIの動作を制御したり、ブラウザやクライアントに指示を出すための重要な要素です。

たとえば、リダイレクト先の指定にはLocationヘッダー、再試行を促すにはRetry-Afterヘッダー、セキュリティやCORS制御にはAccess-Control-Allow-Originなどが使われます。

2. Locationヘッダーの設定方法と用途

Locationヘッダーは、HTTPステータスコード201 Createdや3xx Redirect系のレスポンスで、クライアントに遷移先のURLを伝える際に使用されます。

以下は、ResponseEntityでLocationヘッダーを付与する例です。


@PostMapping("/users")
public ResponseEntity<Void> createUser() {
    URI location = URI.create("/users/123");
    return ResponseEntity.created(location).build();
}

created(location)を使うことで、201 CreatedとLocationヘッダーを自動で設定してくれます。

3. Retry-Afterヘッダーの使い方と実装

Retry-Afterヘッダーは、リクエストを受け入れられない状態で、クライアントに「何秒後に再試行してほしいか」を伝えるために使われます。ステータスコード503 Service Unavailableや429 Too Many Requestsとセットで利用されることが多いです。


@GetMapping("/maintenance")
public ResponseEntity<String> maintenance() {
    HttpHeaders headers = new HttpHeaders();
    headers.add("Retry-After", "120"); // 120秒後に再試行
    return ResponseEntity.status(HttpStatus.SERVICE_UNAVAILABLE)
        .headers(headers)
        .body("メンテナンス中です。しばらくしてから再度アクセスしてください。");
}

このようにすることで、アクセス集中時やメンテナンス中の丁寧な対応が可能になります。

Spring FrameworkやThymeleafを使った Webアプリ開発の全体像をやさしく理解したい人には、この入門書が定番です。

Spring Framework超入門をAmazonで見る

※ Amazon広告リンク

4. CORS関連ヘッダー（Access-Control-Allow-*）の設定方法

CORS（クロスオリジンリソースシェアリング）に対応するためには、いくつかのHTTPレスポンスヘッダーを設定する必要があります。代表的なヘッダーは以下の通りです。

Access-Control-Allow-Origin
Access-Control-Allow-Methods
Access-Control-Allow-Headers

Spring Bootでは、次のようにしてこれらを個別に付与することも可能です。


@GetMapping("/cors-data")
public ResponseEntity<String> corsData() {
    HttpHeaders headers = new HttpHeaders();
    headers.add("Access-Control-Allow-Origin", "*");
    headers.add("Access-Control-Allow-Methods", "GET, POST, OPTIONS");
    headers.add("Access-Control-Allow-Headers", "Content-Type, Authorization");

    return ResponseEntity.ok().headers(headers).body("CORS対応のデータ");
}

このように明示的に設定すれば、フロントエンドとの連携時のエラー回避にも役立ちます。

5. グローバルにCORS設定を適用する方法（セキュリティ向け）

個別にCORSヘッダーを付ける方法に加えて、グローバルに全体へ適用する方法もあります。これはWebMvcConfigurerを使って実装します。


@Configuration
public class CorsGlobalConfig implements WebMvcConfigurer {
    @Override
    public void addCorsMappings(CorsRegistry registry) {
        registry.addMapping("/**")
            .allowedOrigins("*")
            .allowedMethods("GET", "POST", "PUT", "DELETE")
            .allowedHeaders("*");
    }
}

この設定により、すべてのAPIエンドポイントでCORSが有効になり、ヘッダーも一括で付与されます。

6. HttpServletResponseを使った手動ヘッダー追加の方法

コントローラー内でHttpServletResponseを直接使えば、細かな制御も可能です。以下はRetry-Afterを手動で設定する例です。


@GetMapping("/retry-manual")
public void retryManual(HttpServletResponse response) throws IOException {
    response.setStatus(HttpServletResponse.SC_SERVICE_UNAVAILABLE);
    response.setHeader("Retry-After", "60");
    response.getWriter().write("手動でヘッダーを追加した例です。");
}

細かくヘッダー制御したい場合や、Springの抽象化を使わずに記述したいときに便利な方法です。

7. セキュリティとパフォーマンスの観点でのヘッダー設計

ヘッダー操作は便利な反面、セキュリティやパフォーマンスにも影響を与えるため注意が必要です。たとえば以下のような配慮が求められます。

Access-Control-Allow-Originに*を指定する場合は、認証が不要なAPIのみに限定する
Locationヘッダーでリダイレクト先を動的に指定する際は、オープンリダイレクトの脆弱性に注意する
Retry-Afterは適切な再試行時間を設定し、ユーザー体験と負荷分散を両立させる

まとめ

Spring BootにおけるHTTPヘッダー操作の全体像

本記事では、Spring Bootを使ったWebアプリケーションやREST API開発において欠かせない、HTTPレスポンスヘッダーの操作方法について体系的に振り返りました。HTTPヘッダーは、クライアントとサーバー間の通信を円滑にし、動作の意図や状態を正確に伝える重要な役割を担っています。特にSpring Bootでは、ResponseEntityやHttpServletResponseといった仕組みを通じて、柔軟かつ安全にヘッダーを制御できる点が大きな特徴です。

Locationヘッダーはリソース作成後やリダイレクト処理において不可欠であり、正しいURL設計と組み合わせることで、APIの使いやすさやRESTらしさを高めることができます。またRetry-Afterヘッダーは、メンテナンス中やアクセス集中時にクライアントへ再試行の目安を伝えるため、ユーザー体験の向上とサーバー負荷の軽減に大きく貢献します。これらのヘッダーを適切に設定することは、単なる技術的な実装を超えて、システム全体の信頼性を高めることにつながります。

CORS設定とフロントエンド連携の重要性

CORSに関するAccess-Control-Allow-OriginやAccess-Control-Allow-Methodsなどのヘッダーは、モダンなWeb開発において避けて通れない要素です。フロントエンドとバックエンドを分離した構成が一般的になった現在、CORS設定の理解不足は、原因不明のエラーや通信失敗を引き起こしやすくなります。Spring Bootでは、個別のエンドポイントでヘッダーを設定する方法と、WebMvcConfigurerを使ってアプリケーション全体に適用する方法があり、用途に応じて使い分けることが重要です。

グローバル設定を行うことで開発効率は向上しますが、その一方でセキュリティ面への配慮も欠かせません。許可するオリジンやHTTPメソッドを必要最小限に絞ることで、不正アクセスのリスクを抑えつつ、安全なAPI設計を実現できます。CORSヘッダーの理解は、Spring Boot開発者にとって基礎でありながら、実務で差が出やすいポイントと言えるでしょう。

ヘッダー設計と実装例の振り返り

記事内で紹介したサンプルプログラムでは、ResponseEntityを使った宣言的なヘッダー設定と、HttpServletResponseによる手動制御の両方を確認しました。ResponseEntityはコードの可読性が高く、HTTPステータスとヘッダーを一貫して扱えるため、一般的なAPI開発に適しています。一方でHttpServletResponseは、より低レベルな制御が可能で、特殊な要件や細かな調整が必要な場面で役立ちます。

どちらの方法を選ぶかは、プロジェクトの規模やチームの方針、求められる柔軟性によって異なります。重要なのは、それぞれの特徴を理解したうえで、適切な手法を選択できる知識を身につけることです。Spring Bootのヘッダー操作を正しく理解することで、APIの品質や保守性は大きく向上します。

サンプルプログラムで再確認


@GetMapping("/summary-sample")
public ResponseEntity<String> summarySample() {
    HttpHeaders headers = new HttpHeaders();
    headers.add("Retry-After", "30");
    headers.add("Access-Control-Allow-Origin", "*");
    return ResponseEntity.status(HttpStatus.SERVICE_UNAVAILABLE)
        .headers(headers)
        .body("まとめ用のサンプルレスポンスです。");
}

このように、これまで学んだ内容を組み合わせることで、実践的なレスポンス設計が可能になります。ヘッダーは単独で使うものではなく、ステータスコードやレスポンスボディと一体となって初めて意味を持つことを意識すると、より理解が深まります。

先生と生徒の振り返り会話

生徒「今回の記事を通して、Spring Bootでヘッダーを設定する方法がかなり整理できました。LocationやRetry-Afterって、こんなに大事だったんですね。」

先生「そうですね。ヘッダーは目立たない存在ですが、APIの使いやすさや信頼性を左右する重要な要素です。」

生徒「CORS設定も、今までエラーが出たら何となく直していたのですが、仕組みが分かってスッキリしました。」

先生「理解したうえで設定できるようになると、トラブル対応も早くなりますし、セキュリティ意識も自然と高まります。」

生徒「ResponseEntityとHttpServletResponseの使い分けも、これから意識してみます。」

先生「その姿勢が大切です。今回学んだHTTPヘッダー操作は、Spring Boot開発の土台になりますから、ぜひ実務や個人開発でも活かしてください。」