【阶段 7】微服务：Spring Cloud Alibaba 实战

# 1. 下载并启动 Nacos（单机模式，用于注册中心 + 配置中心）
wget https://github.com/alibaba/nacos/releases/download/2.3.2/nacos-server-2.3.2.tar.gz
tar -zxvf nacos-server-2.3.2.tar.gz
cd nacos/bin
# Linux/Unix 单机模式启动
sh startup.sh -m standalone
# 默认控制台地址：http://localhost:8848/nacos ，账号/密码均为 nacos

# 2. 下载并启动 Sentinel Dashboard（可视化限流规则控制台）
wget https://github.com/alibaba/Sentinel/releases/download/1.8.7/sentinel-dashboard-1.8.7.jar
java -Dserver.port=8858 -Dcsp.sentinel.dashboard.server=localhost:8858 
     -Dproject.name=sentinel-dashboard -jar sentinel-dashboard-1.8.7.jar
# 默认控制台地址：http://localhost:8858 ，账号/密码均为 sentinel

# 3. 初始化三个业务库
mysql -uroot -p <<'EOF'
CREATE DATABASE IF NOT EXISTS db_user  DEFAULT CHARACTER SET utf8mb4;
CREATE DATABASE IF NOT EXISTS db_order DEFAULT CHARACTER SET utf8mb4;
CREATE DATABASE IF NOT EXISTS db_stock DEFAULT CHARACTER SET utf8mb4;
EOF

<!-- user-service/pom.xml 的依赖片段 -->
<dependency>
    <groupId>com.alibaba.cloud</groupId>
    <artifactId>spring-cloud-starter-alibaba-nacos-discovery</artifactId>
</dependency>
<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-web</artifactId>
</dependency>

package com.example.user;

import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;
import org.springframework.cloud.client.discovery.EnableDiscoveryClient;

@SpringBootApplication
@EnableDiscoveryClient   // 显式开启服务注册与发现，语义清晰
public class UserServiceApplication {
    public static void main(String[] args) {
        SpringApplication.run(UserServiceApplication.class, args);
    }
}

spring:
  application:
    name: user-service          # 服务名，注册中心和 Feign 调用都以它为准
  cloud:
    nacos:
      discovery:
        server-addr: ${NACOS_ADDR:localhost:8848}   # 环境变量可覆盖
        namespace: dev          # 命名空间：环境隔离（见第 3 章）
        group: DEFAULT_GROUP    # 分组：默认 DEFAULT_GROUP
server:
  port: 8081

<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-actuator</artifactId>
</dependency>

management:
  endpoints:
    web:
      exposure:
        include: health          # 暴露 /actuator/health
  endpoint:
    health:
      show-details: always
spring:
  cloud:
    nacos:
      discovery:
        # 临时实例（默认）：靠客户端心跳上报，15s 没心跳标记不健康，30s 剔除
        ephemeral: true

spring:
  cloud:
    nacos:
      discovery:
        metadata:
          version: v1.2.0       # 版本号，配合灰度路由使用
          zone: hangzhou        # 机房/可用区，配合就近路由使用

package com.example.user.controller;

import com.example.common.ApiResult;
import com.example.common.ErrorCode;
import com.example.user.entity.User;
import com.example.user.service.UserService;
import lombok.RequiredArgsConstructor;
import lombok.extern.slf4j.Slf4j;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.PathVariable;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RestController;

@RestController
@RequestMapping("/api/users")
@RequiredArgsConstructor
@Slf4j
public class UserController {

    private final UserService userService;   // 构造器注入，依赖不可变

    @GetMapping("/{id}")
    public ApiResult<User> getById(@PathVariable("id") Long id) {
        log.info("收到查询用户请求，userId={}", id);
        User user = userService.getById(id);
        if (user == null) {
            // 查不到返回业务错误码，而不是 200 + null，下游能明确区分
            return ApiResult.fail(ErrorCode.USER_NOT_FOUND);
        }
        return ApiResult.ok(user);
    }
}

package com.example.order.config;

import org.springframework.cloud.client.loadbalancer.LoadBalanced;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.web.client.RestTemplate;

@Configuration
public class RestTemplateConfig {

    @Bean
    @LoadBalanced   // 关键：让 RestTemplate 支持按服务名 + 负载均衡调用
    public RestTemplate restTemplate() {
        return new RestTemplate();
    }
}

// order-service 里调用 user-service 的片段
// 注意 URL 里写的是服务名 user-service，而非 IP:port
String url = "http://user-service/api/users/" + userId;
ApiResult<User> result = restTemplate.getForObject(url, ApiResult.class);

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

spring:
  application:
    name: user-service
  cloud:
    nacos:
      config:
        server-addr: ${NACOS_ADDR:localhost:8848}
        file-extension: yaml          # 配置内容格式
        namespace: dev                # 与 discovery 的 namespace 对应
        group: DEFAULT_GROUP
  config:
    import:
      - optional:nacos:user-service.yaml   # 拉取 dataId=user-service.yaml 的配置

