本文へスキップ

本ページはプロモーションが含まれています

Java入門

Spring Bootアノテーション一覧|用途別の早見表と使い分け

CATEGORY
DRAWN BY
TOM
DATE
REV.
READ
約29分
SHEETS
8枚
Spring Bootアノテーション(用途別の早見表と使い分け)

トム

SESで約8年、環境を変えられないもどかしさの中にいました。32歳で自社開発企業に転職し、今はClaude Codeと自動化で、仕事も時間も組み直している途中です。
・Javaバックエンドエンジニア(Java歴12年以上)
・資格:基本情報技術者/応用情報技術者/Java Silver/Python3エンジニア認定基礎
詳細なプロフィール

𝕏

@Service と @Component は何が違うのか。@Autowired は書くべきか、消してよいのか。

Spring Bootのコードを読み始めると、クラスの上に並ぶアノテーションの意味が分からないまま、隣のクラスを真似して付けることになりがちです。

この記事は、よく使うアノテーションを起動・Bean登録・DI・Web・設定値・データ・トランザクション・テストの8つの用途に分けた一覧表から始めます。

続けて、迷いやすい組み合わせ(@Component と @Bean、@Value と @ConfigurationProperties、@SpringBootTest と @WebMvcTest)を、Spring Boot 4.1.2で実行したテストの出力つきで比べます。

この記事でわかること

  • Spring Bootのアノテーションを用途別に引ける一覧表と、パッケージでの見分け方
  • コンストラクタ注入が勧められる理由と、@Autowired を省略できる条件
  • @Component と @Bean、@Configuration の proxyBeanMethods の違い
  • @Transactional が効かない場面と、@SpringBootTest / @WebMvcTest の使い分け

迷ったら次の4つから始めます。
・Bean登録はクラスに @Service などを付ける
・注入はコンストラクタ1つにして @Autowired を書かない
・設定値はまとめて @ConfigurationProperties で受け取る
・Controllerのテストは @WebMvcTest で書く

PARTS LIST /目次

Spring Bootのアノテーション一覧|用途別の早見表

Spring Bootのアノテーションとは、クラスやメソッドに付けて「この部品をどう扱うか」をSpringに伝える目印です。

Spring Bootは起動時にクラスをスキャンし、付いているアノテーションを読んで、部品(Bean)を作り、つなぎ、URLに割り当てます。

数は多いのですが、普段のアプリで使うものは8つの用途でほぼ足ります。まず全体を表で押さえ、細かい違いは後半の節で手元のテストを動かしながら確かめます。

8つの用途で引ける早見表

表の「付ける場所」は、どこに書くアノテーションかを示します。クラスに付けるものとメソッドに付けるものを取り違えるとコンパイルは通っても動かないことがあるので、ここだけは先に見ておくと迷いが減ります。

用途アノテーション付ける場所役割
起動@SpringBootApplicationメインクラス自動設定・コンポーネントスキャン・設定クラスの3つをまとめて有効にする
起動@ConfigurationPropertiesScanメインクラス@ConfigurationProperties のクラスを探して登録する
Bean登録@Componentクラス汎用の部品としてBeanに登録する
Bean登録@Serviceクラス業務ロジックの層。登録のされ方は @Component と同じ
Bean登録@Repositoryクラスデータアクセスの層。例外を DataAccessException に変換する対象になる
Bean登録@Configurationクラス@Bean メソッドを持つ設定クラス
Bean登録@Beanメソッド戻り値をBeanに登録する。自分でソースを直せないクラスにも使える
DI@Autowiredコンストラクタ・フィールド・セッター注入先を示す。コンストラクタが1つなら省略できる
DI@Qualifier引数・フィールド同じ型のBeanが複数あるとき、名前で選ぶ
DI@Primaryクラス・@Bean メソッド同じ型が複数あるときの既定を決める
Web@RestControllerクラス@Controller + @ResponseBody。戻り値をJSONなどで返す
Web@Controllerクラス戻り値をビュー名(画面テンプレートの名前)として扱う
Web@RequestMapping / @GetMapping / @PostMappingクラス・メソッドURLとHTTPメソッドを割り当てる
Web@PathVariable / @RequestParam / @RequestBody引数パス・クエリ文字列・リクエスト本文から値を受け取る
Web@ResponseStatusメソッド・例外クラス返すステータスコードを決める
Web@RestControllerAdvice / @ExceptionHandlerクラス / メソッド例外をまとめてレスポンスに変える
設定値@Value引数・フィールド設定値を1つずつ受け取る
設定値@ConfigurationPropertiesクラス・record同じ接頭辞の設定をまとめて受け取る
データ@Entity / @Id / @GeneratedValueクラス / フィールドJPAのエンティティと主キー(Jakarta Persistenceのもの)
トランザクション@Transactionalクラス・メソッドメソッドを1つのトランザクションで包む
テスト@SpringBootTestテストクラスアプリ全体のコンテキストを読み込む
テスト@WebMvcTestテストクラスSpring MVCの部品だけを読み込む
テスト@DataJpaTestテストクラスJPAの部品だけを読み込み、各テストの終わりにロールバックする
テスト@MockitoBeanテストのフィールドコンテキストのBeanをMockitoのモックに置き換える

