【SpringBoot】レスポンスで返すHTTPステータスコードを設定できる@ResponseStatusアノテーションを解説します

こんにちは。たいら(@tairaengineer2)です。
転職を繰り返し現在4社経験している、11年目エンジニアです。

この記事では、 SpringBootでレスポンスで返すHTTPステータスコードを設定できる@ResponseStatusアノテーションについて

@ResponseStatusアノテーションとは
@ResponseStatusアノテーションを使ったサンプルプログラム

と、丁寧に解説していきます。

前提：実施している環境
@ResponseStatusアノテーションとは
1. @ResponseStatusアノテーションの属性：code属性、value属性
2. @ResponseStatusアノテーションの属性：reason属性
@ResponseStatusアノテーションを解説するプログラムの概要
Javaサンプルプログラム
実行結果
まとめ：@ResponseStatusアノテーションを使ってみよう！

前提：実施している環境

この記事では、以下の環境で行っています。

OS	Windows10
IntelliJ IDEAのエディション	Community(無料版)
IntelliJ IDEAのバージョン	2021.3.2
プロジェクト	Gradle Project
言語	Java　バージョン11
フレームワーク	Spring Boot　バージョン2.6.3

Spring Bootを動かすためにIntelliJ IDEAを使っています。
IntelliJ IDEAのインストールとSpring Bootプロジェクトを新規作成するやり方はこちらの記事をご参考ください。

IntelliJ IDEAのインストール
【IntelliJ IDEA】インストールするやり方を解説します（Windows向け）

Spring Bootプロジェクトを新規作成するやり方
【IntelliJ IDEA】Spring Initializrを使ってSpring Bootプロジェクトを新規作成するやり方を解説します

この記事では

C:\SpringBootSample

配下に「SpringSample」という名前のプロジェクトを作っています。

@ResponseStatusアノテーションとは

@ResponseStatusアノテーションとは、レスポンスで返すHTTPステータスコードを設定できるアノテーションです。

@ResponseStatusアノテーションを使うためには

import org.springframework.web.bind.annotation.ResponseStatus;

1	import org.springframework.web.bind.annotation.ResponseStatus;

をインポートする必要があります。

@ResponseStatusアノテーションの基本の使い方サンプルは以下になります。

@ResponseStatus(code = HttpStatus.BAD_REQUEST)
@GetMapping(value = "/sample")
String sample(){
	return "Hello";
}

@ResponseStatus(code = HttpStatus.BAD_REQUEST)

@GetMapping(value = "/sample")

String sample(){

return "Hello";

}

このサンプルでは、【http://localhost:8080/sample】でGETリクエストを投げた場合、HTTPステータスコードが400で

Hello

Hello

というレスポンスが返されます。

@GetMappingアノテーションは、GETリクエストをマッピングするアノテーションです。
詳しくはこちらの記事をご参考ください。

【SpringBoot】GETリクエストをマッピングする@GetMappingアノテーションを解説します

@ResponseStatusアノテーションで指定できる属性の

code属性、value属性
reason属性

について、それぞれ詳しく解説します。
※code属性、value属性は同じ機能を持っているので一緒に解説します。

@ResponseStatusアノテーションの属性：code属性、value属性

@ResponseStatusアノテーションの属性のcode属性とvalue属性は、常に返すHTTPステータスコードを指定する属性です。
指定できるHTTPステータスコードについては、こちらの記事をご参考ください。

【SpringBoot】HTTPステータスコードのまとめ

どちらを使っても同じ効果を得ることができます。
片方だけを使っても良いですし、両方使っても問題ありません。

@ResponseStatus(code = HttpStatus.OK, value = HttpStatus.OK)
@GetMapping(value = "/test")
String test(){
	return "Hello";
}

@ResponseStatus(code = HttpStatus.OK, value = HttpStatus.OK)

@GetMapping(value = "/test")

String test(){

return "Hello";

}

このサンプルでは、【http://localhost:8080/test】でGETリクエストを投げた場合、HTTPステータスコードが200で

Hello

Hello

というレスポンスが返されます。

code属性、value属性両方を使う場合に注意点があります。
それは、設定する値は必ず同じものを使う必要がある、という点です。

たとえば

@ResponseStatus(code = HttpStatus.ACCEPTED, value = HttpStatus.OK)
@GetMapping(value = "/test")
String test(){
	return "Hello";
}

@ResponseStatus(code = HttpStatus.ACCEPTED, value = HttpStatus.OK)

@GetMapping(value = "/test")

String test(){

return "Hello";

}

だとコンパイルは通るものの実行した場合

org.springframework.core.annotation.AnnotationConfigurationException

1	org.springframework.core.annotation.AnnotationConfigurationException

という例外が発生します。

@ResponseStatusアノテーションの属性：reason属性

@ResponseStatusアノテーションの属性のreason属性は、レスポンスのエラーメッセージを指定する属性です。
デフォルトは空です。

reason属性を使う場合に注意点があります。
それはreason属性を設定していると、HttpServletResponse.sendErrorメソッドが呼ばれて指定した処理が行われない、という点です。