# 内容示例：把业务参数集中到 Nacos
app:
  name: 用户中心服务
  swagger-enabled: true
order:
  timeout-ms: 3000

spring:
  cloud:
    nacos:
      config:
        server-addr: ${NACOS_ADDR:localhost:8848}
        file-extension: yaml
        namespace: dev
        group: DEFAULT_GROUP
        extension-configs:
          - data-id: common-config.yaml      # 公共配置，所有服务共享
            group: DEFAULT_GROUP
            refresh: true                    # 公共配置变更也参与热更新
  config:
    import:
      - optional:nacos:user-service.yaml

package com.example.user.controller;

import lombok.extern.slf4j.Slf4j;
import org.springframework.beans.factory.annotation.Value;
import org.springframework.cloud.context.config.annotation.RefreshScope;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RestController;

@RestController
@RequestMapping("/api/config")
@RefreshScope   // 关键：配置变更时，该 Bean 会被销毁重建，@Value 重新注入
@Slf4j
public class ConfigController {

    @Value("${app.name:默认名称}")   // 加了默认值，配置缺失也不报错
    private String appName;

    @Value("${app.swagger-enabled:false}")
    private boolean swaggerEnabled;

    @GetMapping("/app-name")
    public String appName() {
        return appName + "，swagger=" + swaggerEnabled;
    }
}

package com.example.user.config;

import com.alibaba.cloud.nacos.NacosConfigManager;
import jakarta.annotation.PostConstruct;
import lombok.RequiredArgsConstructor;
import lombok.extern.slf4j.Slf4j;
import org.springframework.stereotype.Component;

@Component
@RequiredArgsConstructor
@Slf4j
public class ConfigChangeListener {

    private final NacosConfigManager nacosConfigManager;

    @PostConstruct
    public void init() throws Exception {
        // 监听 dataId=user-service.yaml 的变更，配置一变就回调
        nacosConfigManager.getConfigService().addListener("user-service.yaml", "DEFAULT_GROUP",
                new com.alibaba.nacos.api.config.listener.Listener() {
                    @Override
                    public void receiveConfigInfo(String configInfo) {
                        // configInfo 是变更后的完整配置内容，这里可以做自定义处理
                        log.info("检测到配置变更：{}", configInfo);
                        // 例如：重建连接池、重新加载限流规则等
                    }

                    @Override
                    public com.alibaba.nacos.api.config.listener.Executor getExecutor() {
                        return null;   // null 表示用默认线程池
                    }
                });
    }
}

<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>

@SpringBootApplication
@EnableDiscoveryClient
@EnableFeignClients(basePackages = "com.example.order.client")  // 扫描 Feign 客户端接口
public class OrderServiceApplication {
    public static void main(String[] args) {
        SpringApplication.run(OrderServiceApplication.class, args);
    }
}

package com.example.order.client;

import com.example.common.ApiResult;
import com.example.common.vo.UserVO;
import org.springframework.cloud.openfeign.FeignClient;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.PathVariable;

// name 指向注册中心里的服务名，Feign 会自动通过 Nacos 发现实例并负载均衡
@FeignClient(name = "user-service")
public interface UserClient {

    @GetMapping("/api/users/{id}")
    ApiResult<UserVO> getById(@PathVariable("id") Long id);
}

@Service
@RequiredArgsConstructor
@Slf4j
public class OrderServiceImpl implements OrderService {

    private final UserClient userClient;   // Feign 生成的代理，像本地 Bean 一样注入

    @Override
    public OrderVO getOrderDetail(Long orderId) {
        Order order = orderMapper.selectById(orderId);
        if (order == null) {
            throw new BizException(ErrorCode.ORDER_NOT_FOUND);
        }
        // 远程调用用户服务：声明式调用，代码像在调本地方法
        ApiResult<UserVO> result = userClient.getById(order.getUserId());
        if (result.getCode() != 0 || result.getData() == null) {
            throw new BizException(result.getCode(), result.getMessage());
        }
        return OrderVO.of(order, result.getData());
    }
}

@FeignClient(name = "stock-service", fallbackFactory = StockClientFallbackFactory.class)
public interface StockClient {

    // 1. @RequestBody 传 JSON 对象：参数会被序列化成 JSON 放到请求体
    @PostMapping("/api/stocks/deduct")
    ApiResult<Boolean> deduct(@RequestBody DeductStockDTO dto);

    // 2. @PathVariable 拼到 URL 路径上
    @GetMapping("/api/stocks/{productId}")
    ApiResult<StockVO> getStock(@PathVariable("productId") Long productId);