Spring Bootでよく使うアノテーション(Spring Boot 4.1.2で確認)

@Override や @Deprecated のようなJava標準のアノテーション、自作アノテーションの作り方は、Javaアノテーションの基本の記事にまとめています。

この記事はSpringが読むアノテーションだけを扱います。

Springのものかどうかはパッケージで見分ける

クラスの上に並んでいるアノテーションが全部Springのものとは限りません。

import 文のパッケージを見ると提供元が分かり、調べるときにどのドキュメントを開けばよいかも決まります。

アノテーションパッケージ提供元
@SpringBootApplicationorg.springframework.boot.autoconfigureSpring Boot
@ConfigurationPropertiesorg.springframework.boot.context.propertiesSpring Boot
@Component / @Service / @Repository / @Controllerorg.springframework.stereotypeSpring Framework
@Configuration / @Bean / @Primaryorg.springframework.context.annotationSpring Framework
@Autowired / @Qualifier / @Valueorg.springframework.beans.factory.annotationSpring Framework
@RestController / @GetMapping などorg.springframework.web.bind.annotationSpring Framework
@Transactionalorg.springframework.transaction.annotationSpring Framework
@Entity / @Idjakarta.persistenceJakarta Persistence
@SpringBootTestorg.springframework.boot.test.contextSpring Boot
@WebMvcTestorg.springframework.boot.webmvc.test.autoconfigureSpring Boot(4.0から)
@DataJpaTestorg.springframework.boot.data.jpa.test.autoconfigureSpring Boot(4.0から)
@MockitoBeanorg.springframework.test.context.bean.override.mockitoSpring Framework
@Data / @RequiredArgsConstructorlombokLombok

主なアノテーションのパッケージ

Spring Boot 4ではテスト用のアノテーションの置き場所が変わりました。Spring Boot 3系の記事のコードを貼ると、@WebMvcTest の import で止まるのはこのためです。

@Transactional には jakarta.transaction.Transactional という同じ名前の別物もあり、こちらには readOnly などの属性がありません。

補完で選ぶときは org.springframework.transaction.annotation のほうかを見ます。Lombokの @Data などはLombokの記事を参照してください。

起動とBean登録のアノテーション

Beanとは、Springが作って管理する部品(オブジェクト)のことです。

Springにオブジェクトを作らせるには、クラスに @Component 系の目印を付けてスキャンで見つけてもらうか、@Bean メソッドで自分で作って渡すかの2通りがあります。

どちらでも結果は「コンテナにBeanが1つ増える」なのですが、向いている場面が違います。

@SpringBootApplicationは3つのアノテーションの合体

メインクラスに付ける @SpringBootApplication は、次の3つをまとめたものです。

  • @EnableAutoConfiguration:依存に入っているライブラリを見て、DataSourceやMVCの設定を自動で組む
  • @ComponentScan:メインクラスのパッケージから下を探し、@Component 系のクラスをBeanにする
  • @SpringBootConfiguration:このクラス自体を設定クラスにする(テストが設定を探すときの目印にもなる)

スキャンの起点はメインクラスのパッケージです。com.example.demo にメインクラスを置いたら、com.example.demo.item や com.example.demo.web は見つかります。

一方、com.other のような外のパッケージは見つかりません。

この記事の検証用プロジェクトでは、メインクラスに @ConfigurationPropertiesScan も付けました。

@SpringBootApplication
@ConfigurationPropertiesScan
public class DemoApplication {

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

}

@Component・@Service・@Repository・@Controllerの違い

4つとも「スキャンで見つけてBeanにする」働きは同じです。@Service も @Repository も @Controller も、中に @Component が付いた特化版にあたります。

違いは、層の意味を読む人とSpringに伝えるかどうかです。

アノテーション付けるクラスSpringが追加でしてくれること
@Componentどの層にも当てはまらない部品なし
@Service業務ロジックなし(層を示す目印)
@Repositoryデータアクセス例外の変換の対象になる(PersistenceExceptionTranslationPostProcessor と組み合わせたとき)
@ControllerWebの受付@RequestMapping のメソッドがURLに割り当てられる

Bean登録の4つのアノテーション

Spring Data JPAの JpaRepository を継承したインターフェースには、@Repository を付けなくても動きます。

検証用プロジェクトの ItemRepository も何も付けていませんが、起動ログに Found 1 JPA repository interface. と出て、Beanとして注入できました。

public interface ItemRepository extends JpaRepository<Item, Long> {
}

@Componentと@Beanの違いは「誰がnewするか」

@Component はクラスに付けて、Springに new を任せます。@Bean はメソッドに付けて、自分で new した戻り値をSpringに渡します。

そのため、ソースに手を入れられないクラスは @Bean で登録するしかありません。java.time.Clock やHTTPクライアントのようなライブラリのクラスが典型です。

@Configuration(proxyBeanMethods = false)
public class AppConfig {

	@Bean
	Clock clock() {
		return Clock.system(ZoneId.of("Asia/Tokyo"));
	}

}

@Component(クラスに付ける)

