AIによる要約
@Primaryは同じ型のBeanが複数ある時の標準候補を決め、@Qualifierは注入先ごとに候補を明示します。アプリ全体で通常使う実装が1つなら@Primary、業務ごとに実装を選び分けるなら@Qualifierが基本です。エラーを消すためだけでなく、どの実装を使う設計なのかをコードで説明できることが重要です。


Spring Bootでは、ControllerやServiceが必要とするオブジェクトをDIコンテナから注入できます。実装が1つなら型だけで候補を決められますが、同じインターフェースを実装するBeanが複数あると、Springはどれを注入すべきか判断できません。
決済方法、通知方法、外部APIの本番用・スタブ用など、SIerの業務システムでも複数実装はよくあります。この記事では、@Primaryと@Qualifierを付ける基準を、現場のレビューで説明できる形に整理します。
この記事のポイント
@Primaryは型注入で優先する標準Beanを決める@Qualifierは注入先で使うBeanを明示する- 複数のBeanをすべて使うなら
List<型>で受け取る - Bean名への暗黙依存ではなく、選定理由が読めるコードにする
実行用サンプル
候補が2件で起動に失敗する場合、Primaryでメールを選ぶ場合、Qualifierでチャットを選ぶ場合、Listで両方を受け取る場合を、同じ通知の例で比べます。ZIPにはソース全文・4件のJUnitテスト・pom.xml・READMEを収録しています。JDK 17とMaven 3.9系で mvn test を実行します。Spring Framework 6.2.19で注入を検証し、実際のメールやチャットは送信しません。
Beanが複数あると何が起きるか
通知を送る NotificationSender に、メールとチャットの2実装を登録します。サンプルでは送信先を区別するため、メールは MAIL:、チャットは CHAT: を付けた文字列を返します。
NotificationSender.java の全文
package info.syachiku.notification;
@FunctionalInterface
public interface NotificationSender {
String send(String message);
}SenderConfigurations.java から、既定の候補を決めていない WithoutDefault の抜粋
@Configuration(proxyBeanMethods = false)
public static class WithoutDefault {
@Bean
@Qualifier("incident-channel")
@Order(20)
NotificationSender chatNotificationSender() {
return message -> "CHAT:" + message;
}
@Bean
@Order(10)
NotificationSender mailNotificationSender() {
return message -> "MAIL:" + message;
}
}OrderService は NotificationSender を1つ要求します。WithoutDefault では候補がメールとチャットの2件あり、名前も指定していません。Springのコンテキストは起動に失敗し、UnsatisfiedDependencyException の原因に NoUniqueBeanDefinitionException が入ります。
OrderService.java の全文
package info.syachiku.notification;
import org.springframework.stereotype.Service;
@Service
public class OrderService {
private final NotificationSender notificationSender;
public OrderService(NotificationSender notificationSender) {
this.notificationSender = notificationSender;
}
public String notifyOrder(String orderId) {
return notificationSender.send(orderId);
}
}テストでは、原因の例外型に加え、候補が mailNotificationSender と chatNotificationSender の2件であることを確認します。ここから先は、同じ2件を登録し、メール側だけに @Primary を付けた WithDefault で比べます。
@Primaryは標準で使うBeanを決める
アプリケーション全体ではメール通知を通常使い、一部の処理だけチャット通知を使うなら、メール側を標準候補にできます。
SenderConfigurations.java の WithDefault から、メールを既定にするBean定義の抜粋
@Bean
@Primary
@Order(10)
NotificationSender mailNotificationSender() {
return message -> "MAIL:" + message;
}型に一致する候補のうち、@Primary が付いたBeanが1つなら、単一注入ではそれが選ばれます。注文通知のテストでは候補が2件あることを確認し、notifyOrder("order-42") の結果が MAIL:order-42 になることを確かめます。
@Primaryが向くのは、「特に指定がなければこの実装を使う」というアプリ全体の既定値がある場合です。
@Qualifierは注入先ごとに実装を選ぶ
障害通知だけはチャットへ送りたいなど、呼び出し側の用途によって実装が決まる場合は@Qualifierで候補を絞ります。
FailureAlertService.java の全文
package info.syachiku.notification;
import org.springframework.beans.factory.annotation.Qualifier;
import org.springframework.stereotype.Service;
@Service
public class FailureAlertService {
private final NotificationSender notificationSender;
public FailureAlertService(
@Qualifier("incident-channel") NotificationSender notificationSender) {
this.notificationSender = notificationSender;
}
public String notifyFailure(String incidentId) {
return notificationSender.send(incidentId);
}
}障害通知の引数は incident-channel で候補を絞ります。チャットBeanの定義にも同じ @Qualifier が付いているため一致します。メールは @Primary でも用途が一致せず、候補から外れます。テストでは CHAT:incident-7 を確認します。
incident-channel は用途を示す名前です。同じQualifierに複数のBeanが該当することもあるので、単一注入では絞ったあとに候補を1件に決められるか確認します。
使い分けを表で整理する
| 判断すること | @Primary | @Qualifier |
|---|---|---|
| 選ぶ場所 | Bean側 | 注入先側 |
| 意味 | 型注入の標準候補 | 用途に合う候補へ絞る |
| 向く状況 | 通常実装が1つ決まっている | 処理ごとに実装を選ぶ |
| 注意点 | 既定値が本当に妥当か | 文字列やBean名への依存を増やさないか |
迷ったら、「指定しなかった呼び出し側はどの実装を使うべきか」と質問します。答えが1つなら@Primary、呼び出し側の目的を見ないと決められないなら@Qualifierが候補です。
複数のBeanを全部使うならListで受け取る
すべての通知手段へ送る処理なら、どれか1つを選ぶ必要はありません。同じ型のBeanをListとして注入できます。
BroadcastService.java の全文
package info.syachiku.notification;
import java.util.List;
import org.springframework.stereotype.Service;
@Service
public class BroadcastService {
private final List<NotificationSender> senders;
public BroadcastService(List<NotificationSender> senders) {
this.senders = senders;
}
public List<String> broadcast(String message) {
return senders.stream().map(sender -> sender.send(message)).toList();
}
}List<NotificationSender> には、@Primary のメールだけでなくチャットも入ります。サンプルではチャットのBean定義を先に書いていますが、 @Order(10) をメール、@Order(20) をチャットへ付けています。実行結果は [MAIL:maintenance, CHAT:maintenance] です。
4件のテストは、Springの AnnotationConfigApplicationContext を実際に起動します。起動失敗を想定する1件は assertThrows で例外と候補名を確認するため、そのテストが通ればJUnit上は成功です。
NotificationSelectionTest.java の全文
package info.syachiku.notification;
import java.util.List;
import java.util.Set;
import org.junit.jupiter.api.Test;
import org.springframework.beans.factory.NoUniqueBeanDefinitionException;
import org.springframework.beans.factory.UnsatisfiedDependencyException;
import org.springframework.context.annotation.AnnotationConfigApplicationContext;
import static org.junit.jupiter.api.Assertions.assertEquals;
import static org.junit.jupiter.api.Assertions.assertInstanceOf;
import static org.junit.jupiter.api.Assertions.assertThrows;
class NotificationSelectionTest {
@Test
void 候補が二つで標準がなければ一つの注入先を決められない() {
try (var context = new AnnotationConfigApplicationContext()) {
context.register(SenderConfigurations.WithoutDefault.class, OrderService.class);
var failure = assertThrows(UnsatisfiedDependencyException.class, context::refresh);
var ambiguous = assertInstanceOf(NoUniqueBeanDefinitionException.class,
failure.getMostSpecificCause());
assertEquals(Set.of("mailNotificationSender", "chatNotificationSender"),
Set.copyOf(ambiguous.getBeanNamesFound()));
}
}
@Test
void 型だけで注入した注文通知にはPrimaryのメールを選ぶ() {
try (var context = new AnnotationConfigApplicationContext(
SenderConfigurations.WithDefault.class, OrderService.class)) {
assertEquals(2, context.getBeansOfType(NotificationSender.class).size());
assertEquals("MAIL:order-42", context.getBean(OrderService.class).notifyOrder("order-42"));
}
}
@Test
void メールがPrimaryでもQualifierで障害通知をチャットへ送る() {
try (var context = new AnnotationConfigApplicationContext(
SenderConfigurations.WithDefault.class, FailureAlertService.class)) {
assertEquals("CHAT:incident-7",
context.getBean(FailureAlertService.class).notifyFailure("incident-7"));
}
}
@Test
void ListではPrimaryだけに絞らずOrderで指定した順に両方受け取る() {
try (var context = new AnnotationConfigApplicationContext(
SenderConfigurations.WithDefault.class, BroadcastService.class)) {
assertEquals(List.of("MAIL:maintenance", "CHAT:maintenance"),
context.getBean(BroadcastService.class).broadcast("maintenance"));
}
}
}Tests run: 4, Failures: 0, Errors: 0, Skipped: 0よくあるNG対応
もっとも危険なのは、例外を消すためだけに片方へ@Primaryを付ける対応です。注文処理が本来チャット通知を使うべきなのに、たまたまメール実装が注入されても、アプリケーションは起動してしまいます。
- 理由を確認せず、先に見つけた実装へ
@Primaryを付ける - フィールド名とBean名が一致した時の暗黙解決に依存する
- 実装クラスを直接注入し、インターフェースを使う意味を失わせる
- 用途の異なるBeanを1つの巨大なif文へまとめる
Springのバージョンやコンパイル設定によっては、コンストラクタ引数名とBean名の一致が候補解決に使われることがあります。しかし、それを設計意図の代わりにすると読み手が判断しづらいため、用途が重要なら明示的なQualifierを使います。
現場レビューでの見られ方
// レビューコメント例 NoUniqueBeanDefinitionExceptionを消す目的ではなく、 通常利用する実装がMailでよい理由をコメントに残してください。 // レビューコメント例 このServiceは障害通知専用なので、@Primary任せではなく 用途が読めるQualifierでChat実装を指定したいです。 // レビューコメント例 全実装へ送る要件なら、1件を選ばずList注入で表現できないか確認してください。
レビュー前のセルフチェック
確認リスト
- 同じ型のBeanが何個登録されるか把握しているか
- 標準実装があるのか、呼び出し側ごとに選ぶのか説明できるか
@Primaryをエラー回避だけの目的で付けていないか- Qualifier名が実装クラス名ではなく用途を表しているか
- 全部使う要件なのに1件だけを注入していないか
Beanの選び方をDI全体から学ぶ参考書
@Primaryと@Qualifierを使い分けた後、Beanの登録と依存関係の解決をまとめて理解したい人には、『Spring徹底入門 第2版』が候補です。DIを含むSpringの機能を体系的に確認できます。Spring Framework 5を前提とした本なので、掲載コードと現在の環境の違いは公式ドキュメントで補ってください。出版社の紹介・目次で範囲を確認できます。
Spring徹底入門 第2版
アプリを作った後に、DIやDB更新の仕組みを調べる。
DI、MVC、データアクセス、テスト、セキュリティまで幅広く確認できます。小さなWebアプリを一通り作り、Springの仕組みを詳しく学びたい人に向く参考書です。
- Springで小さなWebアプリを作ったことがある
- DIやトランザクションの仕組みを確認したい
Spring Framework 5向けです。Boot 3の実装に使うコード・設定は、採用している版の公式資料と照合してください。
当サイトはAmazonアソシエイト・プログラムの参加者です。価格・在庫・配送条件はAmazonでご確認ください。
この記事とあわせて読みたい
まとめ
@Primaryは型注入の標準候補を決め、@Qualifierは注入先の用途に合う候補へ絞ります。どちらも複数Beanのエラーを解消できますが、表している設計意図は同じではありません。
新人のうちは、アノテーションを付ける前に「この処理はどの実装を必要としているか」「指定がない場所では何を使うか」を言葉にしてください。その答えが、そのまま@Primaryと@Qualifierの判断基準になります。