    // 3. @SpringQueryMap 把对象的字段展开成查询参数 ?a=1&b=2（适合 GET 传多参数）
    @GetMapping("/api/stocks/page")
    ApiResult<List<StockVO>> list(@SpringQueryMap StockQuery query);
}

package com.example.order.config;

import feign.RequestInterceptor;
import feign.RequestTemplate;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.web.context.request.RequestContextHolder;
import org.springframework.web.context.request.ServletRequestAttributes;

@Configuration
public class FeignHeaderConfig {

    // Feign 拦截器：在发出远程调用前，把当前请求的 X-User-Id 转发到下游
    // 这样「身份」就能穿透多层服务调用，下游无需重新鉴权
    @Bean
    public RequestInterceptor userHeaderInterceptor() {
        return template -> {
            ServletRequestAttributes attrs =
                    (ServletRequestAttributes) RequestContextHolder.getRequestAttributes();
            if (attrs == null) {
                return;
            }
            String userId = attrs.getRequest().getHeader("X-User-Id");
            if (userId != null) {
                template.header("X-User-Id", userId);
            }
        };
    }
}

package com.example.order.config;

import feign.Request;
import feign.Retryer;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;

import java.util.concurrent.TimeUnit;

@Configuration
public class FeignConfig {

    @Bean
    public Request.Options requestOptions() {
        // 连接超时 3s，读取超时 5s：比默认值更贴合「快速失败」的微服务诉求
        return new Request.Options(3, TimeUnit.SECONDS, 5, TimeUnit.SECONDS, true);
    }

    @Bean
    public Retryer retryer() {
        // Feign 默认会重试（Retryer.Default 重试 5 次），
        // 对「写操作」很危险：可能重复下单/重复扣库存，生产建议关闭重试
        return Retryer.NEVER_RETRY;
    }
}

package com.example.order.client;

import com.example.common.ApiResult;
import com.example.common.ErrorCode;
import lombok.extern.slf4j.Slf4j;
import org.springframework.cloud.openfeign.FallbackFactory;
import org.springframework.stereotype.Component;

// 降级工厂：下游 user-service 不可用时触发，返回兜底结果而不是抛异常
@Component
@Slf4j
public class UserClientFallbackFactory implements FallbackFactory<UserClient> {

    @Override
    public UserClient create(Throwable cause) {
        // cause 是真正的失败原因：超时、连接拒绝、500 等，必须记录日志便于排查
        log.error("调用 user-service 失败，触发降级", cause);
        return new UserClient() {
            @Override
            public ApiResult<UserVO> getById(Long id) {
                // 兜底：返回一个「服务不可用」的统一错误，而不是 null 或抛异常
                return ApiResult.fail(ErrorCode.SERVICE_UNAVAILABLE);
            }
        };
    }
}

@FeignClient(
    name = "user-service",
    fallbackFactory = UserClientFallbackFactory.class,   // 降级工厂
    configuration = FeignConfig.class                    // 超时、重试配置
)
public interface UserClient {

    @GetMapping("/api/users/{id}")
    ApiResult<UserVO> getById(@PathVariable("id") Long id);
}

// 在 ErrorCode 枚举中新增（基础码保持数值不变，见 5.2 节完整定义）
SERVICE_UNAVAILABLE(50301, "服务暂不可用，请稍后重试"),

logging:
  level:
    com.example.order.client.UserClient: DEBUG   # 只对某个 Feign 客户端开 DEBUG

feign:
  client:
    config:
      default:
        logger-level: FULL     # NONE/BASIC/HEADERS/FULL，FULL 最详细但性能开销大

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

