// ❌ 反例 - 裸调用，没有任何保护
@Service
public class OrderService {
    
    @Autowired
    private UserFeignClient userClient;
    
    public OrderDTO getOrder(Long orderId) {
        Order order = orderMapper.selectById(orderId);
        // 如果 user-service 挂了，这里就卡死
        User user = userClient.getUser(order.getUserId());
        return buildOrderDTO(order, user);
    }
}

// ✅ 正例 - 完整的容错保护

// 1. Feign 客户端配置超时
@FeignClient(
    name = "user-service",
    fallbackFactory = UserClientFallbackFactory.class
)
public interface UserFeignClient {
    
    @GetMapping("/users/{id}")
    User getUser(@PathVariable Long id);
}

// 2. 降级工厂（推荐用 Factory，可以拿到异常信息）
@Component
public class UserClientFallbackFactory implements FallbackFactory<UserFeignClient> {
    
    @Override
    public UserFeignClient create(Throwable cause) {
        return new UserFeignClient() {
            @Override
            public User getUser(Long id) {
                // 记录日志，返回兜底数据
                log.warn("调用 user-service 失败，降级处理: {}", cause.getMessage());
                return User.unknown(id);
            }
        };
    }
}

// 3. 全局超时配置 (application.yml)
// feign:
//   client:
//     config:
//       default:
//         connectTimeout: 2000
//         readTimeout: 5000
//   circuitbreaker:
//     enabled: true

// 4. 熔断器配置（Resilience4j）
// resilience4j:
//   circuitbreaker:
//     instances:
//       user-service:
//         failureRateThreshold: 50
//         waitDurationInOpenState: 30s
//         slidingWindowSize: 10

// ❌ 反例 - 非幂等接口开启重试
@FeignClient(name = "payment-service")
public interface PaymentClient {
    
    // 这个接口不幂等，重试会重复扣款！
    @PostMapping("/pay")
    @Retryable(maxAttempts = 3)  // 危险！
    PayResult pay(PayRequest request);
}

// ✅ 正例 - 通过幂等 Token 保证幂等

// 1. 请求中带幂等 Token
@Data
public class PayRequest {
    private String idempotentKey;  // 幂等键，如：订单号+支付类型
    private Long orderId;
    private BigDecimal amount;
}

// 2. 服务端幂等校验
@Service
public class PaymentService {
    
    @Autowired
    private StringRedisTemplate redis;
    
    public PayResult pay(PayRequest request) {
        String key = "pay:idempotent:" + request.getIdempotentKey();
        
        // 幂等校验：已处理过就直接返回
        Boolean isNew = redis.opsForValue()
            .setIfAbsent(key, "1", Duration.ofHours(24));
        
        if (Boolean.FALSE.equals(isNew)) {
            // 已经处理过，查询结果返回
            return getExistingResult(request.getIdempotentKey());
        }
        
        try {
            // 执行真正的支付逻辑
            return doPayment(request);
        } catch (Exception e) {
            // 失败时删除幂等键，允许重试
            redis.delete(key);
            throw e;
        }
    }
}

// 3. 安全的重试配置
@Configuration
public class RetryConfig {
    
    @Bean
    public Retryer feignRetryer() {
        // 只对 GET 请求重试，POST/PUT/DELETE 不重试
        return new Retryer.Default(100, 1000, 3);
    }
}

project-root/
├── project-common/              # 基础工具
│   ├── src/main/java/
│   │   ├── exception/           # 统一异常
│   │   ├── result/              # 统一响应
│   │   ├── utils/               # 工具类
│   │   └── constants/           # 常量
│   └── pom.xml
│
├── project-api/                 # 共享契约
│   ├── user-api/                # 用户服务 API
│   │   ├── dto/
│   │   ├── vo/
│   │   └── enums/
│   └── order-api/               # 订单服务 API
│
├── project-client/              # Feign 客户端
│   ├── user-client/
│   └── order-client/
│
├── project-starter/             # 自定义 Starter
│   ├── sms-starter/             # 短信组件
│   ├── oss-starter/             # 对象存储组件
│   └── log-starter/             # 日志组件
│
├── user-service/                # 用户服务
├── order-service/               # 订单服务
└── pom.xml

