Spring Cloud 微服务架构详解：从入门到实战 ☁️

Spring Cloud 是微服务架构的完整解决方案，它将众多分布式开发中需要用到的组件整合在一起，为开发者提供了构建微服务架构应用的工具箱。本文将带你系统学习 Spring Cloud 的核心组件、架构设计以及实战应用！💪

📚 目录导航

一、微服务概述：什么是微服务架构？

1.1 从单体架构到微服务

在微服务诞生之前，传统的应用大多采用单体架构（Monolithic Architecture）。随着业务规模的增长，单体架构的局限性逐渐显现。

1.2 微服务的核心特征

1.3 微服务带来的挑战

挑战 说明 解决方案
服务治理 服务如何被发现和调用 Nacos、Eureka
负载均衡 如何分配请求 Ribbon、LoadBalancer
网关路由 统一入口和权限 Gateway
配置管理 配置文件分散如何管理 Config、Nacos
服务熔断 单个服务故障如何处理 Sentinel、Hystrix
分布式事务 跨服务数据一致性 Seata
日志追踪 分布式日志如何聚合 Sleuth、Zipkin

二、Spring Cloud 生态系统

2.1 Spring Cloud 组件全景图

2.2 版本对应关系

Spring Boot 版本 Spring Cloud 版本 主要特性
3.2.x 2023.0.x 最新稳定版
3.1.x 2022.0.x Anniversary
3.0.x 2022.0.0 重大更新
2.7.x 2021.0.x Kilburn
2.6.x 2021.0.3 稳定版

💡 推荐：新项目使用 Spring Boot 3.x + Spring Cloud 2023.0.x，享受最新特性和性能优化。

2.3 常见微服务架构模式

三、服务注册与发现：Nacos

3.1 Nacos 简介

Nacos（Naming and Configuration Service）是阿里巴巴开源的项目，专注于服务注册与发现和配置管理。

3.2 Nacos 服务端安装

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
# 1. 下载 Nacos
# https://github.com/alibaba/nacos/releases

# 2. 解压并启动（单机模式）
tar -xvf nacos-server-2.3.0.tar.gz
cd nacos/bin

# Linux/Mac 启动
sh startup.sh -m standalone

# Windows 启动
cmd startup.cmd -m standalone

# 3. 访问控制台
# http://localhost:8848/nacos
# 默认用户名/密码：nacos/nacos

3.3 服务提供者配置

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
# provider-service/application.yml
server:
  port: 8081

spring:
  application:
    name: provider-service  # 服务名称
  cloud:
    nacos:
      discovery:
        server-addr: localhost:8848  # Nacos 地址
        namespace: public           # 命名空间
        group: DEFAULT_GROUP      # 分组
      config:
        server-addr: localhost:8848  # 配置中心地址
        file-extension: yaml        # 配置文件格式

# 服务元数据
metadata:
  version: v1
  env: test
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
/**
 * 服务提供者启动类
 */
@SpringBootApplication
@EnableDiscoveryClient  // 启用服务发现
public class ProviderApplication {
    public static void main(String[] args) {
        SpringApplication.run(ProviderApplication.class, args);
    }
}

/**
 * 服务提供者 Controller
 */
@RestController
@RequestMapping("/provider")
public class ProviderController {
    
    @Value("${spring.application.name}")
    private String serviceName;
    
    @GetMapping("/hello")
    public String hello(@RequestParam String name) {
        return "Hello " + name + ", this is " + serviceName;
    }
    
    @GetMapping("/user/{id}")
    public User getUser(@PathVariable Long id) {
        return new User(id, "User" + id, 25);
    }
}

/**
 * 实体类
 */
@Data
@AllArgsConstructor
@NoArgsConstructor
public class User {
    private Long id;
    private String name;
    private Integer age;
}

3.4 服务消费者配置

1
2
3
4
5
6
7
8
9
10
11
# consumer-service/application.yml
server:
  port: 8082

spring:
  application:
    name: consumer-service
  cloud:
    nacos:
      discovery:
        server-addr: localhost:8848
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
/**
 * 服务消费者启动类
 */