predicates:
  - Path=/api/orders/**              # 按路径匹配
  - Method=GET,POST                  # 按 HTTP 方法匹配
  - Header=X-Requested-With, XMLHttpRequest   # 按请求头匹配（值是正则）
  - Query=brand, baidu               # 按查询参数匹配
  - After=2026-08-01T00:00:00+08:00  # 按时间匹配（可做活动页面定时上下线）

filters:
  - StripPrefix=1                    # 去掉第一段路径再转发（/api/orders/x -> /orders/x）
  - AddRequestHeader=X-From, gateway # 给下游加一个请求头
  - AddResponseHeader=X-Powered-By, gateway
  - RedirectTo=302, https://example.com   # 重定向
  - name: RequestRateLimiter         # 限流过滤器（见 5.5）
    args: ...

server:
  port: 8080
spring:
  application:
    name: gateway
  cloud:
    nacos:
      discovery:
        server-addr: ${NACOS_ADDR:localhost:8848}
    gateway:
      routes:
        - id: user-route
          uri: lb://user-service       # lb:// 走 Nacos 发现 + 负载均衡
          predicates:
            - Path=/api/users/**       # 路径断言：以 /api/users/ 开头的请求走这条
        - id: order-route
          uri: lb://order-service
          predicates:
            - Path=/api/orders/**
        - id: stock-route
          uri: lb://stock-service
          predicates:
            - Path=/api/stocks/**

package com.example.gateway.filter;

import lombok.extern.slf4j.Slf4j;
import org.springframework.cloud.gateway.filter.GatewayFilterChain;
import org.springframework.cloud.gateway.filter.GlobalFilter;
import org.springframework.core.Ordered;
import org.springframework.core.io.buffer.DataBuffer;
import org.springframework.http.HttpStatus;
import org.springframework.http.server.reactive.ServerHttpRequest;
import org.springframework.http.server.reactive.ServerHttpResponse;
import org.springframework.stereotype.Component;
import org.springframework.web.server.ServerWebExchange;
import reactor.core.publisher.Mono;

import java.nio.charset.StandardCharsets;

// 全局鉴权过滤器：所有请求都会经过这里
@Component
@Slf4j
public class AuthGlobalFilter implements GlobalFilter, Ordered {

    // 白名单：这些路径不需要鉴权（登录接口、健康检查、Swagger 等）
    private static final String[] WHITE_LIST = {"/api/auth/login", "/actuator", "/api/users/register"};

    @Override
    public Mono<Void> filter(ServerWebExchange exchange, GatewayFilterChain chain) {
        ServerHttpRequest request = exchange.getRequest();
        String path = request.getURI().getPath();

        // 1. 白名单直接放行
        for (String white : WHITE_LIST) {
            if (path.startsWith(white)) {
                return chain.filter(exchange);
            }
        }

        // 2. 校验 JWT，解析出可信的 userId（这里用简化版 JWT 工具，生产用阶段 5 的 JwtUtil）
        String token = request.getHeaders().getFirst("Authorization");
        Long userId = null;
        if (token != null && token.startsWith("Bearer ")) {
            userId = JwtUtil.parseUserId(token.substring(7));   // 解析失败返回 null
        }
        if (userId == null) {
            // 未登录或 token 无效：直接返回 401，不进入下游
            log.warn("鉴权失败，拒绝访问，path={}", path);
            return unauthorized(exchange);
        }

        // 3. 关键：用 JWT 解析出的 userId 覆盖请求头，防止客户端伪造 X-User-Id
        ServerHttpRequest mutated = request.mutate()
                .header("X-User-Id", String.valueOf(userId))   // 覆盖，而非追加
                .build();

        // 4. 把改写后的请求传给下游
        return chain.filter(exchange.mutate().request(mutated).build());
    }

    private Mono<Void> unauthorized(ServerWebExchange exchange) {
        ServerHttpResponse response = exchange.getResponse();
        response.setStatusCode(HttpStatus.UNAUTHORIZED);
        response.getHeaders().add("Content-Type", "application/json;charset=UTF-8");
        String body = "{"code":40101,"message":"未登录或登录已过期"}";
        DataBuffer buffer = response.bufferFactory()
                .wrap(body.getBytes(StandardCharsets.UTF_8));
        return response.writeWith(Mono.just(buffer));
    }

    // Ordered 越小优先级越高，鉴权要最先执行
    @Override
    public int getOrder() {
        return -100;
    }
}

package com.example.order.context;

// 用户上下文：从网关透传的 Header 里取 userId，存到 ThreadLocal
public class UserContext {
    private static final ThreadLocal<Long> USER_ID = new ThreadLocal<>();

    public static void setUserId(Long userId) { USER_ID.set(userId); }
    public static Long getUserId() { return USER_ID.get(); }
    public static void clear() { USER_ID.remove(); }   // 必须 remove，防止线程池复用导致串号
}

package com.example.order.interceptor;

import com.example.order.context.UserContext;
import jakarta.servlet.http.HttpServletRequest;
import jakarta.servlet.http.HttpServletResponse;
import org.springframework.stereotype.Component;
import org.springframework.web.servlet.HandlerInterceptor;

// 下游拦截器：读取网关透传的 X-User-Id，写入 ThreadLocal
@Component
public class UserContextInterceptor implements HandlerInterceptor {

    @Override
    public boolean preHandle(HttpServletRequest request, HttpServletResponse response,
                             Object handler) {
        String userId = request.getHeader("X-User-Id");
        if (userId != null) {
            UserContext.setUserId(Long.parseLong(userId));
        }
        return true;
    }

    @Override
    public void afterCompletion(HttpServletRequest request, HttpServletResponse response,
                                Object handler, Exception ex) {
        UserContext.clear();   // 请求结束必须清理，否则线程池复用会串用户
    }
}

spring:
  cloud:
    gateway:
      routes:
        - id: order-route
          uri: lb://order-service
          predicates:
            - Path=/api/orders/**
          filters:
            - name: RequestRateLimiter
              args:
                redis-rate-limiter.replenishRate: 10    # 每秒补充 10 个令牌（即 QPS=10）
                redis-rate-limiter.burstCapacity: 20     # 桶容量 20，允许突发
                key-resolver: "#{@userKeyResolver}"      # 按用户维度限流的 Key 解析器

package com.example.gateway.config;

import org.springframework.cloud.gateway.filter.ratelimit.KeyResolver;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import reactor.core.publisher.Mono;

@Configuration
public class RateLimitConfig {

    // 按用户限流：每个 userId 独立限流，而非全局限流（防止单个用户刷爆）
    @Bean
    public KeyResolver userKeyResolver() {
        return exchange -> {
            String userId = exchange.getRequest().getHeaders().getFirst("X-User-Id");
            return Mono.just(userId == null ? "anonymous" : userId);
        };
    }
}

spring:
  cloud:
    gateway:
      globalcors:
        cors-configurations:
          '[/**]':
            allowed-origins: "https://www.example.com"   # 生产填具体域名，不要用 *
            allowed-methods: "GET,POST,PUT,DELETE"
            allowed-headers: "*"
            allow-credentials: true

package com.example.gateway.filter;

import lombok.extern.slf4j.Slf4j;
import org.springframework.cloud.gateway.filter.GatewayFilterChain;
import org.springframework.cloud.gateway.filter.GlobalFilter;
import org.springframework.core.Ordered;
import org.springframework.http.server.reactive.ServerHttpRequest;
import org.springframework.stereotype.Component;
import org.springframework.web.server.ServerWebExchange;
import reactor.core.publisher.Mono;

@Component
@Slf4j
public class AccessLogFilter implements GlobalFilter, Ordered {

    @Override
    public Mono<Void> filter(ServerWebExchange exchange, GatewayFilterChain chain) {
        ServerHttpRequest request = exchange.getRequest();
        long start = System.currentTimeMillis();
        String path = request.getURI().getPath();
        String userId = request.getHeaders().getFirst("X-User-Id");

        // 请求完成后记录耗时（doFinally 无论成功失败都会执行）
        return chain.filter(exchange).doFinally(signalType -> {
            long cost = System.currentTimeMillis() - start;
            log.info("访问日志：path={}, userId={}, status={}, cost={}ms",
                    path, userId, exchange.getResponse().getStatusCode(), cost);
        });
    }

    // 日志过滤器要在鉴权之后执行（此时 X-User-Id 已就位），Ordered 值比鉴权大
    @Override
    public int getOrder() {
        return 0;
    }
}

<dependency>
    <groupId>com.alibaba.cloud</groupId>
    <artifactId>spring-cloud-starter-alibaba-sentinel</artifactId>
</dependency>
<!-- 让 @SentinelResource 的注解生效（AOP 切面） -->
<dependency>
    <groupId>com.alibaba.csp</groupId>
    <artifactId>sentinel-annotation-aspectj</artifactId>
</dependency>

spring:
  cloud:
    sentinel:
      transport:
        dashboard: ${SENTINEL_DASHBOARD:localhost:8858}   # 控制台地址
        port: 8719          # 客户端与控制台通信的本地端口
      eager: true           # 启动即注册到控制台，否则首次访问接口才出现

package com.example.stock.service;

import com.alibaba.csp.sentinel.annotation.SentinelResource;
import com.alibaba.csp.sentinel.slots.block.BlockException;
import com.example.common.ErrorCode;
import com.example.common.BizException;
import lombok.RequiredArgsConstructor;
import lombok.extern.slf4j.Slf4j;
import org.springframework.stereotype.Service;

@Service
@RequiredArgsConstructor
@Slf4j
public class StockServiceImpl implements StockService {

    // value 是资源名（限流/熔断规则的锚点），必须全局唯一
    // blockHandler 处理「限流/熔断触发」的情况，fallback 处理「业务异常」的情况
    @SentinelResource(
            value = "deductStock",
            blockHandler = "deductStockBlock",
            fallback = "deductStockFallback"
    )
    @Override
    public boolean deductStock(Long productId, Integer quantity) {
        // 模拟扣库存：库存不足抛业务异常
        int affected = stockMapper.deduct(productId, quantity);
        if (affected == 0) {
            throw new BizException(ErrorCode.STOCK_NOT_ENOUGH);
        }
        return true;
    }

    // 限流/熔断触发时走这里：参数必须与原方法一致，末尾多一个 BlockException
    public boolean deductStockBlock(Long productId, Integer quantity, BlockException e) {
        log.warn("扣库存被限流/熔断，productId={}, quantity={}", productId, quantity);
        // 降级：返回 false 表示本次扣减未执行，让上游走「库存紧张」的提示
        return false;
    }

    // 业务异常（如库存不足抛 BizException）走这里：参数一致，末尾多一个 Throwable
    public boolean deductStockFallback(Long productId, Integer quantity, Throwable t) {
        log.error("扣库存业务异常", t);
        return false;
    }
}

feign:
  sentinel:
    enabled: true   # 开启 Feign 的 Sentinel 整合

package com.example.stock.config;

import com.alibaba.csp.sentinel.slots.block.RuleConstant;
import com.alibaba.csp.sentinel.slots.block.flow.FlowRule;
import com.alibaba.csp.sentinel.slots.block.flow.FlowRuleManager;
import jakarta.annotation.PostConstruct;
import org.springframework.context.annotation.Configuration;

import java.util.ArrayList;
import java.util.List;

@Configuration
public class SentinelRuleConfig {

    @PostConstruct
    public void initFlowRules() {
        List<FlowRule> rules = new ArrayList<>();

        FlowRule rule = new FlowRule();
        rule.setResource("deductStock");        // 资源名，与 @SentinelResource 的 value 一致
        rule.setGrade(RuleConstant.FLOW_GRADE_QPS);   // 按 QPS 限流（而非线程数）
        rule.setCount(50);                      // 阈值：每秒最多 50 个请求
        rule.setControlBehavior(RuleConstant.CONTROL_BEHAVIOR_DEFAULT); // 超出直接拒绝
        rules.add(rule);

        FlowRuleManager.loadRules(rules);
    }
}

DegradeRule degradeRule = new DegradeRule();
degradeRule.setResource("getUser");
degradeRule.setGrade(CircuitBreakerStrategy.SLOW_REQUEST_RATIO.getType()); // 慢调用比例
degradeRule.setCount(0.3);              // 慢调用比例阈值 30%
degradeRule.setSlowRatioThreshold(0.5); // 调用时间超过 500ms 视为慢调用
degradeRule.setMinRequestAmount(10);    // 最少 10 个请求才开始统计
degradeRule.setStatIntervalMs(10000);   // 统计窗口 10s
degradeRule.setTimeWindow(30);          // 熔断打开 30s 后进入半开状态试探
DegradeRuleManager.loadRules(List.of(degradeRule));

<dependency>
    <groupId>com.alibaba.csp</groupId>
    <artifactId>sentinel-datasource-nacos</artifactId>
</dependency>

spring:
  cloud:
    sentinel:
      datasource:
        flow:                             # 数据源名称，可自定义
          nacos:
            server-addr: ${NACOS_ADDR:localhost:8848}
            namespace: dev
            group-id: DEFAULT_GROUP
            data-id: ${spring.application.name}-flow-rules   # 规则文件 DataId
            data-type: json
            rule-type: flow               # 规则类型：flow/degrade/system/authority/param-flow
        degrade:
          nacos:
            server-addr: ${NACOS_ADDR:localhost:8848}
            namespace: dev
            group-id: DEFAULT_GROUP
            data-id: ${spring.application.name}-degrade-rules
            data-type: json
            rule-type: degrade

[
  {
    "resource": "deductStock",
    "grade": 1,
    "count": 50,
    "controlBehavior": 0,
    "clusterMode": false
  }
]

import com.alibaba.csp.sentinel.slots.block.flow.param.ParamFlowRule;
import com.alibaba.csp.sentinel.slots.block.flow.param.ParamFlowRuleManager;

// 热点参数限流规则
ParamFlowRule rule = new ParamFlowRule("deductStock")
        .setParamIdx(0)             // 针对第 0 个参数（productId）
        .setCount(10);              // 该参数值的 QPS 阈值
// 针对特定值单独设阈值：productId=1001 只允许 5 QPS
rule.setParamFlowItemList(java.util.List.of(
        new ParamFlowItem().setObject("1001").setClassType(long.class.getName()).setCount(5)
));
ParamFlowRuleManager.loadRules(java.util.List.of(rule));

import com.alibaba.csp.sentinel.slots.system.SystemRule;
import com.alibaba.csp.sentinel.slots.system.SystemRuleManager;

SystemRule rule = new SystemRule();
rule.setHighestSystemLoad(4.0);      // 系统 load 超过 4.0 时触发保护
rule.setHighestCpuUsage(0.8);        // CPU 使用率超过 80% 时触发
rule.setAvgRt(500);                  // 平均 RT 超过 500ms 时触发
rule.setMaxThread(200);              // 并发线程超过 200 时触发
SystemRuleManager.loadRules(java.util.List.of(rule));

# 1. 下载并启动 SkyWalking（OAP + UI 一体，默认 8080 是 UI，11800 是 gRPC 采集端口）
wget https://archive.apache.org/dist/skywalking/9.7.0/apache-skywalking-apm-9.7.0.tar.gz
tar -zxvf apache-skywalking-apm-9.7.0.tar.gz
cd apache-skywalking-apm-bin/bin
sh oapService.sh        # 启动 OAP 采集服务
sh webappService.sh     # 启动 UI，访问 http://localhost:8080

# 2. 启动业务服务时挂 Agent
java -javaagent:/path/to/skywalking-agent/skywalking-agent.jar 
     -Dskywalking.agent.service_name=order-service 
     -Dskywalking.collector.backend_service=localhost:11800 
     -jar order-service.jar

<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-actuator</artifactId>
</dependency>
<dependency>
    <groupId>io.micrometer</groupId>
    <artifactId>micrometer-tracing-bridge-brave</artifactId>
</dependency>
<dependency>
    <groupId>io.zipkin.reporter2</groupId>
    <artifactId>zipkin-reporter-brave</artifactId>
</dependency>

management:
  tracing:
    sampling:
      probability: 1.0        # 采样率，生产建议 0.1~0.5，避免海量数据
  zipkin:
    tracing:
      endpoint: http://localhost:9411/api/v2/spans   # Zipkin 上报地址

package com.example.common.trace;

import org.slf4j.MDC;

// TraceId 工具：从 MDC 取，取不到就生成一个，保证每处日志都能关联
public class TraceContext {

    public static final String TRACE_ID_KEY = "traceId";

    public static String getTraceId() {
        String traceId = MDC.get(TRACE_ID_KEY);
        return traceId == null ? "N/A" : traceId;
    }

    public static void setTraceId(String traceId) {
        MDC.put(TRACE_ID_KEY, traceId);
    }

    public static void clear() {
        MDC.remove(TRACE_ID_KEY);
    }
}

logging:
  pattern:
    console: "%d{yyyy-MM-dd HH:mm:ss.SSS} [%thread] %-5level [%X{traceId}] %logger{50} - %msg%n"

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

package com.example.order.service;

import java.util.Map;

import io.seata.spring.annotation.GlobalTransactional;
import lombok.RequiredArgsConstructor;
import lombok.extern.slf4j.Slf4j;
import org.springframework.stereotype.Service;

@Service
@RequiredArgsConstructor
@Slf4j
public class OrderServiceImpl implements OrderService {

    private final StockClient stockClient;

    // @GlobalTransactional：把「本地事务」升级为「全局事务」
    // 该方法内所有远程调用参与的服务，都纳入同一个分布式事务
    @GlobalTransactional(name = "create-order", rollbackFor = Exception.class)
    @Override
    public Long createOrder(CreateOrderDTO dto) {
        // 1. 本地事务：插入订单
        Order order = insertOrder(dto);
        // 2. 远程调用：扣库存（stock-service 内部执行自己的本地事务，受 TC 协调）
        ApiResult<Boolean> result = stockClient.deductStock(Map.of("productId", dto.getProductId(), "quantity", dto.getQuantity()));
        if (result.getCode() != 0 || !Boolean.TRUE.equals(result.getData())) {
            // 抛异常会触发全局回滚：订单插入会被回滚，库存扣减也会被回滚
            throw new BizException(ErrorCode.STOCK_NOT_ENOUGH);
        }
        return order.getId();
    }
}

seata:
  registry:
    type: nacos
    nacos:
      server-addr: ${NACOS_ADDR:localhost:8848}
      namespace: dev
      group: SEATA_GROUP        # 事务分组，与服务端 tc 配置对应
  config:
    type: nacos
    nacos:
      server-addr: ${NACOS_ADDR:localhost:8848}
      namespace: dev
      group: SEATA_GROUP

-- 业务执行的 SQL
UPDATE t_stock SET available = available - 2 WHERE product_id = 1001;

-- Seata 自动写入的回滚日志（示意）
INSERT INTO undo_log (branch_id, xid, before_image, after_image, ...) VALUES (
  123, '192.168.1.10:8091:202608141200001',
  '{"available":100}',      -- before_image：变更前
  '{"available":98}'        -- after_image：变更后
);

-- 反向 SQL：把 available 改回 100
UPDATE t_stock SET available = 100 WHERE product_id = 1001;

public interface StockTccService {

    // Try：预留资源（冻结库存，不真正扣减）
    boolean tryFreeze(Long productId, Integer quantity);

    // Confirm：确认提交（真正扣减之前冻结的量）
    boolean confirmFreeze(Long productId, Integer quantity);

    // Cancel：取消（释放之前冻结的量）
    boolean cancelFreeze(Long productId, Integer quantity);
}

@Service
@RequiredArgsConstructor
@Slf4j
public class OrderServiceImpl {

    private final OrderMapper orderMapper;
    private final LocalMsgMapper localMsgMapper;

    // 本地事务：订单和消息同库写入，保证「有订单必有消息」
    @Transactional
    public Long createOrder(CreateOrderDTO dto) {
        Order order = buildOrder(dto);
        orderMapper.insert(order);

        // 写入本地消息表，状态=待发送
        LocalMsg msg = new LocalMsg();
        msg.setMsgId(UUID.randomUUID().toString());
        msg.setTopic("stock-deduct");
        msg.setPayload(JSON.toJSONString(dto));   // 扣库存的消息体
        msg.setStatus(0);                          // 0=待发送
        localMsgMapper.insert(msg);

        return order.getId();
    }
}

// 定时任务：扫描「待发送」消息投递到 MQ，投递成功改状态
@Scheduled(fixedDelay = 5000)
public void sendLocalMsg() {
    List<LocalMsg> msgs = localMsgMapper.selectByStatus(0);   // 查待发送
    for (LocalMsg msg : msgs) {
        try {
            rocketMQTemplate.syncSend(msg.getTopic(), msg.getPayload());
            msg.setStatus(1);                       // 1=已发送
            localMsgMapper.updateById(msg);
        } catch (Exception e) {
            log.error("消息投递失败，msgId={}，稍后重试", msg.getMsgId(), e);
            // 失败不更新状态，下次定时任务继续重试
        }
    }
}

<?xml version="1.0" encoding="UTF-8"?>
<project xmlns="http://maven.apache.org/POM/4.0.0"
         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
    <modelVersion>4.0.0</modelVersion>

    <parent>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-parent</artifactId>
        <version>3.2.5</version>
        <relativePath/>
    </parent>

    <groupId>com.example</groupId>
    <artifactId>microservice-demo</artifactId>
    <version>1.0.0</version>
    <packaging>pom</packaging>

    <modules>
        <module>common</module>
        <module>user-service</module>
        <module>order-service</module>
        <module>stock-service</module>
        <module>gateway</module>
    </modules>

    <properties>
        <java.version>17</java.version>
        <spring-cloud.version>2023.0.1</spring-cloud.version>
        <spring-cloud-alibaba.version>2023.0.1.0</spring-cloud-alibaba.version>
        <mybatis-plus.version>3.5.7</mybatis-plus.version>
    </properties>

    <dependencyManagement>
        <dependencies>
            <dependency>
                <groupId>org.springframework.cloud</groupId>
                <artifactId>spring-cloud-dependencies</artifactId>
                <version>${spring-cloud.version}</version>
                <type>pom</type>
                <scope>import</scope>
            </dependency>
            <dependency>
                <groupId>com.alibaba.cloud</groupId>
                <artifactId>spring-cloud-alibaba-dependencies</artifactId>
                <version>${spring-cloud-alibaba.version}</version>
                <type>pom</type>
                <scope>import</scope>
            </dependency>
            <dependency>
                <groupId>com.baomidou</groupId>
                <artifactId>mybatis-plus-spring-boot3-starter</artifactId>
                <version>${mybatis-plus.version}</version>
            </dependency>
        </dependencies>
    </dependencyManagement>
</project>

import lombok.Data;
import org.slf4j.MDC;

@Data
public class ApiResult<T> {
    private int code;        // 0=成功，非 0=错误码
    private String message;  // 提示信息
    private T data;          // 业务数据
    private String traceId;  // 链路追踪 id

    public static <T> ApiResult<T> ok(T data) {
        ApiResult<T> r = new ApiResult<>();
        r.setCode(ErrorCode.SUCCESS.getCode());
        r.setMessage(ErrorCode.SUCCESS.getMessage());
        r.setData(data);
        r.setTraceId(MDC.get("traceId"));
        return r;
    }
    public static <T> ApiResult<T> ok() {
        return ok(null);
    }
    public static <T> ApiResult<T> fail(int code, String message) {
        ApiResult<T> r = new ApiResult<>();
        r.setCode(code);
        r.setMessage(message);
        r.setTraceId(MDC.get("traceId"));
        return r;
    }
    public static <T> ApiResult<T> fail(ErrorCode ec) {
        return fail(ec.getCode(), ec.getMessage());
    }
}

package com.example.common;

public enum ErrorCode {
    SUCCESS(0, "success"),
    PARAM_ERROR(40001, "参数错误"),
    UNAUTHORIZED(40101, "未登录或登录已过期"),
    FORBIDDEN(40301, "无权限访问"),
    USER_NOT_FOUND(40401, "用户不存在"),
    ORDER_NOT_FOUND(40403, "订单不存在"),
    STOCK_NOT_ENOUGH(50002, "库存不足"),
    SERVICE_UNAVAILABLE(50301, "服务暂不可用，请稍后重试"),
    SYSTEM_ERROR(50000, "系统繁忙，请稍后重试"),
    ;

    private final int code;
    private final String message;

    ErrorCode(int code, String message) {
        this.code = code;
        this.message = message;
    }

    public int getCode() { return code; }
    public String getMessage() { return message; }
}

package com.example.common;

// 统一业务异常：业务代码里主动抛它，全局异常处理器统一转成 ApiResult
public class BizException extends RuntimeException {
    private final int code;

    public BizException(ErrorCode ec) {
        super(ec.getMessage());
        this.code = ec.getCode();
    }

    public BizException(int code, String message) {
        super(message);
        this.code = code;
    }

    public int getCode() { return code; }
}