// ✅ project-common 中定义统一响应

@Data
@AllArgsConstructor
@NoArgsConstructor
public class Result<T> {
    
    private int code;
    private String message;
    private T data;
    private long timestamp = System.currentTimeMillis();
    
    public static <T> Result<T> success(T data) {
        return new Result<>(200, "success", data, System.currentTimeMillis());
    }
    
    public static <T> Result<T> fail(int code, String message) {
        return new Result<>(code, message, null, System.currentTimeMillis());
    }
    
    public static <T> Result<T> fail(ErrorCode errorCode) {
        return new Result<>(errorCode.getCode(), errorCode.getMessage(), null, System.currentTimeMillis());
    }
    
    public boolean isSuccess() {
        return this.code == 200;
    }
}

// ✅ 业务异常定义
public class BusinessException extends RuntimeException {
    
    private final int code;
    
    public BusinessException(ErrorCode errorCode) {
        super(errorCode.getMessage());
        this.code = errorCode.getCode();
    }
    
    public BusinessException(int code, String message) {
        super(message);
        this.code = code;
    }
}

// ✅ 全局异常处理器（每个服务引入即可）
@RestControllerAdvice
public class GlobalExceptionHandler {
    
    @ExceptionHandler(BusinessException.class)
    public Result<?> handleBusinessException(BusinessException e) {
        log.warn("业务异常: {}", e.getMessage());
        return Result.fail(e.getCode(), e.getMessage());
    }
    
    @ExceptionHandler(MethodArgumentNotValidException.class)
    public Result<?> handleValidationException(MethodArgumentNotValidException e) {
        String msg = e.getBindingResult().getFieldErrors().stream()
            .map(err -> err.getField() + ": " + err.getDefaultMessage())
            .collect(Collectors.joining("; "));
        return Result.fail(400, msg);
    }
    
    @ExceptionHandler(Exception.class)
    public Result<?> handleException(Exception e) {
        log.error("系统异常", e);
        return Result.fail(500, "系统繁忙，请稍后重试");
    }
}

// 1. 自动配置类
@Configuration
@ConditionalOnClass(SmsClient.class)
@EnableConfigurationProperties(SmsProperties.class)
public class SmsAutoConfiguration {
    
    @Bean
    @ConditionalOnMissingBean
    @ConditionalOnProperty(prefix = "sms", name = "enabled", havingValue = "true", matchIfMissing = true)
    public SmsClient smsClient(SmsProperties properties) {
        return new SmsClient(properties);
    }
    
    @Bean
    @ConditionalOnMissingBean
    public SmsTemplate smsTemplate(SmsClient smsClient) {
        return new SmsTemplate(smsClient);
    }
}

// 2. 配置属性类
@Data
@ConfigurationProperties(prefix = "sms")
public class SmsProperties {
    
    private boolean enabled = true;
    private String accessKey;
    private String secretKey;
    private String signName;
    private String templateCode;
}

// 3. 模板类（对外暴露的 API）
public class SmsTemplate {
    
    private final SmsClient smsClient;
    
    public SmsTemplate(SmsClient smsClient) {
        this.smsClient = smsClient;
    }
    
    public void sendVerifyCode(String phone, String code) {
        Map<String, String> params = Map.of("code", code);
        smsClient.send(phone, params);
    }
}

// 4. spring.factories（Spring Boot 2.x）或 AutoConfiguration.imports（Spring Boot 3.x）
// resources/META-INF/spring/org.springframework.boot.autoconfigure.AutoConfiguration.imports
// com.example.sms.SmsAutoConfiguration

# application.yml
sms:
  enabled: true
  access-key: xxx
  secret-key: xxx
  sign-name: 我的应用

// 直接注入使用
@Service
public class UserService {
    
    @Autowired
    private SmsTemplate smsTemplate;
    