自分で書いたクラス向け。Springが new して、コンストラクタの引数も注入する。ServiceやControllerはこちら。

@Bean(メソッドに付ける)

ソースを直せないクラスや、作り方を条件で変えたいとき向け。メソッドの中で自分で new して返す。

自分で書いた ItemService を @Bean で登録することもできますが、クラスに @Service を付けたほうが、どこでBeanになっているかを追いやすくなります。

@ConfigurationのproxyBeanMethodsで何が変わるか

@Configuration には proxyBeanMethods という属性があり、既定は true です。

true のとき、Springは設定クラスのサブクラス(CGLIBのプロキシ)を作ります。このサブクラスのおかげで、クラスの中で @Bean メソッドを直接呼んでも、コンテナにある同じBeanが返ってきます。

false にするとプロキシを作らず、@Bean メソッドはただのメソッドとして呼ばれます。この動き方は「lite」モードと呼ばれます。

違いを確かめるため、Engine と Car の2つのBeanを、3通りの設定クラスで登録しました。

@Configuration
static class FullConfig {

	@Bean
	Engine engine() {
		return new Engine();
	}

	@Bean
	Car car() {
		return new Car(engine()); // 同じクラスの @Bean メソッドを直接呼ぶ
	}

}

@Configuration(proxyBeanMethods = false)
static class LiteConfig {
	// FullConfig と同じ中身
}

@Configuration(proxyBeanMethods = false)
static class LiteConfigWithParam {

	@Bean
	Engine engine() {
		return new Engine();
	}

	@Bean
	Car car(Engine engine) { // 引数で受け取る
		return new Car(engine);
	}

}

テストで、Car が持っている Engine とコンテナの Engine が同じオブジェクトかを出力しました。

FullConfig の実体: ProxyBeanMethodsTest$FullConfig$$SpringCGLIB$$0 / CarのEngineはBeanと同じ?: true
LiteConfig の実体: LiteConfig / CarのEngineはBeanと同じ?: false
LiteConfigWithParam の実体: LiteConfigWithParam / CarのEngineはBeanと同じ?: true

LiteConfig では engine() が普通に呼ばれて、Engine が2つできています。シングルトンのつもりが、知らないうちに2つになるわけです。

ハマりポイント
proxyBeanMethods = false で @Bean メソッドを直接呼ばない

false にしてもエラーは出ません。Beanが2つできるだけなので、気づくのは「設定したはずの値が反映されていない」「接続プールが2つある」といった症状が出てからです。false にするなら、ほかのBeanはメソッドの引数で受け取る形(LiteConfigWithParam)に揃えます。

Spring Boot自身の自動設定クラスは proxyBeanMethods = false で書かれています。プロキシを作らない分、起動の手間が少なく、設定クラスを final にもできます。

自分の設定クラスでも、引数で受け取る書き方に揃えるなら false で困ることはありません。

DI(依存性の注入)のアノテーション

DIとは、クラスが使う部品を自分で new せず、外から渡してもらう設計です。Spring Bootではコンテナが部品を渡す役を担い、渡し方はコンストラクタ・セッター・フィールドの3通りがあります。

DIそのものの考え方とBefore/AfterのコードはDI(依存性の注入)の記事に書いたので、ここではアノテーションの付け方に絞ります。

LOGSES時代 → 現職StrutsからSpring Bootへ。いまはService層を毎日触っている

Java歴は12年で、SES時代はStrutsを8年以上使っていました。Spring Bootを使うようになったのは現職に移ってからで、直近4年ほどです。いまは普段のSpring Boot開発でGradleを毎日回しています。Service層に var を入れたときは、1メソッドあたり平均2〜3行のコードが減りました(varの記事に書いた話です)。

コンストラクタ注入が勧められる理由

Springチームは、注入の方法としてコンストラクタ注入を勧めています。理由は次の3つです。

  • フィールドを final にでき、あとから差し替えられない部品(不変)にできる
  • 必須の部品が null のまま使われることがない
  • 呼び出し側には、必ず初期化が終わった状態で渡される

あわせて、コンストラクタの引数が多すぎるのはクラスの責任が多すぎる兆候だ、とも述べています。

フィールド注入だと、依存は @Autowired の行が1行ずつ増えるだけで、コンストラクタの引数のように「長すぎる」と目に入ってきません。

@Service
public class ItemService {

	private final ItemRepository repository;

	// コンストラクタが1つだけなので @Autowired は書かない
	public ItemService(ItemRepository repository) {
		this.repository = repository;
	}

}

テストのしやすさにも効きます。コンストラクタで受け取るクラスは、Springを起動しなくても new ItemService(モック) で単体テストが書けます。

モックの作り方はMockitoの使い方を参照してください。

@Autowiredを省略できる条件

Beanのクラスにコンストラクタが1つしかないなら、@Autowired は付けなくても、そのコンストラクタが使われます。

コンストラクタが2つ以上あって、引数なしのコンストラクタもない場合は、どれを使うかを @Autowired で1つ指定します。

指定しないとどうなるかを、コンストラクタを2つ持つクラスで試しました。

static class TwoConstructorService {

	TwoConstructorService(Clock2 clock) {
	}

