RestTemplate

​ 在 Spring Cloud 微服务架构中，RestTemplate 是一个核心的、同步的 HTTP 客户端，用于服务之间（服务到服务）或服务与外部 HTTP API 进行 RESTful 风格的通信。它的重要性在于简化了 HTTP 请求的发送和响应的处理，特别是在微服务环境中，它与 Spring Cloud 的服务发现（如 Eureka、Nacos）和客户端负载均衡（如 Ribbon，或后来的 Spring Cloud LoadBalancer）深度集成

其位于org.springframwork.web.client包下

核心定位和特点：作了解即可

1. 同步客户端： 发送请求后会阻塞当前线程，直到收到响应。适用于需要等待结果才能继续的业务逻辑
2. 模板化设计： 提供一系列便捷的方法（getForObject, postForEntity, exchange, delete 等）封装了创建请求、设置头信息、发送请求、处理响应、转换数据（JSON/XML ↔ Java Object）、错误处理等底层细节
3. 可扩展性：
   • 消息转换器（HttpMessageConverter）： 自动处理请求/响应的序列化（Java对象->JSON/XML）和反序列化（JSON/XML->Java对象）。默认支持 JSON (Jackson) 和 XML (JAXB)，可自定义添加转换器
   • 拦截器（ClientHttpRequestInterceptor）： 可在请求发送前和响应接收后插入自定义逻辑，如添加认证头、记录日志、重试等
   • 错误处理器（ResponseErrorHandler）： 自定义处理 HTTP 错误响应（如 4xx, 5xx）
4. 与 Spring Cloud 深度集成：
   • 服务发现： 结合 @LoadBalanced 注解，RestTemplate 能够使用服务名代替具体的 host:port 发起调用。它会自动从服务注册中心（如 Eureka）获取该服务的实例列表
   • 客户端负载均衡： 集成 Ribbon (传统方式) 或 Spring Cloud LoadBalancer (新趋势)。@LoadBalanced 注解启用负载均衡能力，RestTemplate 会根据配置的策略（轮询、随机、权重等）从服务实例列表中选择一个发起请求
   • 容错： 虽然 RestTemplate 本身不直接提供熔断/降级，但可以与 Spring Cloud Circuit Breaker (如 Resilience4j, Sentinel) 结合使用或在拦截器中实现重试等简单容错

1. 快速入门

1. SpringCloud默认集成了RestTemplate，但是需要手动配置Bean才生效

2. 容器类中定义RestTemplate的Bean：

   import org.springframework.context.annotation.Bean;
   import org.springframework.context.annotation.Configuration;
   import org.springframework.web.client.RestTemplate;
   
   @Configuration
   public class AppConfig {
       @Bean
       public RestTemplate restTemplate() {
           return new RestTemplate();
       }
   }
   

3. 在服务中直接注入RestTemplate，调用其封装方法来执行 HTTP 请求即可

---

2. 常用方法

RestTemplate提供了多种重载方法，用于执行HTTP请求并理响应。这些方法主要分为以下几类：

1. GET 请求：获取资源
2. POST 请求：创建资源
3. PUT 请求：更新资源
4. DELETE 请求：删除资源
5. 通用请求方法（exchange）：可以发送任何HTTP方法的请求，更灵活

此外，还有HEAD、OPTIONS等方法，但使用较少，这里不详述

2.1 GET 请求方法

2.1.1 getForObject() - 获取响应体并自动反序列化

// 基本形式（带URI变量）
<T> T getForObject(String url, Class<T> responseType, Object... uriVariables)

// 使用Map传递URI变量
<T> T getForObject(String url, Class<T> responseType, Map<String, ?> uriVariables)

// 使用URI对象（无变量）
<T> T getForObject(URI url, Class<T> responseType)

参数说明：

• url：请求URL（可含{placeholders}）
• responseType：响应反序列化的目标类型（如 User.class）
• uriVariables：替换URL占位符的变量（顺序或命名）
• 返回值：反序列化后的响应体对象

示例：

User user = restTemplate.getForObject(
    "http://user-service/users/{id}", 
    User.class, 
    123  // 替换 {id}
);

---