    public void sendVerifyCode(String phone) {
        String code = RandomUtil.randomNumbers(6);
        smsTemplate.sendVerifyCode(phone, code);
    }
}

// ✅ 基于消息队列的最终一致性

// 1. 订单服务：创建订单 + 发消息
@Service
public class OrderService {
    
    @Autowired
    private RocketMQTemplate rocketMQTemplate;
    
    @Transactional
    public void createOrder(OrderDTO dto) {
        // 创建订单（本地事务）
        Order order = new Order();
        order.setStatus(OrderStatus.PENDING_PAYMENT);
        orderMapper.insert(order);
        
        // 发送消息通知库存服务扣减库存
        // 使用事务消息保证消息一定发送成功
        rocketMQTemplate.sendMessageInTransaction(
            "order-topic",
            MessageBuilder.withPayload(new StockDeductMessage(order.getId(), dto.getItems()))
                .build(),
            order
        );
    }
}

// 2. 库存服务：消费消息扣减库存
@Component
@RocketMQMessageListener(topic = "order-topic", consumerGroup = "stock-consumer")
public class StockDeductListener implements RocketMQListener<StockDeductMessage> {
    
    @Override
    public void onMessage(StockDeductMessage message) {
        // 幂等校验
        if (stockRecordMapper.exists(message.getOrderId())) {
            return;
        }
        
        // 扣减库存
        for (OrderItem item : message.getItems()) {
            int rows = stockMapper.deduct(item.getSkuId(), item.getQuantity());
            if (rows == 0) {
                // 库存不足，发送补偿消息
                throw new BusinessException("库存不足");
            }
        }
        
        // 记录已处理
        stockRecordMapper.insert(new StockRecord(message.getOrderId()));
    }
}

// ✅ 本地消息表：消息和业务数据在同一个事务

@Service
public class OrderService {
    
    @Transactional
    public void createOrder(OrderDTO dto) {
        // 1. 创建订单
        Order order = new Order();
        orderMapper.insert(order);
        
        // 2. 写入本地消息表（同一个事务）
        LocalMessage message = new LocalMessage();
        message.setTopic("stock-deduct");
        message.setPayload(JSON.toJSONString(new StockDeductMessage(order.getId())));
        message.setStatus(MessageStatus.PENDING);
        localMessageMapper.insert(message);
    }
}

// 3. 定时任务扫描发送
@Scheduled(fixedRate = 5000)
public void sendPendingMessages() {
    List<LocalMessage> messages = localMessageMapper.selectPending();
    for (LocalMessage msg : messages) {
        try {
            rocketMQTemplate.syncSend(msg.getTopic(), msg.getPayload());
            msg.setStatus(MessageStatus.SENT);
        } catch (Exception e) {
            msg.setRetryCount(msg.getRetryCount() + 1);
        }
        localMessageMapper.updateById(msg);
    }
}

// ❌ 反例 - 硬编码配置
@Service
public class PaymentService {
    
    // 写死的配置，改动需要重新发版
    private static final String PAY_URL = "https://api.payment.com/pay";
    private static final int MAX_RETRY = 3;
    private static final boolean ENABLE_LOG = true;
}

// ✅ 正例 - 配置外部化 + 动态刷新

@Data
@Component
@RefreshScope  // 支持动态刷新
@ConfigurationProperties(prefix = "payment")
public class PaymentProperties {
    
    private String payUrl;
    private int maxRetry = 3;
    private boolean enableLog = true;
    private BigDecimal maxAmount = new BigDecimal("50000");
}

@Service
public class PaymentService {
    
    @Autowired
    private PaymentProperties properties;
    
    public void pay(PayRequest request) {
        if (request.getAmount().compareTo(properties.getMaxAmount()) > 0) {
            throw new BusinessException("超过单笔限额");
        }
        // 使用配置的 URL
        httpClient.post(properties.getPayUrl(), request);
    }
}

// ✅ 使用 MDC 传递 traceId

// 1. 过滤器设置 traceId
@Component
public class TraceFilter implements Filter {
    