	TwoConstructorService(Clock2 clock, Engine engine) {
	}

}

起動するとBeanを作る段階で失敗し、原因の一番奥には引数なしコンストラクタが見つからないという例外がありました。

Error creating bean with name 'proxyBeanMethodsTest.TwoConstructorService': Failed to instantiate [com.other.proxydemo.ProxyBeanMethodsTest$TwoConstructorService]: No default constructor found
NoSuchMethodException: com.other.proxydemo.ProxyBeanMethodsTest$TwoConstructorService.<init>()

コンストラクタが複数あると、Springはまず引数なしのコンストラクタを探します。無ければ「No default constructor found」で止まるので、使いたいほうに @Autowired を付けます。

Lombokを使う場合
@RequiredArgsConstructor は final フィールドを引数にしたコンストラクタを1つだけ作るので、やはり @Autowired は要りません。コードに見えないコンストラクタになる点だけ、チームで合意しておくと読み違いが減ります。

同じ型のBeanが2つあるときは@Primaryか@Qualifier

インターフェース Notifier の実装を2つ(mailとslack)Beanにして、何も指定せずに注入すると起動に失敗します。

[ヒントなし] NoUniqueBeanDefinitionException: No qualifying bean of type 'com.other.proxydemo.QualifierTest$Notifier' available: expected single matching bean but found 2: mail,slack

ふだん使うほうに @Primary を付け、別のほうが欲しい場所だけ @Qualifier で名前を指定します。

@Bean
@Primary
Notifier mail() {
	return () -> "mail";
}

@Bean
Notifier slack() {
	return () -> "slack";
}

@Bean
Sender sender(Notifier notifier) {
	return new Sender(notifier);
}

@Bean
Sender slackSender(@Qualifier("slack") Notifier notifier) {
	return new Sender(notifier);
}
[@Primary] sender → mail
[@Qualifier("slack")] slackSender → slack

@Primary は「迷ったらこれ」、@Qualifier は「ここだけはこれ」と覚えると使い分けで迷いません。

Webのアノテーション

Webのアノテーションは、HTTPリクエストをどのメソッドで受けて、何を返すかを決めます。

検証用プロジェクトには、商品を返すAPI(@RestController)と、ビュー名を返す画面用のクラス(@Controller)を両方置き、@WebMvcTest で呼び出しました。

サーバーは起動せず、MockMvcという疑似のリクエストで動かしています。

@RestControllerと@Controllerの違い

@RestController は @Controller と @ResponseBody を合わせたアノテーションです。

@Controller のメソッドが返す文字列はビュー名として扱われ、Thymeleafなどのテンプレートが画面を作ります。@ResponseBody が付くと、戻り値はそのままレスポンスの本文として返ります。

@Controller
public class PageController {

	// 戻り値はビュー名として扱われる
	@GetMapping("/page")
	public String page() {
		return "hello";
	}

	// @ResponseBody を付けると、戻り値がそのままレスポンス本文になる
	@GetMapping("/hello-text")
	@ResponseBody
	public String helloText() {
		return "hello";
	}

}
[@Controller] ビュー名: hello / 本文: ''
[@Controller + @ResponseBody] ModelAndView: null / 本文: 'hello'

同じ "hello" を返していても、前者は画面の名前、後者は本文です。

API用のクラスなら @RestController にしておけば、メソッドごとに @ResponseBody を付ける必要がありません。

ハマりポイント
@Controller で「Circular view path」が出たら、@RestController の付け忘れを疑う

テンプレートエンジンを入れずに、@Controller の /hello から "hello" を返してみました。ビューを探して同じURLへ戻ろうとし、次の例外になります。
Circular view path [hello]: would dispatch back to the current handler URL [/hello] again. Check your ViewResolver setup!
JSONや文字列を返したいなら @RestController(か @ResponseBody)にします。画面を返したいなら、Thymeleafの依存とテンプレートを足します。

リクエストの値を受け取るアノテーション

URLの一部、クエリ文字列、リクエスト本文のどこから値を取るかで、引数に付けるアノテーションが変わります。

アノテーション値の出どころ例
@PathVariableURLのパスの一部/items/1 の 1
@RequestParamクエリ文字列・フォーム/items?keyword=ペン の ペン
@RequestBodyリクエスト本文(JSON){"name":"ノコギリ","price":2200}
@RequestHeaderHTTPヘッダーAuthorization の値

引数に付けるアノテーション

検証用の ItemController では、取得に @PathVariable、登録に @RequestBody を使いました。登録は @ResponseStatus(HttpStatus.CREATED) で201を返します。

@RestController
@RequestMapping("/items")
public class ItemController {

	private final ItemService service;

	public ItemController(ItemService service) {
		this.service = service;
	}

	@GetMapping("/{id}")
	public Item get(@PathVariable long id) {
		return service.find(id).orElseThrow(() -> new ItemNotFoundException(id));
	}

	@PostMapping
	@ResponseStatus(HttpStatus.CREATED)
	public Item create(@RequestBody ItemRequest request) {
		return service.register(request.name(), request.price());
	}

	public record ItemRequest(String name, int price) {
	}

}

