🎯 `@Primary` vs `@Qualifier` in Spring – Which to Use and When?

Spring provides multiple ways to resolve dependency injection conflicts when multiple beans of the same type exist. Two commonly used annotations to handle this are @Primary and @Qualifier.

Let’s dive into the difference between them, their usage with examples, and best practices.

---

🧠 Problem Scenario

Let’s say you have an interface MessageService and two implementations: EmailService and SMSService.

public interface MessageService {
    void sendMessage(String message);
}

@Component
public class EmailService implements MessageService {
    public void sendMessage(String message) {
        System.out.println("Sending Email: " + message);
    }
}

@Component
public class SMSService implements MessageService {
    public void sendMessage(String message) {
        System.out.println("Sending SMS: " + message);
    }
}

Now, when Spring tries to autowire MessageService, it doesn’t know whether to inject EmailService or SMSService—ambiguity arises.

---

✅ Solution 1: @Primary – Mark One as the Default

Use @Primary when one implementation should be the default.

@Component
@Primary
public class EmailService implements MessageService {
    public void sendMessage(String message) {
        System.out.println("Sending Email: " + message);
    }
}

@Component
public class SMSService implements MessageService {
    public void sendMessage(String message) {
        System.out.println("Sending SMS: " + message);
    }
}

@Component
public class NotificationSender {
    private final MessageService messageService;

    @Autowired
    public NotificationSender(MessageService messageService) {
        this.messageService = messageService;
    }

    public void send(String message) {
        messageService.sendMessage(message);
    }
}

🔍 Output:

Sending Email: Hello from @Primary

---

✅ Solution 2: @Qualifier – Be Explicit

Use @Qualifier when you want to be specific about which implementation to inject.

@Component("emailService")
public class EmailService implements MessageService {
    public void sendMessage(String message) {
        System.out.println("Sending Email: " + message);
    }
}

@Component("smsService")
public class SMSService implements MessageService {
    public void sendMessage(String message) {
        System.out.println("Sending SMS: " + message);
    }
}

Now inject with @Qualifier:

@Component
public class NotificationSender {

    private final MessageService messageService;

    @Autowired
    public NotificationSender(@Qualifier("smsService") MessageService messageService) {
        this.messageService = messageService;
    }

    public void send(String message) {
        messageService.sendMessage(message);
    }
}

🔍 Output:

Sending SMS: Hello from @Qualifier

---

⚖️ @Primary vs @Qualifier – When to Use What?

Criteria	@Primary	@Qualifier
Default choice	✅ Yes	❌ No
Explicit selection	❌ No	✅ Yes
Suitable for	One most-used implementation	Multiple specific implementations
Use Case	App has a preferred/default bean	You switch between multiple beans frequently
Can be overridden?	✅ Yes, with @Qualifier	✅ Always explicit

---

💡 Best Practices

• Use @Primary only when one implementation should be used in most cases.

• Use @Qualifier when:

  • You need fine-grained control.
  • You inject different implementations in different places.

• Avoid combining both unless necessary (e.g., default with override).

---

🧪 Bonus: Use with @Bean methods too!

@Configuration
public class AppConfig {

    @Bean
    @Primary
    public MessageService emailService() {
        return new EmailService();
    }

    @Bean
    public MessageService smsService() {
        return new SMSService();
    }
}

You can use the same @Primary and @Qualifier("smsService") approach with @Bean methods.

---

🏁 Conclusion

• Use @Primary to define the default bean when multiple candidates exist.
• Use @Qualifier when you need precise control.
• They’re not mutually exclusive—use both smartly based on your project needs.