    @Override
    public void doFilter(ServletRequest request, ServletResponse response, FilterChain chain) 
            throws IOException, ServletException {
        try {
            String traceId = Optional.ofNullable(((HttpServletRequest) request).getHeader("X-Trace-Id"))
                .orElse(UUID.randomUUID().toString().replace("-", ""));
            MDC.put("traceId", traceId);
            chain.doFilter(request, response);
        } finally {
            MDC.clear();
        }
    }
}

// 2. logback 配置
// <pattern>%d{yyyy-MM-dd HH:mm:ss.SSS} [%thread] [%X{traceId}] %-5level %logger{36} - %msg%n</pattern>

// 3. Feign 拦截器传递 traceId
@Component
public class FeignTraceInterceptor implements RequestInterceptor {
    
    @Override
    public void apply(RequestTemplate template) {
        String traceId = MDC.get("traceId");
        if (traceId != null) {
            template.header("X-Trace-Id", traceId);
        }
    }
}

// ✅ 正确的日志打印

@Slf4j
@RestController
public class OrderController {
    
    @PostMapping("/orders")
    public Result<OrderVO> createOrder(@Valid @RequestBody OrderDTO dto) {
        // 入口日志
        log.info("创建订单请求: userId={}, productId={}, quantity={}", 
            dto.getUserId(), dto.getProductId(), dto.getQuantity());
        
        try {
            OrderVO result = orderService.createOrder(dto);
            // 成功日志
            log.info("创建订单成功: orderId={}", result.getOrderId());
            return Result.success(result);
        } catch (BusinessException e) {
            // 业务异常，warn 级别
            log.warn("创建订单失败: {}", e.getMessage());
            throw e;
        } catch (Exception e) {
            // 系统异常，error 级别，打印堆栈
            log.error("创建订单异常: userId={}", dto.getUserId(), e);
            throw e;
        }
    }
}

// ✅ 使用 Sentinel 限流

// 1. 注解方式
@SentinelResource(
    value = "createOrder",
    blockHandler = "createOrderBlockHandler",
    fallback = "createOrderFallback"
)
public Result<OrderVO> createOrder(OrderDTO dto) {
    return orderService.createOrder(dto);
}

// 限流后的处理
public Result<OrderVO> createOrderBlockHandler(OrderDTO dto, BlockException e) {
    return Result.fail(429, "请求过于频繁，请稍后重试");
}

// 2. 配置限流规则（可通过 Sentinel Dashboard 动态配置）
@PostConstruct
public void initFlowRules() {
    List<FlowRule> rules = new ArrayList<>();
    FlowRule rule = new FlowRule();
    rule.setResource("createOrder");
    rule.setGrade(RuleConstant.FLOW_GRADE_QPS);
    rule.setCount(100);  // QPS 限制 100
    rules.add(rule);
    FlowRuleManager.loadRules(rules);
}

// ✅ 基于 Redis 的防重提交

@Aspect
@Component
public class IdempotentAspect {
    
    @Autowired
    private StringRedisTemplate redis;
    
    @Around("@annotation(idempotent)")
    public Object around(ProceedingJoinPoint point, Idempotent idempotent) throws Throwable {
        HttpServletRequest request = getRequest();
        String token = request.getHeader("Idempotent-Token");
        
        if (StringUtils.isBlank(token)) {
            throw new BusinessException("缺少幂等 Token");
        }
        
        String key = "idempotent:" + token;
        Boolean success = redis.opsForValue().setIfAbsent(key, "1", Duration.ofSeconds(idempotent.expire()));
        
        if (Boolean.FALSE.equals(success)) {
            throw new BusinessException("请勿重复提交");
        }
        
        try {
            return point.proceed();
        } catch (Exception e) {
            // 失败时删除 key，允许重试
            redis.delete(key);
            throw e;
        }
    }
}

// 使用注解
@Idempotent(expire = 10)
@PostMapping("/orders")
public Result<OrderVO> createOrder(@RequestBody OrderDTO dto) {
    return orderService.createOrder(dto);
}