@SpringBootApplication
@EnableDiscoveryClient
public class ConsumerApplication {
    public static void main(String[] args) {
        SpringApplication.run(ConsumerApplication.class, args);
    }
}

/**
 * 使用 RestTemplate + @LoadBalanced 调用服务
 */
@Configuration
public class RestTemplateConfig {
    
    @Bean
    @LoadBalanced  // 启用负载均衡
    public RestTemplate restTemplate() {
        return new RestTemplate();
    }
}

/**
 * 服务消费者 Controller
 */
@RestController
@RequestMapping("/consumer")
public class ConsumerController {
    
    @Autowired
    private RestTemplate restTemplate;
    
    /**
     * 通过服务名调用服务
     * 格式：http://{服务名}/{路径}
     */
    @GetMapping("/call-provider")
    public String callProvider(@RequestParam String name) {
        String url = "http://provider-service/provider/hello?name=" + name;
        return restTemplate.getForObject(url, String.class);
    }
}

四、服务调用：OpenFeign

4.1 OpenFeign 简介

OpenFeign 是 Spring Cloud 对 Feign 的封装，提供了声明式 REST 客户端，让服务调用像调用本地方法一样简单。

4.2 快速入门

1. 添加依赖

1
2
3
4
<dependency>
    <groupId>org.springframework.cloud</groupId>
    <artifactId>spring-cloud-starter-openfeign</artifactId>
</dependency>

2. 启用 Feign

1
2
3
4
5
6
7
8
@SpringBootApplication
@EnableFeignClients  // 启用 Feign 客户端
@EnableDiscoveryClient
public class ConsumerApplication {
    public static void main(String[] args) {
        SpringApplication.run(ConsumerApplication.class, args);
    }
}

3. 定义 Feign 客户端接口

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
/**
 * 定义 Feign 客户端接口
 * 
 * @FeignClient 注解属性说明：
 * - name/value: 服务名称（必填）
 * - url: 服务地址（可选，用于直接调用）
 * - fallback: 降级处理类
 * - configuration: Feign 配置类
 */
@FeignClient(name = "provider-service", fallback = ProviderFeignClientFallback.class)
public interface ProviderFeignClient {
    
    /**
     * 调用的目标方法
     * 方法签名必须与 Provider 端一致
     */
    @GetMapping("/provider/hello")
    String hello(@RequestParam("name") String name);
    
    @GetMapping("/provider/user/{id}")
    User getUser(@PathVariable("id") Long id);
    
    @PostMapping("/provider/user")
    User createUser(@RequestBody User user);
}

4. 降级处理类

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
/**
 * Feign 客户端降级处理类
 * 当 Provider 服务不可用时，会自动调用降级方法
 */
@Component
public class ProviderFeignClientFallback implements ProviderFeignClient {
    
    @Override
    public String hello(String name) {
        return "Sorry, " + name + ", the service is unavailable! 😢";
    }
    
    @Override
    public User getUser(Long id) {
        return new User(id, "Default User", 0);
    }
    
    @Override
    public User createUser(User user) {
        return null;
    }
}

5. 使用 Feign 客户端

1
2
3
4
5
6
7
8
9
10
11
12
@RestController
@RequestMapping("/feign")
public class FeignController {
    
    @Autowired
    private ProviderFeignClient providerFeignClient;
    
    @GetMapping("/hello")
    public String hello(@RequestParam String name) {
        return providerFeignClient.hello(name);
    }
}

4.3 OpenFeign 高级配置

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
# application.yml
feign:
  # 启用 Hystrix 熔断器
  hystrix:
    enabled: true
  # 日志级别
  client:
    config:
      default:
        loggerLevel: basic  # none/basic/headers/full
  # 连接超时
  client:
    config:
      default:
        connectTimeout: 5000
        readTimeout: 5000
  # 启用压缩
  compression:
    request:
      enabled: true
    response:
      enabled: true

五、负载均衡：Ribbon

5.1 Ribbon 简介

Ribbon 是 Netflix 开源的客户端负载均衡器，Spring Cloud 将其封装并与 RestTemplate 和 Feign 集成。

5.2 负载均衡策略详解

