Spring Cloud 速查手册

Spring Cloud Alibaba 微服务组件配置速查：Nacos、Feign、Gateway、Sentinel、Seata 等

Nacos 服务注册(5)

引入依赖

添加 Nacos 服务发现依赖

<dependency>
    <groupId>com.alibaba.cloud</groupId>
    <artifactId>spring-cloud-starter-alibaba-nacos-discovery</artifactId>
</dependency>

配置注册中心

配置 Nacos 服务器地址

spring:
  application:
    name: order-service
  cloud:
    nacos:
      discovery:
        server-addr: 127.0.0.1:8848
        namespace: dev
        group: DEFAULT_GROUP

启用服务发现

主类启用注解

@SpringBootApplication
@EnableDiscoveryClient
public class OrderApplication {
    public static void main(String[] args) {
        SpringApplication.run(OrderApplication.class, args);
    }
}

命名空间隔离

多环境隔离（dev/test/prod）

spring:
  cloud:
    nacos:
      discovery:
        server-addr: 127.0.0.1:8848
        namespace: a1b2c3d4-e5f6-7890-abcd-ef1234567890

服务分组与元数据

服务分组及自定义元数据

spring:
  cloud:
    nacos:
      discovery:
        group: ORDER_GROUP
        metadata:
          version: v1
          region: cn-north

Nacos 配置中心(4)

引入依赖

添加 Nacos 配置中心依赖

<dependency>
    <groupId>com.alibaba.cloud</groupId>
    <artifactId>spring-cloud-starter-alibaba-nacos-config</artifactId>
</dependency>
<dependency>
    <groupId>org.springframework.cloud</groupId>
    <artifactId>spring-cloud-starter-bootstrap</artifactId>
</dependency>

bootstrap 配置

bootstrap.yml 连接配置中心

# bootstrap.yml
spring:
  application:
    name: order-service
  cloud:
    nacos:
      config:
        server-addr: 127.0.0.1:8848
        file-extension: yaml
        namespace: dev
        group: DEFAULT_GROUP
        shared-configs:
          - data-id: common.yaml
            refresh: true

配置分组

按 group 区分不同配置

spring:
  cloud:
    nacos:
      config:
        group: PAYMENT_GROUP
        extension-configs:
          - data-id: payment.yaml
            group: PAYMENT_GROUP
            refresh: true

动态刷新

配置动态刷新

@RestController
@RefreshScope
public class ConfigController {

    @Value("${app.switch.enabled:false}")
    private boolean switchEnabled;

    @GetMapping("/config")
    public boolean getConfig() {
        return switchEnabled;
    }
}

配置中心(4)

Config Server 依赖

Spring Cloud Config 服务端

<dependency>
    <groupId>org.springframework.cloud</groupId>
    <artifactId>spring-cloud-config-server</artifactId>
</dependency>

Config Server 启动

启用配置服务并指定仓库

@SpringBootApplication
@EnableConfigServer
public class ConfigServerApplication { }

# application.yml
spring:
  cloud:
    config:
      server:
        git:
          uri: https://github.com/xxx/config-repo
          default-label: main

Config Client bootstrap

客户端连接 Config Server

spring:
  application:
    name: order-service
  cloud:
    config:
      uri: http://localhost:8888
      profile: dev
      label: main

配置加密

Jasypt 加密敏感配置

<dependency>
    <groupId>com.github.ulisesbocchio</groupId>
    <artifactId>jasypt-spring-boot-starter</artifactId>
</dependency>

# 加密后配置
app.secret=ENC(加密后的密文)
jasypt.encryptor.password=密钥

OpenFeign 远程调用(7)

引入依赖

添加 OpenFeign 依赖

<dependency>
    <groupId>org.springframework.cloud</groupId>
    <artifactId>spring-cloud-starter-openfeign</artifactId>
</dependency>
<dependency>
    <groupId>org.springframework.cloud</groupId>
    <artifactId>spring-cloud-starter-loadbalancer</artifactId>
</dependency>

启用 Feign

主类启用 FeignClients

@SpringBootApplication
@EnableFeignClients
public class OrderApplication { }

定义 Feign 接口

声明式远程调用接口

@FeignClient(name = "user-service", fallbackFactory = UserClientFallback.class)
public interface UserClient {

    @GetMapping("/api/users/{id}")
    User getById(@PathVariable("id") Long id);

    @PostMapping("/api/users")
    User create(@RequestBody UserDTO dto);
}

降级处理

Feign 调用失败的兜底

