Introduction

@RibbonClient and @LoadBalanced are related, but they solve different problems. Historically in Spring Cloud Netflix, @RibbonClient customized a named Ribbon load-balancer client, while @LoadBalanced marked an HTTP client bean so service names such as http://orders could be resolved through a client-side load balancer.

What @LoadBalanced Does

@LoadBalanced is attached to a bean such as RestTemplate or WebClient.Builder. It tells Spring to intercept requests to logical service names and send them through the configured load-balancer client.

1import org.springframework.boot.web.client.RestTemplateBuilder;
2import org.springframework.cloud.client.loadbalancer.LoadBalanced;
3import org.springframework.context.annotation.Bean;
4import org.springframework.context.annotation.Configuration;
5import org.springframework.web.client.RestTemplate;
6
7@Configuration
8class ClientConfig {
9    @Bean
10    @LoadBalanced
11    RestTemplate restTemplate(RestTemplateBuilder builder) {
12        return builder.build();
13    }
14}

With that bean in place, code like restTemplate.getForObject("http://inventory/items", String.class) can use service discovery and client-side load balancing instead of a fixed host name.

What @RibbonClient Does

@RibbonClient is not about marking a RestTemplate. It is about customizing the load-balancer behavior for a particular named service client.

1import org.springframework.cloud.netflix.ribbon.RibbonClient;
2import org.springframework.context.annotation.Configuration;
3
4@Configuration
5@RibbonClient(name = "inventory", configuration = InventoryRibbonConfiguration.class)
6class RibbonSetup {
7}

That custom configuration might change the rule used to choose instances, timeouts, retry settings, or the list of servers when service discovery is not being used.

So the relationship is:

• '@LoadBalanced makes the HTTP client participate in load balancing'
• '@RibbonClient customizes how a specific Ribbon-backed client behaves'

They are not strict alternatives. In older Ribbon-based applications, you often used both.

How They Worked Together

In a classic Spring Cloud Netflix setup, a @LoadBalanced RestTemplate would delegate instance selection to Ribbon. If you also declared @RibbonClient(name = "inventory", ...), requests to the inventory service used that custom Ribbon configuration.

That means one annotation was on the caller bean, and the other was on configuration for a named downstream service.

The Modern Context

Ribbon is now in maintenance mode, and newer Spring Cloud applications generally use Spring Cloud LoadBalancer instead. The idea behind @LoadBalanced still exists, but the customization annotation in newer setups is typically @LoadBalancerClient, not @RibbonClient.

A modern replacement looks more like this:

1import org.springframework.cloud.client.loadbalancer.LoadBalanced;
2import org.springframework.cloud.loadbalancer.annotation.LoadBalancerClient;
3import org.springframework.context.annotation.Bean;
4import org.springframework.context.annotation.Configuration;
5import org.springframework.web.reactive.function.client.WebClient;
6
7@Configuration
8@LoadBalancerClient(name = "inventory", configuration = InventoryLoadBalancerConfig.class)
9class LoadBalancerConfig {
10    @Bean
11    @LoadBalanced
12    WebClient.Builder webClientBuilder() {
13        return WebClient.builder();
14    }
15}

The conceptual split is the same: one piece marks the client bean, and another piece customizes the named service behavior.

Which One Should You Use

If you are maintaining an older Ribbon-based application, use @LoadBalanced when you need service-name resolution on an HTTP client, and use @RibbonClient only when you need named Ribbon customization.

If you are building a new application, prefer Spring Cloud LoadBalancer. In that world, @LoadBalanced remains relevant, but Ribbon-specific customization should not be added to new code unless you are stuck on legacy dependencies.

Common Pitfalls

• Treating @RibbonClient and @LoadBalanced as if they were interchangeable.
• Adding @RibbonClient when all you needed was a load-balanced RestTemplate.
• Forgetting that @RibbonClient is service-specific, not a global marker for every HTTP client.
• Adding Ribbon to a new project instead of using Spring Cloud LoadBalancer.
• Assuming @LoadBalanced works without a load-balancer implementation on the classpath.

Summary

• '@LoadBalanced marks an HTTP client bean so service names can be resolved through client-side load balancing.'
• '@RibbonClient customizes a specific named Ribbon client.'
• In older Ribbon stacks, the two annotations were often used together.
• Ribbon is legacy now; new projects should prefer Spring Cloud LoadBalancer.
• The key distinction is client participation versus named-client customization.