策略 类名 说明
轮询 RoundRobinRule 依次选择每个服务器
随机 RandomRule 随机选择一个服务器
权重 WeightedResponseTimeRule 根据响应时间分配权重
最少连接 BestAvailableRule 选择连接数最少的服务器
重试 RetryRule 轮询失败时重试

5.3 Ribbon 配置

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
/**
 * 自定义 Ribbon 配置
 */
@Configuration
public class RibbonConfig {
    
    @Bean
    public IRule ribbonRule() {
        // 方式一：使用随机策略
        return new RandomRule();
        
        // 方式二：使用重试策略
        return new RetryRule();
        
        // 方式三：使用权重策略
        return new WeightedResponseTimeRule();
    }
}

/**
 * 为特定服务指定 Ribbon 策略
 */
@Configuration
@RibbonClient(name = "provider-service", configuration = RibbonConfig.class)
public class ProviderRibbonConfig {
    // 为 provider-service 指定自定义配置
}

六、网关服务：Spring Cloud Gateway

6.1 Gateway 简介

Spring Cloud Gateway 是 Spring Cloud 的第二代网关，基于 WebFlux 的响应式编程，性能比 Zuul 优秀很多。

6.2 快速入门

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
# gateway-service/application.yml
server:
  port: 8080

spring:
  application:
    name: gateway-service
  cloud:
    nacos:
      discovery:
        server-addr: localhost:8848
    gateway:
      # 路由配置
      routes:
        # 路由 ID（唯一标识）
        - id: provider-route
          # 目标服务地址
          uri: lb://provider-service
          # 断言条件（路由规则）
          predicates:
            - Path=/provider/**
          # 过滤器
          filters:
            - StripPrefix=1  # 去掉第一层路径
          
        - id: consumer-route
          uri: lb://consumer-service
          predicates:
            - Path=/consumer/**
          filters:
            - StripPrefix=1
      
      # 全局跨域配置
      globalcors:
        corsConfigurations:
          '[/**]':
            allowedOrigins: "*"
            allowedMethods: "*"
            allowedHeaders: "*"
1
2
3
4
5
6
7
8
9
10
/**
 * 网关启动类
 */
@SpringBootApplication
@EnableDiscoveryClient
public class GatewayApplication {
    public static void main(String[] args) {
        SpringApplication.run(GatewayApplication.class, args);
    }
}

6.3 动态路由配置

1
2
3
4
5
6
7
8
9
10
spring:
  cloud:
    nacos:
      discovery:
        server-addr: localhost:8848
    gateway:
      discovery:
        locator:
          enabled: true  # 启用服务发现路由
          lower-case-service-id: true  # 服务 ID 小写
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
/**
 * 通过 Nacos 配置中心动态配置路由
 */
@Configuration
@RefreshScope
public class DynamicRouteConfig {
    
    @Autowired
    private RouteDefinitionWriter routeDefinitionWriter;
    
    @Autowired
    private ApplicationEventPublisher publisher;
    
    /**
     * 动态添加路由
     */
    public void addRoute(RouteDefinition definition) {
        routeDefinitionWriter.save(Mono.just(definition)).subscribe();
        publisher.publishEvent(new RefreshRoutesEvent(this));
    }
    
    /**
     * 动态删除路由
     */
    public void deleteRoute(String routeId) {
        routeDefinitionWriter.delete(Mono.just(routeId)).subscribe();
        publisher.publishEvent(new RefreshRoutesEvent(this));
    }
}

6.4 网关过滤器

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
/**
 * 自定义网关过滤器
 */
@Component
public class RequestTimeFilter extends AbstractGatewayFilterFactory<RequestTimeFilter.Config> {
    
    public RequestTimeFilter() {
        super(Config.class);
    }
    
    @Override
    public GatewayFilter apply(Config config) {
        return (exchange, chain) -> {
            // 前置逻辑
            long startTime = System.currentTimeMillis();
            System.out.println("🔔 请求开始：" + exchange.getRequest().getURI());
            
            return chain.filter(exchange).then(
                Mono.fromRunnable(() -> {
                    // 后置逻辑
                    long duration = System.currentTimeMillis() - startTime;
                    System.out.println("🔕 请求结束，耗时：" + duration + "ms");
                })
            );
        };
    }
    