@Component
public class UserClientFallback implements FallbackFactory<UserClient> {
    @Override
    public UserClient create(Throwable cause) {
        return new UserClient() {
            @Override
            public User getById(Long id) {
                return new User(id, "未知用户");
            }
            @Override
            public User create(UserDTO dto) {
                throw new RuntimeException("服务不可用");
            }
        };
    }
}

请求拦截器

传递 Token 等请求头

@Configuration
public class FeignConfig {
    @Bean
    public RequestInterceptor requestInterceptor() {
        return template -> {
            ServletRequestAttributes attrs = (ServletRequestAttributes)
                RequestContextHolder.getRequestAttributes();
            if (attrs != null) {
                String token = attrs.getRequest().getHeader("Authorization");
                if (token != null) template.header("Authorization", token);
            }
        };
    }
}

错误解码器

自定义 Feign 异常解析

@Component
public class FeignErrorDecoder implements ErrorDecoder {
    private final ErrorDecoder defaultDecoder = new Default();
    @Override
    public Exception decode(String methodKey, Response response) {
        if (response.status() == 404)
            return new NotFoundException("资源不存在");
        if (response.status() >= 500)
            return new ServiceException("远程服务异常");
        return defaultDecoder.decode(methodKey, response);
    }
}

Feign 配置

超时、日志等配置

feign:
  client:
    config:
      default:
        connect-timeout: 5000
        read-timeout: 10000
        logger-level: FULL
  compression:
    request:
      enabled: true
    response:
      enabled: true

logging:
  level:
    com.example.client: DEBUG

Gateway 网关(7)

引入依赖

添加 Gateway 依赖

<dependency>
    <groupId>org.springframework.cloud</groupId>
    <artifactId>spring-cloud-starter-gateway</artifactId>
</dependency>

路由配置

配置路由转发规则

