Для чего нужен @Qualifier?

@Qualifier в Spring: разрешение неоднозначности зависимостей

@Qualifier используется для разрешения конфликтов, когда Spring не может определить, какую из нескольких реализаций интерфейса инъектировать. Это мощный инструмент для работы с множественными реализациями одного интерфейса.

Проблема, которую решает @Qualifier

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

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

@Component
public class StripePaymentGateway implements PaymentGateway {
    @Override
    public void processPayment(BigDecimal amount) {
        System.out.println("Processing via Stripe: " + amount);
    }
}

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

@Component
public class SquarePaymentGateway implements PaymentGateway {
    @Override
    public void processPayment(BigDecimal amount) {
        System.out.println("Processing via Square: " + amount);
    }
}

Теперь если ты попытаешься инъектировать интерфейс:

// ❌ ОШИБКА! Spring не знает, какую реализацию выбрать:
@Service
public class OrderService {
    @Autowired
    private PaymentGateway paymentGateway; // Какой из трёх?
    
    public void completeOrder(BigDecimal amount) {
        paymentGateway.processPayment(amount);
    }
}

// Error: Field paymentGateway in OrderService required a single bean,
// but 3 were found: stripePaymentGateway, payPalPaymentGateway, squarePaymentGateway

Здесь @Qualifier спешит на помощь.

Решение: @Qualifier

Способ 1: По имени компонента (Default)

// Каждый @Component имеет имя (по умолчанию — первая буква маленькая)
@Component
public class StripePaymentGateway implements PaymentGateway { /* ... */ }
// Имя: stripePaymentGateway

@Component
public class PayPalPaymentGateway implements PaymentGateway { /* ... */ }
// Имя: payPalPaymentGateway

// ✅ Используем @Qualifier с именем:
@Service
public class OrderService {
    @Autowired
    @Qualifier("stripePaymentGateway")
    private PaymentGateway paymentGateway;
    
    public void completeOrder(BigDecimal amount) {
        paymentGateway.processPayment(amount); // Будет использовать Stripe
    }
}

Способ 2: Кастомное имя через @Component

@Component("stripe")
public class StripePaymentGateway implements PaymentGateway { /* ... */ }

@Component("paypal")
public class PayPalPaymentGateway implements PaymentGateway { /* ... */ }

@Service
public class OrderService {
    @Autowired
    @Qualifier("stripe")
    private PaymentGateway paymentGateway;
}

Способ 3: Через конфигурацию (явная регистрация)

@Configuration
public class PaymentConfiguration {
    
    @Bean
    @Qualifier("stripe")
    public PaymentGateway stripePaymentGateway() {
        return new StripePaymentGateway();
    }
    
    @Bean
    @Qualifier("paypal")
    public PaymentGateway payPalPaymentGateway() {
        return new PayPalPaymentGateway();
    }
    
    @Bean
    @Qualifier("square")
    public PaymentGateway squarePaymentGateway() {
        return new SquarePaymentGateway();
    }
}

// Использование:
@Service
public class OrderService {
    @Autowired
    @Qualifier("paypal")
    private PaymentGateway paymentGateway;
}

Продвинутые техники

1. Кастомный Qualifier аннотация

Вместо строк лучше использовать типобезопасные аннотации:

// Создаём кастомную аннотацию:
@Target({ElementType.FIELD, ElementType.PARAMETER, ElementType.METHOD})
@Retention(RetentionPolicy.RUNTIME)
@Qualifier
public @interface Stripe {
}

@Target({ElementType.FIELD, ElementType.PARAMETER, ElementType.METHOD})
@Retention(RetentionPolicy.RUNTIME)
@Qualifier
public @interface PayPal {
}

// Применяем на реализации:
@Component
@Stripe
public class StripePaymentGateway implements PaymentGateway { /* ... */ }

@Component
@PayPal
public class PayPalPaymentGateway implements PaymentGateway { /* ... */ }

// Инъектируем через кастомный qualifier (типобезопасно!):
@Service
public class OrderService {
    @Autowired
    @Stripe
    private PaymentGateway paymentGateway;
    