2.1.2 getForEntity()` - 获取完整响应实体

<T> ResponseEntity<T> getForEntity(String url, Class<T> responseType, Object... uriVariables)
<T> ResponseEntity<T> getForEntity(String url, Class<T> responseType, Map<String, ?> uriVariables)
<T> ResponseEntity<T> getForEntity(URI url, Class<T> responseType)

返回值：ResponseEntity<T> 包含：

• getBody()：反序列化后的响应体
• getStatusCode()：HTTP状态码（如 HttpStatus.OK）
• getHeaders()：响应头信息

示例：

ResponseEntity<User> response = restTemplate.getForEntity(
    "http://user-service/users/{id}",
    User.class,
    Map.of("id", 123)
);

if(response.getStatusCode().is2xxSuccessful()) {
    User user = response.getBody();
}

---

2.2 POST 请求方法

2.2.1 postForObject() - 发送请求并获取响应体

<T> T postForObject(String url, Object request, Class<T> responseType, Object... uriVariables)
<T> T postForObject(String url, Object request, Class<T> responseType, Map<String, ?> uriVariables)
<T> T postForObject(URI url, Object request, Class<T> responseType)

参数说明：

• request：请求体对象（自动序列化）
• 其他参数同 GET

示例：

Order newOrder = new Order("Laptop", 1);
Order createdOrder = restTemplate.postForObject(
    "http://order-service/orders",
    newOrder,  // 自动序列化为JSON
    Order.class
);

---

2.2.2 postForEntity() - 获取完整响应实体

<T> ResponseEntity<T> postForEntity(String url, Object request, Class<T> responseType, Object... uriVariables)
// 其他重载形式类似

示例：

ResponseEntity<Order> response = restTemplate.postForEntity(
    "http://order-service/orders",
    newOrder,
    Order.class
);

if(response.getStatusCode() == HttpStatus.CREATED) {
    URI location = response.getHeaders().getLocation(); // 获取新建资源URI
}

---

2.3 PUT 请求方法

void put(String url, Object request, Object... uriVariables)
void put(String url, Object request, Map<String, ?> uriVariables)
void put(URI url, Object request)

特点：无返回值，适用于更新操作

示例：

User updatedUser = new User(123, "New Name");
restTemplate.put(
    "http://user-service/users/{id}",
    updatedUser,
    123
);

---

2.4 DELETE 请求方法

void delete(String url, Object... uriVariables)
void delete(String url, Map<String, ?> uriVariables)
void delete(URI url)

特点：无返回值，适用于删除操作

示例：

restTemplate.delete("http://user-service/users/{id}", 456);

---

2.5 通用方法 exchange()

<T> ResponseEntity<T> exchange(String url, HttpMethod method,
                               HttpEntity<?> requestEntity,
                               Class<T> responseType,
                               Object... uriVariables)

// 其他重要重载：
<T> ResponseEntity<T> exchange(RequestEntity<?> requestEntity,
                               Class<T> responseType)

参数说明：

• method：HTTP方法（HttpMethod.GET, POST 等）
• requestEntity：包含请求头和请求体的封装对象
• responseType：响应体类型
• 返回值：完整响应实体

使用场景：

• 需要自定义请求头
• 使用非标准HTTP方法（如 PATCH）
• 需要精细控制请求/响应

示例：

// 创建带自定义头的请求
HttpHeaders headers = new HttpHeaders();
headers.setBearerAuth("jwt-token");
headers.setContentType(MediaType.APPLICATION_JSON);
HttpEntity<User> requestEntity = new HttpEntity<>(userToUpdate, headers);

// 发送PATCH请求
ResponseEntity<Void> response = restTemplate.exchange(
    "http://user-service/users/{id}",
    HttpMethod.PATCH,    // 使用PATCH方法
    requestEntity,
    Void.class,          // 无响应体
    123
);

---

3. 服务发现集成

在 Spring Cloud 微服务架构中，RestTemplate 的服务发现与负载均衡演进可分为三个阶段，逐步实现从手动到自动化的跃迁

3.1 DiscoveryClient（手动服务发现）

DiscoveryClient 是 Spring Cloud Commons 模块定义的核心服务发现接口，它为不同服务注册中心提供统一的抽象层。不同的服务发现组件（如Eureka, Consul, Zookeeper, Nacos等）都会实现这个接口
通过DiscoveryClient，我们可以查询注册中心中的服务实例信息：

• 查询服务实例：动态获取微服务实例信息
• 获取服务列表：发现注册中心的所有可用服务
• 解耦注册中心：业务代码不依赖具体注册中心实现
• 支持多注册中心：同时连接不同类型的服务注册中心

3.1.1 核心方法

1. 服务实例查询

// 获取指定服务的所有实例
List<ServiceInstance> getInstances(String serviceId);

// 示例：查询用户服务的所有实例
List<ServiceInstance> instances = discoveryClient.getInstances("user-service");

• 返回的 ServiceInstance 包含：

  • serviceId：服务名称（如 “user-service”）

  • host：实例主机地址（IP 或域名）

  • port：服务端口

  • isSecure：是否 HTTPS 协议

  • uri：完整访问地址（如 http://192.168.1.10:8080）

  • metadata：元数据键值对（区域、版本、权重等）

2. 服务列表获取

// 获取注册中心所有服务名称
List<String> getServices();

// 示例：列出所有注册服务
List<String> services = discoveryClient.getServices();
// 输出: [ "order-service", "payment-service", "inventory-service" ]

---

3.1.2 组件实现类

不同的服务发现组件会有不同的实现：

• EurekaDiscoveryClient：用于Eureka
• ConsulDiscoveryClient：用于Consul
• ZookeeperServiceDiscovery：用于Zookeeper
• NacosServiceDiscovery：用于Nacos

---

3.1.3 手动服务发现

如前所述，我们通过DiscoveryClient手动查询服务实例 + 手动选择实例（负载均衡） + 原始 RestTemplate，就可以动用原始的力量实现服务发现和负载均衡了！

• 那么代价呢？
  • 需手动实现负载均衡算法
  • 耦合服务发现逻辑
  • 每次调用都要查询服务实例，可能会对注册中心造成压力，建议缓存实例列表，并注意实例变化
  • 无健康检查/故障转移
  • 代码重复且易错
• 后续方向：在微服务架构中，更推荐使用带有负载均衡的RestTemplate（即使用@LoadBalanced注解）或Feign客户端，它们内部已经集成了服务发现和负载均衡

@Autowired
private DiscoveryClient discoveryClient;

public void callUserService() {
    // 1. 查询可用实例
    List<ServiceInstance> instances = discoveryClient.getInstances("user-service");
    
    if(instances.isEmpty()) {
        throw new ServiceUnavailableException("用户服务不可用");
    }
    
    // 2. 自定义负载均衡策略（随机选择）
    ServiceInstance instance = instances.get(ThreadLocalRandom.current().nextInt(instances.size()));
    
    // 3. 构建请求URL
    String url = String.format("%s/api/users/123", instance.getUri());
    
    // 4. 发起调用
    ResponseEntity<User> response = restTemplate.getForEntity(url, User.class);
    // ... 处理响应
}

---

3.2 LoadBalancerClient（半自动负载均衡）

​ 我们知道，使用DiscoveryClient来实现服务发现和负载均衡太复杂麻烦了，那有没有简单好上手的方法呢？有的同学，LoadBalancerClient登场了

LoadBalancerClient 是 Spring Cloud Commons 中定义的客户端负载均衡核心接口，它连接了服务发现（如DiscoveryClient）和实际的负载均衡服务调用。作为 DiscoveryClient 的上层抽象，它将原始服务发现能力转化为智能路由能力，实现三大核心功能：

1. 服务实例选择：从多个实例中根据策略选择最优目标
2. 请求执行：在选定实例上执行网络请求
3. URI重构：将逻辑服务名转换为物理地址

本质：封装DicoveryClient服务发现和负载均衡（依靠其子接口RibbonLoadBalancerClient/BlockingLoadBalancerClient）的能力，再依靠客户端调用

3.2.1 核心方法

1. 服务实例选择（负载均衡）

// 根据服务ID使用负载均衡策略选择一个服务实例
ServiceInstance choose(String serviceId); // 继承自ServiceInstanceChooser接口的方法

• 参数说明：

  • serviceId：服务注册ID（如 “user-service”）

• 返回的 ServiceInstance 包含：

  • serviceId：服务名称（如 “user-service”）

  • host：实例主机地址（IP 或域名）

  • port：服务端口

  • isSecure：是否 HTTPS 协议

  • uri：完整访问地址（如 http://192.168.1.10:8080）

  • metadata：元数据键值对（区域、版本、权重等）

---

2. 请求执行

// 使用指定的服务实例执行请求，返回响应
<T> T execute(String serviceId, LoadBalancerRequest<T> request) throws IOException;

<T> T execute(String serviceId, ServiceInstance instance, 
             LoadBalancerRequest<T> request) throws IOException;

• 参数说明：
  • serviceId：服务注册ID（如 “user-service”）
  • serviceInstance：要使用的服务实例（通常通过choose方法获得）
  • request：一个LoadBalancerRequest回调，它定义了如何执行请求（例如，使用RestTemplate或WebClient）
• 返回：请求执行的结果，类型由回调决定
• 异常：可能抛出IOException

---

3. URI重构方法

​ 将原始URI（通常包含服务ID作为主机名）重构为实际的服务实例地址（主机和端口）。例如，将http://user-service/api转换为http://192.168.1.100:8080/api。

// 重构URI：将服务ID（逻辑主机名）替换为实际选择的服务实例的主机和端口
URI reconstructURI(ServiceInstance instance, URI original);

//示例
URI originalUri = URI.create("http://my-service/api/data");
ServiceInstance instance = loadBalancer.choose("my-service");
URI actualUri = loadBalancer.reconstructURI(instance, originalUri);
// actualUri会是类似 http://192.168.1.100:8080/api/data

• 参数说明：
  • instance：目标服务实例
  • original：原始URI，包含服务ID作为主机名
• 返回：重构后的URI，指向具体的服务实例。

---

3.2.2 实现关系

LoadBalancerClient本身不包含负载均衡策略，它委托给底层的负载均衡器来实现策略。Spring Cloud提供了两种主要的实现：

1. RibbonLoadBalancerClient：基于Netflix Ribbon的实现（在Spring Cloud 2020.0.0之前是默认的）
2. BlockingLoadBalancerClient：Spring Cloud LoadBalancer的默认实现（从2020.0.0开始成为默认）

BlockingLoadBalancerClient 示例：在Spring Cloud LoadBalancer中，BlockingLoadBalancerClient实现了LoadBalancerClient接口。它的choose方法会委托给ReactorLoadBalancer（通过适配器转换为阻塞调用）

详细的负载均衡策略这里不多说明，可以查看博主文章《负载均衡策略》

---

3.2.3 半自动服务发现

现在我们可以手动使用LoadBalancerClient进行服务调用了，它帮我们封装了负载均衡的服务发现，我们只需要选择服务通信工具发起HTTP请求即可（LoadBalancerClient+RestTemplate）

• 进步点？：
  • 自动过滤不健康实例
  • 内置多种负载均衡算法
  • 支持重试机制
  • 解耦实例选择逻辑
• 遗留问题？：
  • 仍需手动重构 URL
  • 每次调用需创建新 RestTemplate
  • 不够透明化

@Service
public class MyService {
    @Autowired
    private LoadBalancerClient loadBalancer;
    
    public String callService() {
        String serviceId = "my-service";
        // 选择一个实例
        ServiceInstance instance = loadBalancer.choose(serviceId);
        if (instance == null) {
            throw new IllegalStateException("No instances available for " + serviceId);
        }
        
        // 使用execute方法执行请求
        return loadBalancer.execute(serviceId, instance, request -> {
            // 使用RestTemplate发送请求，重构真实URL
            String url = "http://" + instance.getHost() + ":" + instance.getPort() + "/endpoint";
            RestTemplate restTemplate = new RestTemplate();
            ResponseEntity<String> response = restTemplate.getForEntity(url, String.class);
            return response.getBody();
        });
    }
}

---

3.2.4 执行流程

---

3.3 @LoadBalanced（全自动负载均衡）

通过LoadBalancrClient，我们不再需要手动的实现服务发现的负载均衡策略了，但是还是不够，我们还需要手动去重构请求URL，每次都需要创建新的RestTemplate，这是一个重复工作，有没有一个更简单的方法来封装它们呢？有的同学，@LoadBalanced最终登场了

@LoadBalanced 是 Spring Cloud 中的一个关键性注解，它通过简单的声明式配置，将普通的 HTTP 客户端（如 RestTemplate 或 WebClient的Bean）转化为具备智能服务发现和客户端负载均衡能力的增强型客户端。这个注解的本质是 Spring Cloud 对"约定优于配置"理念的完美实践

维度	传统客户端	@LoadBalanced 增强客户端
地址解析	硬编码 IP:端口	自动将服务标识符(如 user-service)解析为实际的服务实例地址
请求路由	直接连接	自动服务发现 + 智能负载均衡
容错能力	无内置容错	集成重试/熔断机制
配置复杂度	高(需手动管理实例)	低(声明式配置)
动态适应性	静态配置	实时感知服务变化

本质：将服务通信客户端封装成自动服务发现和负载均衡能力的高级客户端

3.3.1 核心原理

实际上就是在我们之前所讲的LoadBalanceClient的基础上，再添加了一层LoadBalancerIntercptor拦截器，这个拦截器会拦截客户端发送的请求，解析URL中的服务标识符，替换为实际的服务实例地址，再发送请求

具体步骤：通过拦截器机制将服务名解析转换为实际服务实例地址，并结合负载均衡策略选择合适的实例

1. 注解标记：

   • 使用 @LoadBalanced 标注 RestTemplate 或 WebClient.Builder 的 Bean
   • Spring Cloud 识别该注解并触发负载均衡自动配置

2. 注入拦截器：

   • LoadBalancerAutoConfiguration 自动注入 LoadBalancerInterceptor
   • 该拦截器被添加到被注解标记的客户端组件中

3. 请求拦截过程：

   • 当客户端发起请求（如 restTemplate.getForObject("http://user-service/api")）
   • LoadBalancerInterceptor 拦截请求并提取服务名（user-service）

4. 服务发现与负载均衡：

   • 通过LoadBalancerClient（具体实现为BlockingLoadBalancerClient）：

     1. 从服务注册中心（如 Nacos/Eureka）获取所有可用实例

     2. 使用负载均衡算法（默认轮询）选择目标实例

     3. 重构 URI：将服务名替换为实际 IP:Port（如 http://10.0.0.1:8080/api）

             // 输入: http://order-service/orders
             // 输出: http://10.0.0.5:8080/orders
             URI realUri = loadBalancerClient.reconstructURI(instance, originalUri);
        

5. 请求转发：

   • 将重构后的真实请求转发到目标实例
   • 将响应结果返回给调用方

原理图示例：

---

3.3.2 完整使用

1. 在容器类中配置RestTemplate或WebClient的客户端Bean上添加@LoadBalanced注解

   @Configuration
   public class LoadBalancerConfig {
       
       // 创建负载均衡的RestTemplate
       @Bean
       @LoadBalanced // 魔法注解
       public RestTemplate restTemplate() {
           return new RestTemplate();
       }
       
       // 响应式客户端配置 (Spring WebFlux)
       @Bean
       @LoadBalanced
       public WebClient.Builder loadBalancedWebClientBuilder() {
           return WebClient.builder();
       }
   }
   

2. 服务调用时，使用服务标识符（user-service）而非硬编码（ip:port）

   @Service
   public class OrderService {
       
       // 注入增强的RestTemplate
       @Autowired
       private RestTemplate restTemplate;
       
       public Order createOrder(OrderRequest request) {
           // 使用服务名而非具体地址
           return restTemplate.postForObject(
               "http://order-service/orders", // 虚拟URL
               request,
               Order.class
           );
       }
       
       // 使用WebClient的响应式调用
       public Mono<Product> getProduct(String id) {
           return webClientBuilder.build()
               .get()
               .uri("http://product-service/products/{id}", id)
               .retrieve()
               .bodyToMono(Product.class);
       }
   }
   

---

3.4 总结

从DiscoveryClient到LoadBalancerClient到@LoadBalanced的演进，我们进行一个总结

1. DiscoveryClient（服务发现基础层）：
   • 核心功能：提供注册中心查询能力
   • 主要方法：getInstances(serviceId), getServices()
   • 特点：返回原始服务实例数据，需手动处理负载均衡
   • 局限性：无路由决策能力，需自行实现负载均衡算法
2. LoadBalancerClient（负载均衡中间层）：
   • 核心进化：增加智能路由决策能力
   • 关键接口：choose(serviceId), execute(), reconstructURI()
   • 优势：
     • 封装负载均衡算法
     • 内置健康检查过滤
     • 提供URI重构能力
3. @LoadBalanced：声明式负载均衡（终极形态）

• 革命性创新：
  • 通过注解实现零侵入集成
  • 自动完成服务发现→路由决策→URI重构全流程
  • 与Spring生态无缝整合

维度	DiscoveryClient	LoadBalancerClient	@LoadBalanced
抽象层级	基础设施层	应用逻辑层	声明式接入层
使用复杂度	高（全手动）	中（半自动）	低（零配置）
负载均衡实现	需自行实现	内置算法	全自动执行
URI处理	手动拼接	需调用重构方法	自动转换
健康检查	无	支持	集成+配置扩展
容错能力	无	基础重试	集成熔断+高级重试
代码侵入性	高	中	近乎零
典型调用代码量	15-20行	8-12行	1行

---

3.5 未来方向

1. 服务网格集成：

   • 与Istio/Linkerd协同工作
   • 混合负载均衡策略

2. AI驱动路由：

3. 边缘计算支持：

   • 边缘节点优先路由
   • 离线场景优化

---

接下来，可以学习《负载均衡策略》、《Feign》