たとえば

@ResponseStatus(code = HttpStatus.BAD_REQUEST, value = HttpStatus.BAD_REQUEST, reason = "sample reason")
@GetMapping(value = "/test")
String test(){
	return "Hello";
}

@ResponseStatus(code = HttpStatus.BAD_REQUEST, value = HttpStatus.BAD_REQUEST, reason = "sample reason")

@GetMapping(value = "/test")

String test(){

return "Hello";

}

に対して【http://localhost:8080/test】でGETリクエストを投げた場合、HTTPステータスコードが400でレスポンスが

{
    "timestamp": "2022-05-23T14:36:10.066+00:00",
    "status": 400,
    "error": "Bad Request",
    "message": "sample reason",
    "path": "/test"
}

{

"timestamp": "2022-05-23T14:36:10.066+00:00",

"status": 400,

"error": "Bad Request",

"message": "sample reason",

"path": "/test"

}

と、メソッド内で指定したレスポンスではなくエラーのレスポンスが返されます。
画面では

と表示されます。

reason属性は使用用途によって向き不向きがあるので、使う場合はご注意ください。
基本使わないでどうしてもという場合使う、というスタンスで問題ありません。

では、次の章で実際に使ってみます。

@ResponseStatusアノテーションを解説するプログラムの概要

@ResponseStatusアノテーションを解説するプログラムでは、

全属性を指定したメソッド
code属性のみを指定したメソッド

と、合計2つ作成します。
それぞれリクエストを投げてレスポンスを確認します。

解説で使うJavaプログラムは、

SpringSample\src\main\java\com\example\SpringSample

配下にある【SpringSampleApplication.java】を使います。

Javaサンプルプログラム

package com.example.SpringSample;

import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;
import org.springframework.http.HttpStatus;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.ResponseStatus;
import org.springframework.web.bind.annotation.RestController;

@SpringBootApplication
@RestController
public class SpringSampleApplication {

	public static void main(String[] args) {
		SpringApplication.run(SpringSampleApplication.class, args);
	}

	@ResponseStatus(code = HttpStatus.BAD_REQUEST, value = HttpStatus.BAD_REQUEST, reason = "sample reason")
	@GetMapping(value = "/test")
	String test(){
		return "Hello";
	}

	@ResponseStatus(code = HttpStatus.OK)
	@GetMapping(value = "/index")
	String index(){
		return "Hello";
	}
}

package com.example.SpringSample;

import org.springframework.boot.SpringApplication;

import org.springframework.boot.autoconfigure.SpringBootApplication;

import org.springframework.http.HttpStatus;

import org.springframework.web.bind.annotation.GetMapping;

import org.springframework.web.bind.annotation.ResponseStatus;

import org.springframework.web.bind.annotation.RestController;

@SpringBootApplication

@RestController

public class SpringSampleApplication {

public static void main(String[] args) {

SpringApplication.run(SpringSampleApplication.class, args);

}

@ResponseStatus(code = HttpStatus.BAD_REQUEST, value = HttpStatus.BAD_REQUEST, reason = "sample reason")

@GetMapping(value = "/test")

String test(){

return "Hello";

}

@ResponseStatus(code = HttpStatus.OK)

@GetMapping(value = "/index")

String index(){

return "Hello";

}

実行結果

プロジェクトを実行するやり方は

プログラムを右クリックして実行
実行タブから実行
ガターから実行

の3種類あるので、いずれかで実行します。
詳しい解説は以下の記事をご参考ください。

【IntelliJ IDEA】SpringBootプロジェクトを実行するやり方を解説します

今回、確認するにあたりPostmanというツールを使います。
Postmanの基本的な使い方については、こちらの記事をご参考ください。

【Postman】基本的な使い方を解説します

まず、「全属性を指定したメソッド」のレスポンスを確認します。
【http://localhost:8080/test】のURL、かつGETでリクエストを投げると、HTTPステータスが400でレスポンスが

{
    "timestamp": "2022-05-23T15:08:53.852+00:00",
    "status": 400,
    "error": "Bad Request",
    "message": "sample reason",
    "path": "/test"
}

{

"timestamp": "2022-05-23T15:08:53.852+00:00",

"status": 400,

"error": "Bad Request",

"message": "sample reason",

"path": "/test"

}

が返されているので、指定した内容のエラーレスポンスが返ってきていることが確認できました。

最後に、「code属性のみを指定したメソッド」のレスポンスを確認します。
【http://localhost:8080/test】のURL、かつGETでリクエストを投げると、HTTPステータスが200でレスポンスが

Hello

Hello

が返されているので、指定した内容でレスポンスが返ってきていることが確認できました。

まとめ：@ResponseStatusアノテーションを使ってみよう！

以上がSpringBootでレスポンスのHTTPステータスコードを指定できる@ResponseStatusアノテーションについての解説でした！

あなたのご参考になったのなら、とても嬉しいです(*´▽｀*)
ではでは～(・ω・)ﾉｼ