GET /items/1 をMockMvcで送ったときの出力(抜粋)です。

MockHttpServletResponse:
           Status = 200
          Headers = [Content-Type:"application/json"]
             Body = {"name":"ハンマー","price":1500,"id":null}

@RestControllerAdviceで例外をまとめて返す

Controllerごとに try-catch を書く代わりに、@RestControllerAdvice のクラスに @ExceptionHandler を集めると、例外をレスポンスに変える処理を1か所にできます。

@RestControllerAdvice
public class ApiExceptionHandler {

	@ExceptionHandler(ItemNotFoundException.class)
	@ResponseStatus(HttpStatus.NOT_FOUND)
	public Map<String, String> notFound(ItemNotFoundException e) {
		return Map.of("message", e.getMessage());
	}

}

テストでは GET /items/99 に対して404と {"message":"商品が見つかりません: id=99"} が返ることを確かめました。

@WebMvcTest は @ControllerAdvice 系のクラスも読み込むので、Controllerのテストと一緒にエラーの形も確かめられます。

設定値のアノテーション(@Valueと@ConfigurationProperties)

application.yaml や application.properties に書いた値をJavaで受け取るアノテーションは、@Value と @ConfigurationProperties の2つです。

1つだけ取るなら @Value、関連する値をまとめて扱うなら @ConfigurationProperties と分けると選びやすくなります。

検証用には次の設定を用意しました。

shop:
  name: トムの道具屋
  tax-rate: 0.10
  free-shipping-over: 5000

@Valueは1つの値とデフォルト値に向く

@Value("${キー}") で設定値を1つ受け取ります。${キー:既定値} と書けば、設定がないときの値も決められます。

ここでもフィールドではなくコンストラクタの引数に付けました。

@Component
public class GreetingService {

	private final String shopName;

	private final int retry;

	public GreetingService(@Value("${shop.name}") String shopName,
			@Value("${shop.retry:3}") int retry) {
		this.shopName = shopName;
		this.retry = retry;
	}

	public String greet() {
		return "いらっしゃいませ、" + shopName + "へ(retry=" + retry + ")";
	}

}
[@Value] いらっしゃいませ、トムの道具屋へ(retry=3)

shop.retry は設定に書いていないので、既定値の3が入りました。

@Value は #{...} の形でSpEL(式)も書けますが、キーの名前を間違えると起動時に失敗するまで気づけません。

@ConfigurationPropertiesでまとめて受け取る

@ConfigurationProperties("shop") を付けたクラスやrecordは、shop. で始まる設定をまとめて受け取ります。

Spring Bootも、自分の部品の設定キーを定義するなら @ConfigurationProperties のクラスにまとめるよう勧めています。型のついた1つのオブジェクトとして注入できるからです。

@ConfigurationProperties("shop")
public record ShopProperties(String name, BigDecimal taxRate, int freeShippingOver,
		@DefaultValue("JPY") String currency) {
}
[@ConfigurationProperties] ShopProperties[name=トムの道具屋, taxRate=0.1, freeShippingOver=5000, currency=JPY]

設定ファイルの tax-rate がJavaの taxRate に、free-shipping-over が freeShippingOver に入っています。この「書き方の違いを吸収する」働きを緩いバインド(relaxed binding)と呼びます。

recordはコンストラクタが1つなので、そのまま値が入ります。登録はメインクラスの @ConfigurationPropertiesScan に任せました。

recordの書き方はJavaのrecordの記事にまとめています。

ハマりポイント
application.properties に日本語を書くと文字化けする

検証の途中まで、同じ値を application.properties に書いていました。すると出力は name=ãã ã®éå·å± になりました。Spring Bootは properties ファイルを既定で ISO-8859-1 として読みます。日本語の値は application.yaml(UTF-8で読まれる)に移すか、properties なら \u30c8 のようなUnicodeエスケープで書きます。

@Valueと@ConfigurationPropertiesのどちらを選ぶか

2つの違いを、選ぶときの目線で表にすると次のようになります。