    public static class Config {
        // 配置属性
    }
}

七、配置中心：Spring Cloud Config

7.1 Config 简介

Spring Cloud Config 为分布式系统中的配置文件管理提供了服务端和客户端支持。

7.2 Config Server 配置

1
2
3
4
5
6
7
8
9
10
11
12
# config-server/application.yml
server:
  port: 8847

spring:
  application:
    name: config-server
  cloud:
    config:
      server:
        nacos:
          server-addr: localhost:8848  # 使用 Nacos 作为配置中心
1
2
3
4
5
6
7
8
9
10
11
/**
 * 配置中心服务端启动类
 */
@SpringBootApplication
@EnableConfigServer
@EnableDiscoveryClient
public class ConfigServerApplication {
    public static void main(String[] args) {
        SpringApplication.run(ConfigServerApplication.class, args);
    }
}

7.3 Nacos 配置中心（推荐）

Nacos 同时支持服务注册发现和配置管理，是更加一体化 solution：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
# 所有微服务共享的配置
# Data ID: shared-config.yaml
# Group: DEFAULT_GROUP
spring:
  datasource:
    url: jdbc:mysql://localhost:3306/demo
    username: root
    password: ${MYSQL_PASSWORD:123456}
  redis:
    host: localhost
    port: 6379

mybatis:
  mapper-locations: classpath:/mapper/**/*.xml
  type-aliases-package: com.example.entity
1
2
3
4
5
6
7
8
// 在各微服务中读取共享配置
@SpringBootApplication
@EnableDiscoveryClient
public class ProviderApplication {
    public static void main(String[] args) {
        SpringApplication.run(ProviderApplication.class, args);
    }
}

八、服务熔断：Sentinel

8.1 Sentinel 简介

Sentinel（哨兵）是阿里巴巴开源的流量控制、熔断降级和系统负载保护组件。

8.2 快速入门

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
# application.yml
spring:
  cloud:
    sentinel:
      enabled: true
      # Sentinel 控制台地址
      transport:
        dashboard: localhost:8080
      # 配置文件持久化（可选）
      datasource:
        ds:
          nacos:
            server-addr: localhost:8848
            dataId: ${spring.application.name}-sentinel
            groupId: DEFAULT_GROUP
            dataType: json
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
/**
 * 使用 Sentinel 注解进行熔断降级
 */
@RestController
@RequestMapping("/sentinel")
public class SentinelController {
    
    /**
     * 定义资源名称
     * fallbackClass 指定降级处理类
     */
    @GetMapping("/hello")
    @SentinelResource(value = "helloResource", 
                      fallback = "helloFallback",
                      blockHandler = "helloBlockHandler")
    public String hello(@RequestParam String name) {
        return "Hello " + name;
    }
    
    /**
     * 降级处理方法
     * 方法签名必须与原方法一致
     */
    public String helloFallback(String name, Throwable throwable) {
        return "😢 Sorry, " + name + ", service is unavailable: " + throwable.getMessage();
    }
    
    /**
     * 流控处理方法
     */
    public String helloBlockHandler(String name, BlockException ex) {
        return "🚦 Sorry, " + name + ", request is rejected by flow control";
    }
}

8.3 Feign 集成 Sentinel

1
2
3
4
# 启用 Feign Sentinel 降级
feign:
  sentinel:
    enabled: true
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
/**
 * Feign 客户端配置降级
 */
@FeignClient(name = "provider-service", 
             fallback = ProviderFeignClientFallback.class)
public interface ProviderFeignClient {
    // ...
}

/**
 * 降级处理实现
 */
@Component
public class ProviderFeignClientFallback implements ProviderFeignClient {
    @Override
    public String hello(String name) {
        return "😢 Service is currently unavailable";
    }
    // ...
}

九、消息驱动：Spring Cloud Stream

9.1 Stream 简介

Spring Cloud Stream 是消息中间件的抽象层，支持 RabbitMQ、Kafka、RocketMQ 等多种消息队列。