    public void completeOrder(BigDecimal amount) {
        paymentGateway.processPayment(amount);
    }
}

2. Инъекция нескольких реализаций

// Если нужны ВСЕ реализации:
@Service
public class PaymentServiceRouter {
    private final List<PaymentGateway> allGateways;
    
    @Autowired
    public PaymentServiceRouter(List<PaymentGateway> allGateways) {
        this.allGateways = allGateways; // Получим все 3 реализации
    }
    
    public void processPaymentViaAllGateways(BigDecimal amount) {
        allGateways.forEach(gateway -> gateway.processPayment(amount));
    }
}

// Или инъекция Map:
@Service
public class PaymentServiceRouter {
    private final Map<String, PaymentGateway> gateways;
    
    @Autowired
    public PaymentServiceRouter(Map<String, PaymentGateway> gateways) {
        this.gateways = gateways;
        // gateways.keySet() → ["stripePaymentGateway", "payPalPaymentGateway", ...]
    }
    
    public void processPayment(String provider, BigDecimal amount) {
        PaymentGateway gateway = gateways.get(provider);
        if (gateway != null) {
            gateway.processPayment(amount);
        }
    }
}

3. @Primary для значения "по умолчанию"

Если не указан @Qualifier, используется @Primary:

@Component
@Primary // Эта реализация будет выбрана по умолчанию
public class StripePaymentGateway implements PaymentGateway { /* ... */ }

@Component
public class PayPalPaymentGateway implements PaymentGateway { /* ... */ }

// ✅ Использует StripePaymentGateway по умолчанию:
@Service
public class OrderService {
    @Autowired
    private PaymentGateway paymentGateway; // Stripe (primary)
}

// Но можно переопределить:
@Service
public class RefundService {
    @Autowired
    @Qualifier("payPalPaymentGateway")
    private PaymentGateway paymentGateway; // PayPal (override primary)
}

Практический пример: Payment Service

// Конфиг с разными профилями:
@Configuration
@ConditionalOnProperty(name = "payment.provider", havingValue = "stripe")
public class StripeConfiguration {
    @Bean
    public PaymentGateway paymentGateway() {
        return new StripePaymentGateway();
    }
}

@Configuration
@ConditionalOnProperty(name = "payment.provider", havingValue = "paypal")
public class PayPalConfiguration {
    @Bean
    public PaymentGateway paymentGateway() {
        return new PayPalPaymentGateway();
    }
}

// В application.yml:
// payment:
//   provider: stripe  # или paypal

@Service
public class OrderService {
    @Autowired
    private PaymentGateway paymentGateway; // Spring выберет в зависимости от профиля
    
    public void processOrder(Order order) {
        paymentGateway.processPayment(order.getAmount());
    }
}

Когда НЕ использовать @Qualifier

// ❌ Признак плохого дизайна:
// Если нужно часто использовать @Qualifier, значит:
// 1. Слишком много реализаций одного интерфейса
// 2. Нужна лучше абстракция

// ✅ Лучший подход: Strategy Pattern с Factory
@Component
public class PaymentGatewayFactory {
    @Autowired
    private StripePaymentGateway stripe;
    
    @Autowired
    private PayPalPaymentGateway paypal;
    
    public PaymentGateway getGateway(PaymentProvider provider) {
        return switch (provider) {
            case STRIPE -> stripe;
            case PAYPAL -> paypal;
            case SQUARE -> throw new UnsupportedOperationException();
        };
    }
}

@Service
public class OrderService {
    @Autowired
    private PaymentGatewayFactory factory;
    
    public void processOrder(Order order) {
        PaymentGateway gateway = factory.getGateway(order.getPaymentProvider());
        gateway.processPayment(order.getAmount());
    }
}

Вывод

@Qualifier нужен, когда:

• Есть несколько реализаций одного интерфейса
• Spring не может автоматически выбрать нужную
• Нужно явно указать, какую использовать

Лучшие практики:

1. Предпочитай кастомные @Qualifier аннотации вместо строк
2. Используй @Primary для значения по умолчанию
3. Если @Qualifier требуется часто — пересмотри архитектуру
4. Рассмотри Factory Pattern или Strategy Pattern для сложных случаев