比べる点@ConfigurationProperties@Value
緩いバインド(tax-rate → taxRate)○ できる△ 限定的
IDEの補完用メタデータ○ 作れる× なし
SpEL(#{...})の式× 使えない○ 使える
向いている場面関連する設定が3つ以上ある1〜2個の値、既定値つきの値

@ConfigurationPropertiesと@Valueの比較

@Value を使うときも、キー名はケバブケース(小文字とハイフン)で書くよう勧められています。

@Value("${shop.taxRate}") ではなく @Value("${shop.tax-rate}") と書いておけば、@ConfigurationProperties と同じルールで値が探されます。

データとトランザクションのアノテーション

データの層では、テーブルとクラスを対応させるJPAのアノテーションと、処理のまとまりを決める @Transactional を使います。

前者はSpringではなくJakarta Persistenceのもので、Spring Data JPAが読み取って動きます。後者はSpringのAOP(プロキシ)で動くため、付け方を間違えると効かないまま動いてしまいます。

@Entity・@Idとリポジトリ

@Entity を付けたクラスがテーブルの1行に対応し、@Id が主キー、@GeneratedValue が採番を表します。

JPAはエンティティを内部で new するため、引数なしのコンストラクタ(protected でよい)が必要です。

@Entity
public class Item {

	@Id
	@GeneratedValue
	private Long id;

	private String name;

	private int price;

	protected Item() {
	}

	public Item(String name, int price) {
		this.name = name;
		this.price = price;
	}

	// getter は省略
}

@Column や @OneToMany などのJPAのアノテーション、リポジトリのメソッド名からクエリを作る仕組みは、Spring Data JPA入門で扱っています。

@Transactionalの基本とロールバックの条件

@Transactional を付けたメソッドでは、呼ばれた時点でトランザクションが始まります。正常に終わればコミット、例外で抜ければロールバックです。

ただし、既定でロールバックされるのは RuntimeException と Error だけです。検査例外(Exception を直接継承した例外)ではコミットされます。

@Transactional
public void registerTwoAndFail() {
	repository.save(new Item("ドライバー", 800));
	throw new IllegalStateException("2件目の登録で失敗");
}

@Transactional
public void registerAndThrowChecked() throws Exception {
	repository.save(new Item("ペンチ", 1200));
	throw new Exception("検査例外");
}

@SpringBootTest で両方を呼び、例外のあとにテーブルの件数を数えました。

[実行時例外] 例外のあとの件数: 0
[検査例外] 例外のあとの件数: 1

検査例外でも戻したいなら @Transactional(rollbackFor = Exception.class) を指定します。

Spring Framework 6.2からは @EnableTransactionManagement(rollbackOn = ALL_EXCEPTIONS) でアプリ全体の既定も変えられます。commitとrollbackの仕組みそのものはJavaトランザクションの記事を参照してください。

@Transactionalが効かない4つの場面

@Transactional は、Beanの前に立つプロキシがメソッド呼び出しを横取りして、トランザクションを始めます。

プロキシを通らない呼び方をすると、アノテーションが付いていても何も起きません。一般によく言われる効かない場面は次の4つです。

  • 同じクラスの中から呼ぶ(自己呼び出し)
  • private メソッドに付ける(クラスベースのプロキシなら protected とパッケージプライベートは6.0から対象)
  • 例外を try-catch で握りつぶす(ロールバックの合図が届かない)
  • new で作ったオブジェクトのメソッドを呼ぶ(Beanではないのでプロキシがない)

1つめの自己呼び出しを、@Transactional の付いていないメソッドから同じクラスの inner() を呼ぶ形で試しました。inner() の中で、トランザクションが動いているかを返しています。

public boolean callInnerFromSameClass() {
	return inner();
}

@Transactional
public boolean inner() {
	return TransactionSynchronizationManager.isActualTransactionActive();
}
[外から inner() を呼ぶ] トランザクション中: true
[同じクラスの中から inner() を呼ぶ] トランザクション中: false

外から呼ぶとプロキシを通るので true、クラスの中の this.inner() はプロキシを通らないので false でした。

テストで注入された ItemService のクラス名は ItemService$$SpringCGLIB$$0 で、Springが作ったサブクラスに置き換わっていることも分かります。

呼び出しの流れを図にすると次のとおりです。

flowchart TD
    A["Controller など外のBean"] -->|"service.inner()"| P["ItemServiceの<br>プロキシ"]
    P -->|"トランザクション開始"| T["本物の ItemService.inner()"]
    A -->|"service.callInnerFromSameClass()"| P2["プロキシ<br>(このメソッドは素通り)"]
    P2 --> C["本物の callInnerFromSameClass()"]
    C -->|"this.inner()<br>プロキシを通らない"| T2["inner() がトランザクションなしで動く"]

対策は、トランザクションを始めたいメソッドを別のBeanに分けて、外から呼ばれる形にすることです。

プロキシの仕組みはJava AOPの記事が詳しいです。

テストのアノテーション(@SpringBootTestと@WebMvcTest)

Spring Bootのテストのアノテーションは、どこまでの部品を読み込むかで選びます。

全部を読み込む @SpringBootTest と、一部だけを読み込むテストスライス(@WebMvcTest・@DataJpaTest など)があり、後者は関係のない部品を作らないぶん起動が軽くなります。

JUnit 5そのものの書き方はJUnit5の使い方入門にまとめています。

@SpringBootTestはアプリ全体を読み込む

@SpringBootTest は、メインクラスの @SpringBootApplication を見つけて、本番と同じようにすべてのBeanを作ります。

既定の webEnvironment は MOCK で、組み込みのサーバーは起動しません。実際のポートで受けたいときだけ RANDOM_PORT などを指定します。

@SpringBootTest
class DemoApplicationTests {

	@Autowired
	ApplicationContext context;

	@Autowired
	ItemService itemService;

	@Test
	void beans() {
		System.out.println("[SpringBootTest] Bean定義の数: " + context.getBeanDefinitionCount());
		System.out.println("[SpringBootTest] ItemServiceのクラス: " + itemService.getClass().getName());
	}

}
Started DemoApplicationTests in 1.014 seconds (process running for 2.38)
[SpringBootTest] Bean定義の数: 227
[SpringBootTest] ItemServiceのクラス: com.example.demo.item.ItemService$$SpringCGLIB$$0

テストクラスはJUnitが作るので、ここではフィールドの @Autowired で受け取りました。テストクラスでもコンストラクタに @Autowired を付ければ、コンストラクタで受け取れます。

前の節のロールバックや自己呼び出しの確認も、このテストクラスで行いました。

@WebMvcTestはMVCの部品だけを読み込む

@WebMvcTest が読み込むのは、@Controller・@ControllerAdvice・Converter・Filter・WebMvcConfigurer・HandlerMethodArgumentResolver などのMVCの部品だけです。

普通の @Component や @Service、@ConfigurationProperties のBeanはスキャンされません。そのため、Controllerが使うServiceはモックで用意します。

@WebMvcTest(ItemController.class)
class ItemControllerTest {

	@Autowired
	MockMvc mvc;

	@MockitoBean
	ItemService service;

	@Test
	void getItem() throws Exception {
		given(service.find(1L)).willReturn(Optional.of(new Item("ハンマー", 1500)));
		mvc.perform(get("/items/1"))
			.andExpect(status().isOk())
			.andExpect(jsonPath("$.name").value("ハンマー"))
			.andDo(print());
	}

}

同じプロジェクトで、@SpringBootTest と並べた結果です。

Started ItemControllerTest in 0.128 seconds (process running for 2.763)
[WebMvcTest] Bean定義の数: 125
[WebMvcTest] ItemServiceのクラス: com.example.demo.item.ItemService
[WebMvcTest] ItemRepositoryのBeanはある?: false
比べる点@SpringBootTest@WebMvcTest(ItemController.class)
Bean定義の数227125
コンテキストの起動(ログの Started)1.014秒0.128秒
DB(JPA・HikariCP)起動する起動しない
ItemService本物(プロキシ)モック
向いているテスト層をまたぐ確認・トランザクションURL・JSON・ステータスコード・例外ハンドラ

@SpringBootTestと@WebMvcTestの比較(Spring Boot 4.1.2・Java 23.0.1・Gradle 9.9.1、1回の実行)

秒数は同じJVMで続けて動いた1回分の値なので、目安として見てください。差の大部分は、@WebMvcTest ではDBの接続とJPAの初期化が丸ごとないことから来ています。

全体の設定を読み込みつつMockMvcも使いたいときは、@SpringBootTest に @AutoConfigureMockMvc を足します。

@DataJpaTestはリポジトリとエンティティだけを読み込む

データの層だけを確かめたいときは @DataJpaTest を使います。スキャンの対象はJPAのリポジトリと @Entity に絞られ、Serviceは読み込まれません。

各テストはトランザクションの中で動き、終わるとロールバックされます。DataSourceも組み込みのインメモリDBに置き換わるので、本番のDBの設定があっても書き換わる心配がありません。

@DataJpaTest
@TestMethodOrder(MethodOrderer.MethodName.class)
class ItemRepositoryTest {

	@Autowired
	ItemRepository repository;

	@Test
	void test1Save() {
		repository.save(new Item("やすり", 600));
		System.out.println("[DataJpaTest] 保存後の件数: " + repository.count());
	}

	@Test
	void test2CountInNextTest() {
		System.out.println("[DataJpaTest] 別のテストでの件数: " + repository.count());
	}

}
Started ItemRepositoryTest in 0.115 seconds (process running for 3.003)
[DataJpaTest] Bean定義の数: 80
[DataJpaTest] ItemServiceのBeanはある?: false
[DataJpaTest] テスト中のトランザクション: true
Hibernate: insert into item (name,price,id) values (?,?,?)
[DataJpaTest] 保存後の件数: 1
[DataJpaTest] 別のテストでの件数: 0

1つめのテストで保存した1件は、2つめのテストでは消えています。テストの後片付けに deleteAll() を書かなくてよいのが @DataJpaTest の助かるところです。

実行したSQLが Hibernate: insert ... の形でログに出るのも既定の動きで、showSql 属性で止められます。

一方の @SpringBootTest はテストを自動でロールバックしないため、検証用の DemoApplicationTests では @BeforeEach で repository.deleteAll() を呼んでいます。

テストクラスに @Transactional を付ければ、@SpringBootTest でも各テストの終わりにロールバックされます。

@MockitoBeanで差し替える(Spring Boot 4で@MockBeanは削除)

@MockitoBean は、テストのコンテキストにあるBeanをMockitoのモックに置き換えます。

Spring Boot 3.4で非推奨になった @MockBean と @SpyBean は、Spring Boot 4.0で削除されました。置き換え先はSpring Framework側の @MockitoBean と @MockitoSpyBean です。

Spring Boot 3系の書き方

import org.springframework.boot.test.mock.mockito.MockBean;
import org.springframework.boot.test.autoconfigure.web.servlet.WebMvcTest;
@MockBean ItemService service;

Spring Boot 4系の書き方

import org.springframework.test.context.bean.override.mockito.MockitoBean;
import org.springframework.boot.webmvc.test.autoconfigure.WebMvcTest;
@MockitoBean ItemService service;

@MockitoBean はテストクラスのフィールドに書くもので、@Configuration クラスの中には書けません。

Spring Boot 4では、@WebMvcTest を使うのにテスト用の依存として spring-boot-starter-webmvc-test が要ります(@DataJpaTest なら spring-boot-starter-data-jpa-test)。検証用プロジェクトの依存は次のとおりです。

dependencies {
	implementation 'org.springframework.boot:spring-boot-starter-webmvc'
	implementation 'org.springframework.boot:spring-boot-starter-data-jpa'
	runtimeOnly 'com.h2database:h2'
	testImplementation 'org.springframework.boot:spring-boot-starter-webmvc-test'
	testImplementation 'org.springframework.boot:spring-boot-starter-data-jpa-test'
	testRuntimeOnly 'org.junit.platform:junit-platform-launcher'
}

使っているSpring Bootの版の調べ方はSpring Bootのバージョン確認方法にまとめています。

LOG現職・テストの書き方に迷っていた頃モックを使うほど、テストが実装の写しになっていった

現職のJava開発でテストの書き方に迷っていたとき、特にモックの使い方で悩んで『単体テストの考え方/使い方』を読みました。読んでから職場で変えたのは、単体テストを実装に依存させないことと、意味のないテストは書かないことの2つです。この考え方を @WebMvcTest と @MockitoBean に当てはめると、確かめる相手はServiceのどのメソッドが何回呼ばれたかより、URL・ステータスコード・JSONの形です。外から見える約束だけを確かめるテストは、中の実装を直しても壊れません。

Spring Bootのアノテーションでよくある質問

最後に、Spring Bootのアノテーションで検索されやすい疑問をまとめます。答えは、この記事の検証用プロジェクト(Spring Boot 4.1.2・Java 23.0.1・Gradle 9.9.1)で動かした結果に合わせています。

Q1. Spring Bootでまず覚えるアノテーションはどれですか?

@SpringBootApplication、@RestController と @GetMapping などのマッピング、@Service、@Transactional、@ConfigurationProperties、テストの @SpringBootTest と @WebMvcTest です。

この記事の一覧表の8用途から1つずつ覚えれば、普段のAPI開発のコードはほぼ読めます。

Q2. @Autowiredは付けなくてもいいのですか?

Beanのクラスにコンストラクタが1つだけなら、付けなくてもそのコンストラクタで注入されます。

コンストラクタが2つ以上あり、引数なしのコンストラクタもないときは、使うほうに @Autowired を付けます。付けないと「No default constructor found」で起動に失敗します。

Q3. @Componentと@Serviceで動きは変わりますか?

Beanとして登録される動きは同じです。@Service は中に @Component が付いた特化版で、業務ロジックの層だと示す目印です。

@Repository だけは、例外を DataAccessException に変換する対象になる、という追加の意味があります。

Q4. @Componentと@Beanはどう使い分けますか?

自分で書いたクラスはクラスに @Component 系を付け、ライブラリのクラスのようにソースを直せないものは @Configuration クラスの @Bean メソッドで登録します。

proxyBeanMethods = false の設定クラスでは、ほかのBeanは @Bean メソッドの引数で受け取ります。

Q5. @Transactionalを付けたのにロールバックされないのはなぜですか?

よくある原因は、同じクラスの中から呼んでいる、private メソッドに付けている、例外を try-catch で握りつぶしている、検査例外を投げている、の4つです。

検査例外なら rollbackFor = Exception.class を指定し、自己呼び出しならメソッドを別のBeanに分けます。

Q6. Spring Boot 4で@MockBeanが見つからないのはなぜですか?

@MockBean と @SpyBean はSpring Boot 4.0で削除されました。

org.springframework.test.context.bean.override.mockito パッケージの @MockitoBean と @MockitoSpyBean に置き換えます。@WebMvcTest のパッケージも org.springframework.boot.webmvc.test.autoconfigure に変わっています。

Q7. @SpringBootTestと@WebMvcTestはどちらを使えばいいですか?

Controllerの入出力(URL・ステータスコード・JSON)を確かめるなら @WebMvcTest を使い、Serviceはモックにします。

トランザクションやDBを含めて層をまたいで確かめるなら @SpringBootTest です。手元の検証では、Bean定義の数は227と125でした。

NEXT STEP
手元のControllerを1つ選び、@WebMvcTest のテストを1本書いてみる。

Serviceを @MockitoBean にして、ステータスコードとJSONの1項目だけを確かめれば十分です。Spring Boot自体がまだなら、先にSpring Boot入門で雛形を作ってから戻ってきてください。

途中経過は、また書きます。

NEXT READ本棚から1本

AIで開発を組み直すなら、まずこの5冊から

入門・実践・設計まで、Claude Codeの本をレベル別に5冊選んで比べました。

→ おすすめ5冊を見る

トム

SESで約8年、環境を変えられないもどかしさの中にいました。32歳で自社開発企業に転職し、今はClaude Codeと自動化で、仕事も時間も組み直している途中です。
・Javaバックエンドエンジニア(Java歴12年以上)
・資格:基本情報技術者/応用情報技術者/Java Silver/Python3エンジニア認定基礎
詳細なプロフィール

𝕏

Java入門

TOC