9.2 快速入门

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
# application.yml
spring:
  cloud:
    stream:
      # 定义绑定器
      binders:
        local-kafka:
          type: kafka
          environment:
            spring.cloud.stream.kafka.binder.brokers: localhost:9092
      # 定义绑定
      bindings:
        output:
          binder: local-kafka
          destination: test-topic
        input:
          binder: local-kafka
          destination: test-topic
          group: consumer-group-1
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
/**
 * 消息生产者
 */
@EnableBinding(Source.class)
public class MessageProducer {
    
    @Autowired
    private MessageChannel output;
    
    public void sendMessage(String message) {
        output.send(MessageBuilder.withPayload(message)
                .setHeader("content-type", "text/plain")
                .build());
        System.out.println("📤 Sent: " + message);
    }
}

/**
 * 消息消费者
 */
@EnableBinding(Sink.class)
public class MessageConsumer {
    
    @StreamListener(Sink.INPUT)
    public void receiveMessage(String message) {
        System.out.println("📥 Received: " + message);
    }
}

十、微服务实战：完整项目构建

10.1 项目结构设计

10.2 服务间调用示例

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
/**
 * OrderService 调用 UserService
 */
@Service
public class OrderService {
    
    @Autowired
    private RestTemplate restTemplate;
    
    public Order createOrder(Long userId, String product) {
        // 调用用户服务获取用户信息
        String userUrl = "http://user-service/user/" + userId;
        User user = restTemplate.getForObject(userUrl, User.class);
        
        // 创建订单
        Order order = new Order();
        order.setUserId(userId);
        order.setUserName(user.getName());
        order.setProduct(product);
        order.setCreateTime(new Date());
        
        return orderRepository.save(order);
    }
}

10.3 分布式事务示例

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
/**
 * Seata 分布式事务配置
 */
@Configuration
@EnableAutoDataSourceProxy
@EnableGlobalTransaction
public class TransactionConfig {
    // Seata AT 模式自动配置
}

/**
 * 使用 @GlobalTransactional 注解开启分布式事务
 */
@Service
public class OrderService {
    
    @GlobalTransactional(rollbackFor = Exception.class)
    public void createOrderWithTransaction(Long userId, String product) {
        // 1. 创建订单
        Order order = new Order();
        order.setUserId(userId);
        orderRepository.save(order);
        
        // 2. 扣减库存（远程调用）
        inventoryClient.deduct(product, 1);
        
        // 3. 扣减余额（远程调用）
        accountClient.deduct(userId, product.getPrice());
        
        // 如果任何一步失败，整个事务自动回滚
    }
}

十一、微服务安全：Spring Cloud Security

11.1 OAuth2 授权模式

11.2 JWT Token 认证

1
2
3
4
5
6
7
8
# application.yml
spring:
  security:
    oauth2:
      resourceserver:
        jwt:
          # 使用 Nacos 配置的公钥
          jwk-set-uri: http://localhost:8848/nacos/discovery/v2/jwks
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
/**
 * OAuth2 资源服务器配置
 */
@Configuration
@EnableResourceServer
public class ResourceServerConfig extends ResourceServerConfigurerAdapter {
    
    @Override
    public void configure(HttpSecurity http) throws Exception {
        http
            .authorizeRequests()
            .antMatchers("/user/**").hasAuthority("SCOPE_user:read")
            .antMatchers("/order/**").hasAuthority("SCOPE_order:write")
            .anyRequest().authenticated();
    }
}

/**
 * 获取当前用户信息
 */
@RestController
@RequestMapping("/user")
public class UserController {
    
    @GetMapping("/me")
    public UserPrincipal getCurrentUser(@AuthenticationPrincipal Jwt jwt) {
        return new UserPrincipal(
            jwt.getSubject(),
            jwt.getClaimAsString("email"),
            jwt.getClaimAsStringList("roles")
        );
    }
}

十二、总结与展望

12.1 核心知识点回顾

12.2 学习路线建议

💡 写给读者的话：Spring Cloud 提供了构建微服务架构的完整工具箱，但掌握这些组件只是基础。真正的微服务开发还需要理解分布式系统的复杂性，如CAP理论、一致性、事务等。希望本文能帮助你开启微服务之旅，在实践中不断深化理解！☁️

📅 本文首次发布于 2026 年 5 月 24 日