spring:
  cloud:
    gateway:
      routes:
        - id: user-service
          uri: lb://user-service
          predicates:
            - Path=/api/users/**
          filters:
            - StripPrefix=0
        - id: order-service
          uri: lb://order-service
          predicates:
            - Path=/api/orders/**

AddRequestHeader 过滤器

向下游添加请求头

spring:
  cloud:
    gateway:
      routes:
        - id: user-service
          uri: lb://user-service
          predicates:
            - Path=/api/users/**
          filters:
            - AddRequestHeader=X-Request-Source, gateway
            - AddRequestHeader=X-Request-Time, ${T(java.time.Instant).now()}

StripPrefix / RewritePath

路径重写过滤器

filters:
  - StripPrefix=1
  - RewritePath=/api/v1/(?<segment>.*), /${segment}

# StripPrefix=1: /api/users/1 -> /users/1
# RewritePath: /api/v1/orders -> /orders

Retry 过滤器

失败重试配置

filters:
  - name: Retry
    args:
      retries: 3
      statuses: BAD_GATEWAY,SERVICE_UNAVAILABLE
      methods: GET
      backoff:
        firstBackoff: 10ms
        maxBackoff: 50ms
        factor: 2

全局过滤器

自定义全局过滤器（如鉴权）

@Component
public class AuthFilter implements GlobalFilter, Ordered {

    @Override
    public Mono<Void> filter(ServerWebExchange exchange, GatewayFilterChain chain) {
        String token = exchange.getRequest().getHeaders().getFirst("Authorization");
        if (token == null || token.isEmpty()) {
            exchange.getResponse().setStatusCode(HttpStatus.UNAUTHORIZED);
            return exchange.getResponse().setComplete();
        }
        return chain.filter(exchange);
    }

    @Override
    public int getOrder() { return 0; }
}

跨域配置

Gateway 全局跨域设置

spring:
  cloud:
    gateway:
      globalcors:
        cors-configurations:
          '[/**]':
            allowedOrigins: "*"
            allowedMethods: "*"
            allowedHeaders: "*"

Sentinel 限流熔断(7)

引入依赖

添加 Sentinel 依赖

<dependency>
    <groupId>com.alibaba.cloud</groupId>
    <artifactId>spring-cloud-starter-alibaba-sentinel</artifactId>
</dependency>

连接控制台

配置 Sentinel Dashboard

spring:
  cloud:
    sentinel:
      transport:
        dashboard: 127.0.0.1:8080
        port: 8719

注解限流

使用注解定义限流规则

@GetMapping("/api/orders/{id}")
@SentinelResource(value = "getOrder",
    blockHandler = "getOrderBlock",
    fallback = "getOrderFallback")
public Order getOrder(@PathVariable Long id) {
    return orderService.findById(id);
}

public Order getOrderBlock(Long id, BlockException e) {
    return new Order(id, "限流了，请稍后重试");
}

public Order getOrderFallback(Long id, Throwable t) {
    return new Order(id, "服务异常，降级处理");
}

流控规则代码配置

代码中动态添加流控规则

@PostConstruct
public void initFlowRules() {
    List<FlowRule> rules = new ArrayList<>();
    FlowRule rule = new FlowRule();
    rule.setResource("getOrder");
    rule.setGrade(RuleConstant.FLOW_GRADE_QPS);
    rule.setCount(10);
    rules.add(rule);
    FlowRuleManager.loadRules(rules);
}

降级规则

慢调用比例、异常比例熔断

DegradeRule rule = new DegradeRule();
rule.setResource("getOrder");
rule.setGrade(RuleConstant.DEGRADE_GRADE_RT);
rule.setCount(500);
rule.setTimeWindow(10);
rule.setSlowRatioThreshold(0.5);
DegradeRuleManager.loadRules(Collections.singletonList(rule));

热点参数限流

针对参数值限流

ParamFlowRule rule = new ParamFlowRule();
rule.setResource("getOrder");
rule.setParamIdx(0);
rule.setCount(5);
ParamFlowRuleManager.loadRules(Collections.singletonList(rule));

集群流控模式

多实例共享流控配额

spring:
  cloud:
    sentinel:
      transport:
        client-ip: 127.0.0.1
      cluster:
        mode: client
        server:
          host: 127.0.0.1
          port: 18730

负载均衡(3)

LoadBalancer 依赖

Spring Cloud LoadBalancer（替代 Ribbon）

<dependency>
    <groupId>org.springframework.cloud</groupId>
    <artifactId>spring-cloud-starter-loadbalancer</artifactId>
</dependency>

自定义 LoadBalancer

自定义负载均衡策略

@Configuration
public class LoadBalancerConfig {
    @Bean
    public ReactorLoadBalancer<ServiceInstance> customLoadBalancer(
            Environment env, LoadBalancerClientFactory factory) {
        String name = env.getProperty(LoadBalancerClientFactory.PROPERTY_NAME);
        return new RandomLoadBalancer(
            factory.getLazyProvider(name, ServiceInstanceListSupplier.class), name);
    }
}

负载策略配置

配置 LoadBalancer 策略

spring:
  cloud:
    loadbalancer:
      configurations: default
      cache:
        enabled: true

Seata 分布式事务(4)

引入依赖

添加 Seata 依赖

<dependency>
    <groupId>com.alibaba.cloud</groupId>
    <artifactId>spring-cloud-starter-alibaba-seata</artifactId>
</dependency>

配置 Seata

配置 Seata 服务端地址

seata:
  application-id: order-service
  tx-service-group: my_tx_group
  service:
    vgroup-mapping:
      my_tx_group: default
  registry:
    type: nacos
    nacos:
      server-addr: 127.0.0.1:8848

AT 模式

自动补偿，无侵入

@GlobalTransactional(rollbackFor = Exception.class)
public void createOrder(OrderDTO dto) {
    stockClient.deduct(dto.getProductId(), dto.getCount());
    orderMapper.insert(dto);
    accountClient.debit(dto.getUserId(), dto.getAmount());
}

TCC 模式配置

Try-Confirm-Cancel 手动控制

@LocalTCC
public interface AccountTccService {
    @TwoPhaseBusinessAction(name = "debit", commitMethod = "confirm", rollbackMethod = "cancel")
    boolean tryDebit(BusinessActionContext ctx, Long userId, BigDecimal amount);
    boolean confirm(BusinessActionContext ctx);
    boolean cancel(BusinessActionContext ctx);
}

消息驱动(5)

RabbitMQ 配置

Spring Cloud Stream + RabbitMQ

spring:
  cloud:
    stream:
      binders:
        rabbit:
          type: rabbit
          environment:
            spring:
              rabbitmq:
                host: localhost
                port: 5672
      bindings:
        output:
          destination: order-events
          binder: rabbit
        input:
          destination: order-events
          group: payment-group
          binder: rabbit

Kafka 配置

Spring Cloud Stream + Kafka

spring:
  cloud:
    stream:
      binders:
        kafka:
          type: kafka
          environment:
            spring:
              kafka:
                bootstrap-servers: localhost:9092
      bindings:
        output:
          destination: order-events
          binder: kafka
        input:
          destination: order-events
          group: payment-group
          binder: kafka

RocketMQ 配置

Spring Cloud Stream + RocketMQ

<dependency>
    <groupId>com.alibaba.cloud</groupId>
    <artifactId>spring-cloud-starter-stream-rocketmq</artifactId>
</dependency>

spring:
  cloud:
    stream:
      rocketmq:
        binder:
          name-server: 127.0.0.1:9876
      bindings:
        output:
          destination: order-events
        input:
          destination: order-events
          group: payment-group

发送消息

生产者发送消息

@Service
public class OrderEventProducer {

    @Autowired
    private StreamBridge streamBridge;

    public void sendOrderEvent(OrderEvent event) {
        streamBridge.send("output", event);
    }
}

消费消息

消费者接收消息

@Configuration
public class OrderEventConsumer {

    @Bean
    public Consumer<OrderEvent> input() {
        return event -> {
            System.out.println("收到订单事件: " + event);
        };
    }
}

链路追踪(4)

Micrometer + Zipkin

分布式链路追踪依赖

<dependency>
    <groupId>io.micrometer</groupId>
    <artifactId>micrometer-tracing-bridge-brave</artifactId>
</dependency>
<dependency>
    <groupId>io.zipkin.reporter2</groupId>
    <artifactId>zipkin-reporter-brave</artifactId>
</dependency>

追踪配置

配置采样率和 Zipkin 地址

management:
  tracing:
    sampling:
      probability: 1.0
  zipkin:
    tracing:
      endpoint: http://localhost:9411/api/v2/spans

Sleuth 集成

Spring Boot 2.x 使用 Sleuth

<dependency>
    <groupId>org.springframework.cloud</groupId>
    <artifactId>spring-cloud-starter-sleuth</artifactId>
</dependency>
<dependency>
    <groupId>org.springframework.cloud</groupId>
    <artifactId>spring-cloud-sleuth-zipkin</artifactId>
</dependency>

TraceId 传递

Feign 自动传递 TraceId

spring:
  sleuth:
    sampler:
      probability: 1.0
feign:
  client:
    config:
      default:
        request-interceptors:
          - com.example.config.TraceIdPropagationInterceptor

服务保护(3)

Resilience4j 熔断器

熔断、限流、重试

<dependency>
    <groupId>org.springframework.cloud</groupId>
    <artifactId>spring-cloud-starter-circuitbreaker-reactor-resilience4j</artifactId>
</dependency>

resilience4j:
  circuitbreaker:
    instances:
      default:
        slidingWindowSize: 10
        failureRateThreshold: 50
        waitDurationInOpenState: 10s

熔断注解

使用 @CircuitBreaker 注解

@CircuitBreaker(name = "userService", fallbackMethod = "fallback")
public User getUser(Long id) {
    return userClient.getById(id);
}

public User fallback(Long id, Exception e) {
    return new User(id, "服务暂不可用");
}

重试模式

配置重试次数与退避策略

resilience4j:
  retry:
    instances:
      default:
        maxAttempts: 3
        waitDuration: 500ms
        enableExponentialBackoff: true
        exponentialBackoffMultiplier: 2

常用依赖(2)

BOM 版本管理

Spring Cloud Alibaba 版本管理

<dependencyManagement>
    <dependencies>
        <dependency>
            <groupId>org.springframework.cloud</groupId>
            <artifactId>spring-cloud-dependencies</artifactId>
            <version>2023.0.0</version>
            <type>pom</type>
            <scope>import</scope>
        </dependency>
        <dependency>
            <groupId>com.alibaba.cloud</groupId>
            <artifactId>spring-cloud-alibaba-dependencies</artifactId>
            <version>2023.0.0.0</version>
            <type>pom</type>
            <scope>import</scope>
        </dependency>
    </dependencies>
</dependencyManagement>

版本对照表

Spring Boot / Cloud / Alibaba 版本关系

Spring Boot 3.2.x → Spring Cloud 2023.0.x → Alibaba 2023.0.x
Spring Boot 3.0.x → Spring Cloud 2022.0.x → Alibaba 2022.0.x
Spring Boot 2.7.x → Spring Cloud 2021.0.x → Alibaba 2021.0.x
Spring Boot 2.6.x → Spring Cloud 2021.0.x → Alibaba 2021.0.x

注意: Spring Boot 3.x 需要 Java 17+

相关工具

🐬

MySQL 速查手册

MySQL 常用语句、函数、索引、权限操作速查

G

Git 命令速查

Git 日常开发常用命令：分支、远程、回退、暂存等

🐧

Linux 命令速查

Linux 文件、目录、权限、进程、网络常用命令

🌐

HTTP 状态码查询

HTTP 状态码含义、使用场景和常见原因速查