Как @Qualifier связан с бином

Ответ

@Qualifier — это аннотация Spring, которая явно указывает, какой конкретный бин нужно внедрить когда есть несколько бинов одного типа. Она работает вместе с @Autowired для уточнения выбора нужного бина.

Проблема: амбигуозность при множестве бинов

Представь ситуацию: у тебя есть интерфейс и несколько реализаций.

public interface PaymentService {
    void processPayment(BigDecimal amount);
}

@Component
public class CreditCardPaymentService implements PaymentService {
    @Override
    public void processPayment(BigDecimal amount) {
        System.out.println("Processing with Credit Card: " + amount);
    }
}

@Component
public class PayPalPaymentService implements PaymentService {
    @Override
    public void processPayment(BigDecimal amount) {
        System.out.println("Processing with PayPal: " + amount);
    }
}

// ❌ ОШИБКА! Какой бин внедрить?
@Component
public class OrderService {
    @Autowired
    private PaymentService paymentService;
    
    public void checkout(BigDecimal amount) {
        paymentService.processPayment(amount);
    }
}

Spring не знает, какой из двух бинов (CreditCardPaymentService или PayPalPaymentService) внедрить, и выбросит исключение:

NoUniqueBeanDefinitionException: No qualifying bean of type 'PaymentService' available: expected single matching bean but found 2: creditCardPaymentService, payPalPaymentService

Решение: @Qualifier

@Qualifier привязывает конкретный бин по его имени (bean name).

// Способ 1: Использование по умолчанию имени класса
@Component
public class OrderService {
    @Autowired
    @Qualifier("creditCardPaymentService") // Имя класса с маленькой первой буквой
    private PaymentService paymentService;
    
    public void checkout(BigDecimal amount) {
        paymentService.processPayment(amount);
    }
}

Как работает связь @Qualifier с бином

Шаг 1: Регистрация бина

@Component // Автоматически регистрирует бин с именем "creditCardPaymentService"
public class CreditCardPaymentService implements PaymentService {
}

При использовании @Component без явного имени, Spring регистрирует бин под именем, полученным от имени класса (первая буква в нижний регистр).

Шаг 2: Внедрение через @Qualifier

@Autowired
@Qualifier("creditCardPaymentService") // Ищет бин с ИМЕ НЕМ "creditCardPaymentService"
private PaymentService paymentService;

Spring ищет в контексте бин, чей bean name совпадает с значением в @Qualifier, и внедряет его.

Практические примеры

Пример 1: Явное имя бина с @Bean

@Configuration
public class PaymentConfig {
    @Bean(name = "creditCard") // Явное имя бина
    public PaymentService creditCardPayment() {
        return new CreditCardPaymentService();
    }
    
    @Bean(name = "paypal")
    public PaymentService paypalPayment() {
        return new PayPalPaymentService();
    }
}

@Component
public class OrderService {
    @Autowired
    @Qualifier("creditCard") // Ссылается на bean name
    private PaymentService paymentService;
}

Пример 2: Множественное внедрение разных бинов

@Component
public class PaymentProcessor {
    @Autowired
    @Qualifier("creditCardPaymentService")
    private PaymentService creditCardService;
    
    @Autowired
    @Qualifier("payPalPaymentService")
    private PaymentService paypalService;
    
    public void processByPaymentType(String type, BigDecimal amount) {
        if ("credit-card".equals(type)) {
            creditCardService.processPayment(amount);
        } else if ("paypal".equals(type)) {
            paypalService.processPayment(amount);
        }
    }
}

Пример 3: Кастомная аннотация вместо строк

Использование строк в @Qualifier опасно — если переименуешь бин, приложение сломается при runtime.

// Кастомная аннотация
@Retention(RetentionPolicy.RUNTIME)
@Target({ElementType.FIELD, ElementType.PARAMETER})
@Qualifier("creditCardPaymentService")
public @interface CreditCardPayment {
}

@Retention(RetentionPolicy.RUNTIME)
@Target({ElementType.FIELD, ElementType.PARAMETER})
@Qualifier("payPalPaymentService")
public @interface PayPalPayment {
}

// Использование
@Component
public class OrderService {
    @Autowired
    @CreditCardPayment // Безопаснее, чем строка
    private PaymentService paymentService;
}

Пример 4: Внедрение в конструктор и методы

@Component
public class OrderService {
    private PaymentService paymentService;
    
    // Через конструктор
    public OrderService(@Qualifier("creditCardPaymentService") PaymentService service) {
        this.paymentService = service;
    }
    
    // Через setter
    @Autowired
    public void setPaymentService(@Qualifier("payPalPaymentService") PaymentService service) {
        this.paymentService = service;
    }
    
    // Через параметр метода
    @PostConstruct
    public void init(@Qualifier("creditCardPaymentService") PaymentService service) {
        this.paymentService = service;
    }
}

Связь между @Qualifier и bean name

бин регистрируется → @Component("creditCardPaymentService")
         ↓
bean name создаётся → "creditCardPaymentService"
         ↓
@Qualifier ищет бин по имени → @Qualifier("creditCardPaymentService")
         ↓
Spring находит совпадение → внедряет нужный бин

Способы определения bean name

1. @Component без параметра — используется имя класса (первая буква в нижний регистр)

@Component // bean name = "myService"
public class MyService {}

2. @Component с параметром — явное имя

@Component("myCustomName") // bean name = "myCustomName"
public class MyService {}

3. @Bean без параметра — используется имя метода

@Bean // bean name = "myService"
public MyService myService() {}

4. @Bean с параметром — явное имя

@Bean(name = {"myService", "alias"}) // bean names = "myService", "alias"
public MyService myService() {}

Приоритет при выборе бина

1. @Qualifier (явное указание) — ПЕРВЫЙ ПРИОРИТЕТ
2. @Primary — если несколько бинов и нет @Qualifier
3. bean name совпадает с именем поля — fallback
4. Исключение, если ничего не совпадает

Best Practices

✅ Используй кастомные аннотации вместо строк

@Autowired
@CreditCardPayment // Безопаснее
private PaymentService service;

✅ Явно называй бины в @Bean

@Bean(name = "primaryPayment")
public PaymentService creditCard() {}

✅ Используй @Primary для дефолтного бина

@Component
@Primary
public class CreditCardPaymentService implements PaymentService {}

❌ Избегай хардкода строк в @Qualifier

// Плохо
@Qualifier("creditCardPaymentService")

// Хорошо
@CreditCardPayment

Альтернативы @Qualifier

1. @Primary — указывает бин по умолчанию

@Component
@Primary // Будет внедрен если нет @Qualifier
public class CreditCardPaymentService implements PaymentService {}

2. @Resource — из JSR-250

@Resource(name = "creditCardPaymentService")
private PaymentService paymentService;

3. ObjectProvider — программная работа с бинами

private ObjectProvider<PaymentService> paymentServices;

public void process() {
    PaymentService service = paymentServices.getIfAvailable();
}

Заключение

@Qualifier — это явный механизм уточнения при наличии нескольких бинов одного типа. Она связана с бином по его имени (bean name) и позволяет Spring выбрать нужную реализацию. Это essential инструмент для сложных приложений с множественными реализациями одного интерфейса.