微服务开发工作流

Claude Code 工作流专题 · 分布式系统的高效开发

专题：Claude Code 工作流系统学习

关键词：Claude Code, 微服务, DDD, gRPC, Kafka, 服务网格, Saga, API网关, 契约测试

一、微服务架构概述

微服务架构是一种将单个应用程序划分为一组小服务的架构风格，每个服务运行在自己的进程中，并通过轻量级通信机制（通常是HTTP/REST或消息队列）相互协作。与传统的单体架构不同，微服务围绕业务能力组织，可以由不同的团队使用不同的技术栈独立开发、测试和部署。在Claude Code的辅助下，微服务开发的工作流可以大幅提升效率，从服务拆分到部署上线的全链路均可获得AI驱动的智能建议。

核心原则：单一职责（每个服务只负责一个业务领域）、自治性（独立部署和扩展）、去中心化（数据存储和治理分散）、弹性设计（故障隔离而非级联）、可观测性（监控和日志完备）。

微服务并非银弹。在决定采用微服务架构前，需要评估项目的复杂度、团队规模和组织结构。康威定律指出，系统的架构会反映组织的沟通结构。因此，微服务的拆分不仅是一个技术决策，也是组织架构的映射。使用Claude Code的Agent模式可以让AI助手理解整个代码库的依赖关系图，辅助识别合理的服务边界。

【架构示意图：单体架构 vs 微服务架构对比】

二、服务拆分

服务拆分是微服务架构中最重要的环节，也是最具挑战性的任务。错误的拆分会导致服务间高度耦合、分布式单体（Distributed Monolith）等反模式。以下从六个维度深入讲解服务拆分的方法论。

2.1 领域驱动设计（DDD）

Eric Evans提出的领域驱动设计是服务拆分的主要理论工具。DDD强调以业务领域为核心，通过统一语言（Ubiquitous Language）消除技术与业务之间的鸿沟。在Claude Code中，我们可以通过提示词工程让AI分析业务描述，自动识别核心领域和子域。

DDD的核心战术模式包括：实体（Entity）、值对象（Value Object）、聚合（Aggregate）、领域服务（Domain Service）、领域事件（Domain Event）、仓储（Repository）和工厂（Factory）。通过这些模式，可以将复杂的业务逻辑内聚在限界上下文内部。

2.2 限界上下文（Bounded Context）

限界上下文是DDD中最关键的概念，它定义了领域模型的边界。每个限界上下文内部有独立的领域模型和统一语言，上下文之间通过上下文映射（Context Map）进行集成。常见的上下文映射关系包括：合作关系（Partnership）、共享内核（Shared Kernel）、客户-供应商（Customer-Supplier）、防腐层（Anti-Corruption Layer）、开放主机服务（Open Host Service）和发布语言（Published Language）。

// 使用 Claude Code 识别限界上下文的提示词模板
// 请分析以下业务描述，识别出核心域、支撑域和通用域，
// 并给出每个限界上下文名称及其职责描述：

业务描述："
我们的电商平台需要支持用户注册登录、商品浏览、
购物车管理、下单支付、物流追踪、评价系统和后台管理。
支持多商户入驻，每个商户管理自己的商品、库存和订单。
需要对订单进行风控审核，对异常交易进行标记。
"

// Claude Code 分析结果示例：
// - 用户上下文（核心域）：用户注册、认证、权限管理
// - 商品上下文（核心域）：商品目录、库存、价格
// - 订单上下文（核心域）：订单创建、状态流转
// - 支付上下文（支撑域）：支付网关对接、退款
// - 物流上下文（通用域）：配送、追踪
// - 商户上下文（核心域）：商户入驻、店铺管理
// - 风控上下文（支撑域）：交易审核、异常检测

2.3 服务粒度

服务粒度的确定是拆分过程中最困难的部分。粒度太细会导致服务数量爆炸，增加运维复杂度和延迟；粒度太粗又无法获得微服务架构的独立部署和扩展优势。经验法则是：一个服务应该可以在不与其他服务协调的情况下被独立修改和部署。

粒度级别	特征	适用场景
粗粒度	包含多个子域，功能完整	早期迁移、团队较小
中粒度	每个限界上下文对应一个服务	大多数项目推荐
细粒度	一个聚合根对应一个服务	超大规模、团队成熟

2.4 拆分策略

常见的拆分策略分为三大类：按业务能力拆分、按子域拆分和按变化频率拆分。按业务能力拆分关注系统对外提供的功能（如用户管理、订单管理），按子域拆分关注业务内在的领域逻辑，按变化频率拆分（也称为绞杀者模式）关注业务变更的节奏。实践中通常混合使用多种策略。

Claude Code 实践建议：使用Claude Code的"探索-分析-生成"工作流，先让AI读取项目中的实体类、控制器和仓储接口，自动生成依赖关系图，然后基于依赖强度和业务相关性给出服务拆分建议。

2.5 单体拆解（Strangler Fig）

单体应用向微服务的迁移通常采用绞杀者模式（Strangler Fig Pattern），这是一种渐进式的重构策略。基本思路是：在单体应用外围构建新的微服务，通过路由层逐步将旧功能替换到新服务上，最终绞杀掉单体中的旧代码。

// 绞杀者模式实现示例 - 路由代理层

// 第一步：在单体前添加路由代理
// 新功能请求转发到微服务，旧功能继续走单体

public class StranglerRouterFilter implements Filter {

    private static final Map<String, String> ROUTE_TABLE = new HashMap<>() {{
        put("/api/users/**", "http://user-service");
        put("/api/products/**", "http://product-service");
        // 旧功能仍指向单体
        put("/api/orders/**", "http://legacy-monolith");
    }};

    @Override
    public void doFilter(ServletRequest request, ServletResponse response,
                         FilterChain chain) {
        HttpServletRequest req = (HttpServletRequest) request;
        String path = req.getRequestURI();
        String target = ROUTE_TABLE.entrySet().stream()
            .filter(e -> pathMatches(e.getKey(), path))
            .map(Map.Entry::getValue)
            .findFirst()
            .orElse("http://legacy-monolith");

        // 转发到目标服务
        forwardRequest(target, req, response);
    }
}

// 第二步：逐步将单体功能迁移到微服务
// 每完成一个功能的迁移，更新路由表指向新服务
// 第三步：当所有功能都迁移完成后，下线单体应用

三、服务间通信

服务间通信是微服务架构的血脉。选择合适的通信方式直接影响系统的性能、可用性和数据一致性。服务间通信分为同步通信和异步通信两大类，每种方式有各自的适用场景和取舍。

3.1 REST

REST（Representational State Transfer）是微服务中最常用的同步通信协议。它基于HTTP协议，使用资源作为抽象，通过标准HTTP方法（GET/POST/PUT/DELETE）操作资源。REST的优点是简单直观、生态成熟、易于调试，但缺点是序列化开销较大，不适合高频低延迟场景。

// Spring Boot REST 服务示例 - 订单服务接口

@RestController
@RequestMapping("/api/v1/orders")
public class OrderController {

    @Autowired
    private OrderService orderService;

    @PostMapping
    public ResponseEntity<OrderResponse> createOrder(
            @Valid @RequestBody CreateOrderRequest request) {
        OrderResponse response = orderService.createOrder(request);
        return ResponseEntity.status(HttpStatus.CREATED).body(response);
    }

    @GetMapping("/{orderId}")
    public ResponseEntity<OrderResponse> getOrder(
            @PathVariable String orderId) {
        return orderService.findOrder(orderId)
            .map(ResponseEntity::ok)
            .orElse(ResponseEntity.notFound().build());
    }

    @PutMapping("/{orderId}/status")
    public ResponseEntity<Void> updateOrderStatus(
            @PathVariable String orderId,
            @RequestParam OrderStatus status) {
        orderService.updateStatus(orderId, status);
        return ResponseEntity.ok().build();
    }
}

3.2 gRPC

gRPC是Google开源的高性能RPC框架，基于HTTP/2协议和Protocol Buffers序列化协议。相比REST，gRPC具有更高的性能和更低的延迟，支持双向流、流量控制和头部压缩。gRPC特别适合内部服务间的高频通信，但浏览器端支持有限，需要通过gRPC-Web或Envoy代理。

// 使用 Protocol Buffers 定义 gRPC 接口
// file: order.proto

syntax = "proto3";

package order.v1;

option go_package = "order/v1;orderv1";

service OrderService {
    rpc CreateOrder(CreateOrderRequest) returns (OrderResponse);
    rpc GetOrder(GetOrderRequest) returns (OrderResponse);
    rpc ListOrders(ListOrdersRequest) returns (ListOrdersResponse);
    rpc StreamOrderUpdates(StreamRequest) returns (stream OrderEvent);
}

message CreateOrderRequest {
    string user_id = 1;
    repeated OrderItem items = 2;
    string shipping_address = 3;
    string coupon_id = 4;
}

message OrderItem {
    string product_id = 1;
    int32 quantity = 2;
    double unit_price = 3;
}

message OrderResponse {
    string order_id = 1;
    string status = 2;
    double total_amount = 3;
    repeated OrderItem items = 4;
    string created_at = 5;
}

3.3 消息队列与事件驱动

消息队列是异步通信的核心组件，能够解耦服务间的直接依赖，提供削峰填谷、故障隔离和最终一致性保障。事件的发布者不需要知道谁在消费事件，领域事件（Domain Event）和事件溯源（Event Sourcing）是微服务中事件驱动的两种主要模式。

RabbitMQ

RabbitMQ是基于AMQP协议的消息中间件，支持多种交换器类型（Direct、Topic、Fanout、Headers）。它适合需要灵活路由和低延迟的场景。RabbitMQ的消息确认机制（ACK）和死信队列（DLQ）为可靠消费提供了保障。

// Spring AMQP + RabbitMQ 发布订阅示例

@Configuration
public class RabbitMQConfig {

    @Bean
    public TopicExchange orderExchange() {
        return new TopicExchange("order.topic");
    }

    @Bean
    public Queue paymentQueue() {
        return QueueBuilder.durable("payment.order.queue")
            .withArgument("x-dead-letter-exchange", "dlx.exchange")
            .build();
    }

    @Bean
    public Binding paymentBinding() {
        return BindingBuilder.bind(paymentQueue())
            .to(orderExchange())
            .with("order.created.#");
    }
}

// 事件发布
@Service
public class OrderEventPublisher {

    @Autowired
    private RabbitTemplate rabbitTemplate;

    public void publishOrderCreated(OrderCreatedEvent event) {
        rabbitTemplate.convertAndSend(
            "order.topic",
            "order.created." + event.orderId(),
            event
        );
    }
}

// 事件消费
@Component
public class PaymentConsumer {

    @RabbitListener(queues = "payment.order.queue")
    public void handleOrderCreated(OrderCreatedEvent event) {
        // 处理支付逻辑
        log.info("Received order created event: {}", event.orderId());
        paymentService.processPayment(event);
    }
}

Apache Kafka

Apache Kafka是一个分布式流处理平台，专为高吞吐量、持久化和可重放的消息场景设计。Kafka采用分区（Partition）和日志（Log）模型，每个分区内的消息是有序且不可变的。Kafka的消费者组（Consumer Group）机制允许多个消费者并行消费同一主题，且每个分区只能被组内的一个消费者消费。

// Spring Kafka 事件驱动架构示例

@Configuration
public class KafkaConfig {

    @Bean
    public ProducerFactory<String, Object> producerFactory() {
        Map<String, Object> props = new HashMap<>();
        props.put(ProducerConfig.BOOTSTRAP_SERVERS_CONFIG, "localhost:9092");
        props.put(ProducerConfig.KEY_SERIALIZER_CLASS_CONFIG,
            StringSerializer.class);
        props.put(ProducerConfig.VALUE_SERIALIZER_CLASS_CONFIG,
            JsonSerializer.class);
        // 开启幂等生产者
        props.put(ProducerConfig.ENABLE_IDEMPOTENCE_CONFIG, true);
        // 设置acks为all确保最强持久性
        props.put(ProducerConfig.ACKS_CONFIG, "all");
        return new DefaultKafkaProducerFactory<>(props);
    }

    @Bean
    public KafkaTemplate<String, Object> kafkaTemplate() {
        return new KafkaTemplate<>(producerFactory());
    }
}

// 事件源 - 订单服务
@Service
public class OrderEventSourcingService {

    @Autowired
    private KafkaTemplate<String, Object> kafkaTemplate;

    @Transactional
    public Order createOrder(CreateOrderRequest request) {
        Order order = orderRepository.save(
            Order.newOrder(request.getUserId(), request.getItems()));

        // 将领域事件写入事件流
        OrderCreatedEvent event = OrderCreatedEvent.builder()
            .eventId(UUID.randomUUID().toString())
            .orderId(order.getId())
            .userId(order.getUserId())
            .items(order.getItems())
            .totalAmount(order.getTotalAmount())
            .timestamp(Instant.now())
            .build();

        kafkaTemplate.send("order.events", order.getId(), event);
        return order;
    }
}

// 事件消费者 - 库存服务
@Component
public class InventoryEventConsumer {

    @KafkaListener(topics = "order.events",
        groupId = "inventory-service",
        containerFactory = "kafkaListenerContainerFactory")
    public void consumeOrderEvent(OrderCreatedEvent event,
            @Header(KafkaHeaders.RECEIVED_KEY) String key) {
        log.info("Processing inventory reservation for order: {}", key);
        inventoryService.reserveInventory(event.getItems());
    }
}

3.4 服务发现

在微服务架构中，服务实例的IP和端口是动态变化的（特别是容器化部署时），因此需要服务发现机制来解决"如何找到目标服务"的问题。服务发现分为客户端发现和服务端发现两种模式。

// Netflix Eureka 服务注册与发现示例

// 服务端 - Eureka Server
@SpringBootApplication
@EnableEurekaServer
public class DiscoveryServiceApplication {
    public static void main(String[] args) {
        SpringApplication.run(DiscoveryServiceApplication.class, args);
    }
}

// 客户端 - 服务提供者注册到 Eureka
@SpringBootApplication
@EnableEurekaClient
public class OrderServiceApplication {

    public static void main(String[] args) {
        SpringApplication.run(OrderServiceApplication.class, args);
    }
}

// application.yml 配置
// eureka:
//   client:
//     serviceUrl:
//       defaultZone: http://localhost:8761/eureka/
//   instance:
//     preferIpAddress: true
//     leaseRenewalIntervalInSeconds: 10

// 客户端负载均衡 - 使用 Spring Cloud LoadBalancer
@Service
public class OrderClient {

    @Autowired
    @LoadBalanced
    private RestTemplate restTemplate;

    public UserInfo getUserInfo(String userId) {
        // 直接使用服务名调用，LoadBalancer自动解析
        String url = "http://user-service/api/v1/users/" + userId;
        return restTemplate.getForObject(url, UserInfo.class);
    }
}

3.5 客户端负载均衡

客户端负载均衡是指服务消费者在本地维护一份服务实例列表，并通过负载均衡算法（轮询、加权随机、最少连接、一致性哈希等）选择一个实例发起调用。相比服务端负载均衡，客户端负载均衡避免了额外的网络跳转，延迟更低。

// Spring Cloud LoadBalancer 自定义负载均衡策略

public class ConsistentHashLoadBalancer implements ReactorServiceInstanceLoadBalancer {

    private final String serviceId;
    private final ObjectProvider<ServiceInstanceListSupplier> supplierProvider;

    public ConsistentHashLoadBalancer(
            String serviceId,
            ObjectProvider<ServiceInstanceListSupplier> supplierProvider) {
        this.serviceId = serviceId;
        this.supplierProvider = supplierProvider;
    }

    @Override
    public Mono<Response<ServiceInstance>> choose(Request request) {
        ServiceInstanceListSupplier supplier = supplierProvider.getIfAvailable();
        return supplier.get().next().map(instances -> {
            if (instances.isEmpty()) {
                return Response.error(null);
            }
            // 基于请求中的 userId 做一致性哈希
            String userId = extractUserId(request);
            int hash = Math.abs(userId.hashCode());
            int index = hash % instances.size();
            return Response.ok(instances.get(index));
        });
    }

    private String extractUserId(Request request) {
        if (request instanceof RequestDataContext ctx) {
            return ctx.getClientRequest().getHeaders()
                .getFirst("X-User-Id");
        }
        return "default";
    }
}

四、API网关

API网关是微服务架构中所有客户端请求的统一入口，承担着路由转发、请求限流、身份鉴权、协议转换、响应聚合和熔断降级等横切关注点。API网关将客户端与后端服务解耦，使得微服务的内部变更对客户端透明。

4.1 路由

路由是API网关最基础的功能，根据请求的URL路径、Header或参数将请求转发到对应的微服务。Spring Cloud Gateway基于WebFlux的响应式编程模型，性能优于传统的Zuul 1.x。

// Spring Cloud Gateway 路由配置示例

@Bean
public RouteLocator customRouteLocator(RouteLocatorBuilder builder) {
    return builder.routes()
        .route("user-service", r -> r
            .path("/api/v1/users/**")
            .filters(f -> f
                .stripPrefix(1)
                .retry(3)
                .circuitBreaker(config -> config
                    .setName("userServiceCB")
                    .setFallbackUri("forward:/fallback/user")))
            .uri("lb://user-service"))

        .route("order-service", r -> r
            .path("/api/v1/orders/**")
            .and().method("GET", "POST")
            .filters(f -> f
                .stripPrefix(1)
                .requestRateLimiter(config -> config
                    .setRateLimiter(redisRateLimiter())
                    .setKeyResolver(userKeyResolver())))
            .uri("lb://order-service"))

        .route("product-service", r -> r
            .path("/api/v1/products/**")
            .filters(f -> f
                .stripPrefix(1)
                .addRequestHeader("X-Gateway-Request", "true"))
            .uri("lb://product-service"))
        .build();
}

4.2 限流

限流是保护后端服务不被突发流量打垮的关键手段。常见的限流算法包括：令牌桶（Token Bucket）、漏桶（Leaky Bucket）、滑动窗口（Sliding Window）和计数器。实践中推荐使用令牌桶算法配合Redis分布式计数器，兼顾精度和性能。

// 基于 Redis 的分布式限流器

@Component
public class RedisRateLimiter {

    @Autowired
    private StringRedisTemplate redisTemplate;

    // Lua 脚本实现令牌桶算法（原子操作）
    private static final String LUA_SCRIPT = """
        local key = KEYS[1]
        local capacity = tonumber(ARGV[1])
        local refillRate = tonumber(ARGV[2])
        local now = tonumber(ARGV[3])
        local tokens = redis.call('hget', key, 'tokens')
        local lastRefill = redis.call('hget', key, 'lastRefill')
        if tokens == false then
            tokens = capacity
            lastRefill = now
        else
            tokens = tonumber(tokens)
            lastRefill = tonumber(lastRefill)
            local elapsed = now - lastRefill
            local refill = elapsed * refillRate
            tokens = math.min(capacity, tokens + refill)
            lastRefill = now
        end
        if tokens >= 1 then
            redis.call('hset', key, 'tokens', tokens - 1)
            redis.call('hset', key, 'lastRefill', lastRefill)
            return 1
        else
            return 0
        end
        """;

    public boolean tryAcquire(String key, int capacity, double refillRate) {
        DefaultRedisScript<Long> script = new DefaultRedisScript<>();
        script.setScriptText(LUA_SCRIPT);
        script.setResultType(Long.class);
        Long result = redisTemplate.execute(script,
            List.of("rate_limiter:" + key),
            String.valueOf(capacity),
            String.valueOf(refillRate),
            String.valueOf(System.currentTimeMillis() / 1000));
        return result != null && result == 1;
    }
}

4.3 鉴权与协议转换

API网关统一处理JWT令牌验证、OAuth2.0授权码流程、API Key校验等鉴权逻辑，避免每个服务重复实现认证逻辑。同时，网关可以在客户端协议（如HTTP/1.1 WebSocket）和后端服务协议（如gRPC）之间做协议转换。

// Spring Cloud Gateway 全局鉴权过滤器

@Component
public class AuthenticationGatewayFilterFactory
        extends AbstractGatewayFilterFactory<AuthenticationGatewayFilterFactory.Config> {

    public AuthenticationGatewayFilterFactory() {
        super(Config.class);
    }

    @Override
    public GatewayFilter apply(Config config) {
        return (exchange, chain) -> {
            ServerHttpRequest request = exchange.getRequest();
            String path = request.getURI().getPath();

            // 跳过不需要认证的路径
            if (config.skipPaths.stream().anyMatch(path::startsWith)) {
                return chain.filter(exchange);
            }

            // 提取并验证 JWT 令牌
            String authHeader = request.getHeaders()
                .getFirst(HttpHeaders.AUTHORIZATION);
            if (authHeader == null || !authHeader.startsWith("Bearer ")) {
                return unauthorized(exchange, "Missing token");
            }

            try {
                String token = authHeader.substring(7);
                JwtClaims claims = jwtValidator.validateToken(token);

                // 将用户信息注入请求头，传递到下游服务
                ServerHttpRequest mutatedRequest = request.mutate()
                    .header("X-User-Id", claims.getSubject())
                    .header("X-User-Roles",
                        String.join(",", claims.get("roles")))
                    .build();
                return chain.filter(
                    exchange.mutate().request(mutatedRequest).build());
            } catch (JwtException e) {
                return unauthorized(exchange, "Invalid token");
            }
        };
    }

    private Mono<Void> unauthorized(ServerWebExchange exchange, String msg) {
        exchange.getResponse().setStatusCode(HttpStatus.UNAUTHORIZED);
        return exchange.getResponse()
            .writeWith(Mono.just(exchange.getResponse()
                .bufferFactory().wrap(msg.getBytes())));
    }
}

4.4 熔断降级

熔断器模式（Circuit Breaker）是微服务中防止级联故障的最后一层防线。当对下游服务的调用持续失败达到阈值时，熔断器打开（Open），后续请求直接返回降级响应，避免线程池耗尽。经过冷却时间后，熔断器进入半开状态（Half-Open），允许少量请求通过以检测服务是否恢复。

// Resilience4j 熔断器配置与使用

// application.yml 配置
// resilience4j.circuitbreaker:
//   instances:
//     paymentService:
//       slidingWindowSize: 10        # 滑动窗口大小
//       minimumNumberOfCalls: 5      # 最小调用次数
//       failureRateThreshold: 50     # 失败率阈值(%)
//       waitDurationInOpenState: 30s # 打开状态持续时间
//       permittedNumberOfCallsInHalfOpenState: 3
//       automaticTransitionFromOpenToHalfOpenEnabled: true

@Service
@CircuitBreaker(name = "paymentService", fallbackMethod = "fallbackPay")
public class PaymentService {

    @Autowired
    private PaymentClient paymentClient;

    public PaymentResult processPayment(PaymentRequest request) {
        return paymentClient.charge(request);
    }

    // 熔断降级方法（参数要和原方法一致，加上异常参数）
    public PaymentResult fallbackPay(PaymentRequest request,
            Exception ex) {
        log.warn("Payment service unavailable, fallback triggered: {}",
            ex.getMessage());
        // 降级策略：将支付请求存入待处理队列，后续重试
        pendingPaymentQueue.enqueue(request);
        return PaymentResult.pending(request.getOrderId(),
            "支付服务暂时不可用，已排队处理");
    }
}

// 结合时间限流器（Bulkhead）限制并发数
@Bulkhead(name = "paymentService", type = Bulkhead.Type.SEMAPHORE)
@RateLimiter(name = "paymentService")
public PaymentResult safeProcessPayment(PaymentRequest request) {
    return processPayment(request);
}

五、服务治理

服务治理是微服务架构中保障系统稳定运行的基础设施，包括注册中心、配置中心、链路追踪、日志聚合、健康检查和服务网格等技术组件。

5.1 注册中心

注册中心是服务发现的核心组件，维护着所有可用服务实例的动态列表。主流注册中心包括：Eureka（AP模型，最终一致性）、Consul（CP模型，强一致性）、Nacos（支持AP和CP切换）、Zookeeper（CP模型，基于ZAB协议）。

5.2 配置中心

配置中心统一管理微服务的配置信息，支持配置的热更新和环境隔离。Spring Cloud Config、Nacos Config和Consul Config是Java生态中最常用的配置中心方案。

// Nacos 配置中心动态刷新示例

@Component
@RefreshScope  // 配置变更时自动刷新Bean
public class OrderConfig {

    @Value("${order.max-retry-count:3}")
    private int maxRetryCount;

    @Value("${order.payment-timeout-ms:5000}")
    private int paymentTimeoutMs;

    @Value("${order.free-shipping-threshold:99.0}")
    private double freeShippingThreshold;

    // 监听配置变更事件
    @EventListener
    public void handleEvent(NacosConfigReceivedEvent event) {
        log.info("Configuration refreshed: {}", event.getContent());
        log.info("New maxRetryCount: {}, paymentTimeout: {}ms",
            maxRetryCount, paymentTimeoutMs);
    }
}

// Nacos 配置数据 ID: order-service.properties
// order.max-retry-count=5
// order.payment-timeout-ms=8000
// order.free-shipping-threshold=49.0

5.3 链路追踪

在微服务架构中，一个请求可能跨越数十个服务，分布式链路追踪（Distributed Tracing）能够还原请求的完整调用链路。OpenTelemetry是CNCF的标准化可观测性框架，集成了日志、指标和追踪三大信号。

// OpenTelemetry 分布式链路追踪配置

@Configuration
public class TelemetryConfig {

    @Bean
    public OpenTelemetry openTelemetry() {
        return OpenTelemetrySdk.builder()
            .setTracerProvider(
                SdkTracerProvider.builder()
                    .addSpanProcessor(
                        BatchSpanProcessor.builder(
                            OtlpGrpcSpanExporter.builder()
                                .setEndpoint("http://jaeger:4317")
                                .build())
                        .build())
                    .setResource(Resource.getDefault()
                        .toBuilder()
                        .put(ResourceAttributes.SERVICE_NAME, "order-service")
                        .put(ResourceAttributes.DEPLOYMENT_ENVIRONMENT, "production")
                        .build())
                    .build())
            .build();
    }

    @Bean
    public RestTemplate restTemplate(RestTemplateBuilder builder) {
        return builder
            .additionalInterceptors((request, body, execution) -> {
                // 自动注入追踪上下文到HTTP头
                Span currentSpan = Span.current();
                request.getHeaders().add("traceparent",
                    "00-" + currentSpan.getSpanContext().getTraceId()
                        + "-" + currentSpan.getSpanContext().getSpanId()
                        + "-01");
                return execution.execute(request, body);
            })
            .build();
    }
}

// 在业务代码中手动创建Span
@Service
public class OrderProcessingService {

    @Autowired
    private OpenTelemetry openTelemetry;

    public OrderResult processOrder(String orderId) {
        Tracer tracer = openTelemetry.getTracer("order-service");
        Span span = tracer.spanBuilder("processOrder")
            .setAttribute("order.id", orderId)
            .setAttribute("order.type", getOrderType(orderId))
            .startSpan();

        try (Scope scope = span.makeCurrent()) {
            // 业务逻辑
            validateOrder(orderId);
            reserveInventory(orderId);
            processPayment(orderId);
            return buildResult(orderId);
        } catch (Exception e) {
            span.recordException(e)
                .setStatus(StatusCode.ERROR, e.getMessage());
            throw e;
        } finally {
            span.end();
        }
    }
}

5.4 日志聚合

微服务日志分散在成百上千个容器中，需要集中式日志管理平台（ELK/EFK Stack）进行聚合分析。推荐结构化日志格式（JSON），便于按TraceID、ServiceName等字段进行检索。

// Logback + ELK 结构化日志配置

<!-- logback-spring.xml -->
<configuration>
    <appender name="JSON" class="ch.qos.logback.core.ConsoleAppender">
        <encoder class="net.logstash.logback.encoder.LogstashEncoder">
            <includeContext>false</includeContext>
            <customFields>{"service":"order-service","env":"${ENV:-dev"}}</customFields>
        </encoder>
    </appender>

    <!-- MDC 自动注入 TraceID -->
    <appender name="ASYNC_JSON" class="ch.qos.logback.classic.AsyncAppender">
        <appender-ref ref="JSON"/>
        <queueSize>512</queueSize>
        <discardingThreshold>0</discardingThreshold>
    </appender>

    <root level="INFO">
        <appender-ref ref="ASYNC_JSON"/>
    </root>
</configuration>

// Java 代码中使用 MDC 注入追踪信息
@Component
public class TracingFilter implements Filter {
    @Override
    public void doFilter(ServletRequest request,
            ServletResponse response, FilterChain chain) {
        try {
            String traceId = extractTraceId(request);
            String spanId = UUID.randomUUID().toString().substring(0, 8);
            MDC.put("traceId", traceId);
            MDC.put("spanId", spanId);
            MDC.put("userId", extractUserId(request));
            chain.doFilter(request, response);
        } finally {
            MDC.clear();
        }
    }
}

5.5 健康检查

健康检查是服务治理的基础能力，用于判断服务实例是否正常运行。Kubernetes提供了两种探针：存活探针（Liveness Probe）用于判断是否需要重启容器，就绪探针（Readiness Probe）用于判断服务是否已准备好接收流量。

// Spring Boot Actuator 健康检查 + 自定义指标

@Component
public class DatabaseHealthIndicator implements HealthIndicator {

    @Autowired
    private DataSource dataSource;

    @Override
    public Health health() {
        try (Connection conn = dataSource.getConnection()) {
            if (conn.isValid(3)) {
                return Health.up()
                    .withDetail("database", "available")
                    .withDetail("latencyMs", measureLatency(conn))
                    .build();
            } else {
                return Health.down()
                    .withDetail("database", "connection validation failed")
                    .build();
            }
        } catch (Exception e) {
            return Health.down(e).build();
        }
    }
}

// Kubernetes 探针配置
// apiVersion: v1
// kind: Pod
// spec:
//   containers:
//   - name: order-service
//     livenessProbe:
//       httpGet:
//         path: /actuator/health/liveness
//         port: 8080
//       initialDelaySeconds: 30
//       periodSeconds: 10
//       failureThreshold: 3
//     readinessProbe:
//       httpGet:
//         path: /actuator/health/readiness
//         port: 8080
//       initialDelaySeconds: 5
//       periodSeconds: 5
//       failureThreshold: 2

5.6 服务网格（Istio）

服务网格（Service Mesh）将服务间通信的逻辑从应用代码中抽离出来，下沉到基础设施层。Istio是目前最流行的服务网格实现，基于Envoy代理以Sidecar模式注入到每个Pod中，提供流量管理、安全策略和可观测性能力。

// Istio 流量管理配置示例

// VirtualService - 流量路由和灰度发布
// apiVersion: networking.istio.io/v1beta1
// kind: VirtualService
// metadata:
//   name: order-service-routing
// spec:
//   hosts:
//   - order-service
//   http:
//   - match:
//     - headers:
//         X-Version:
//           exact: v2
//     route:
//     - destination:
//         host: order-service
//         subset: v2
//       weight: 100
//   - route:
//     - destination:
//         host: order-service
//         subset: v1
//       weight: 90
//     - destination:
//         host: order-service
//         subset: v2
//       weight: 10

// DestinationRule - 服务版本和负载均衡策略
// apiVersion: networking.istio.io/v1beta1
// kind: DestinationRule
// metadata:
//   name: order-service-destination
// spec:
//   host: order-service
//   trafficPolicy:
//     loadBalancer:
//       consistentHash:
//         httpHeaderName: X-User-Id
//     connectionPool:
//       tcp:
//         maxConnections: 100
//       http:
//         http1MaxPendingRequests: 50
//         maxRetries: 3
//   subsets:
//   - name: v1
//     labels:
//       version: v1
//   - name: v2
//     labels:
//       version: v2

// 故障注入 - 测试弹性
// apiVersion: networking.istio.io/v1beta1
// kind: VirtualService
// metadata:
//   name: order-service-fault-injection
// spec:
//   hosts:
//   - order-service
//   http:
//   - fault:
//       delay:
//         percentage:
//           value: 10.0
//         fixedDelay: 5s
//       abort:
//         percentage:
//           value: 1.0
//         httpStatus: 500
//     route:
//     - destination:
//         host: order-service

六、分布式事务

分布式事务是微服务架构中最棘手的问题之一。在跨多个服务的操作中保证数据一致性，需要在一致性、可用性和分区容忍性之间做出权衡。以下是几种主流的分布式事务解决方案。

6.1 Saga模式

Saga模式将长事务拆分为一系列本地事务，每个本地事务完成后发布事件触发下一个本地事务。如果某个步骤失败，Saga会执行补偿事务（Compensating Transaction）来撤销之前已完成的步骤。Saga分为编排（Choreography）和协调（Orchestration）两种实现方式。

// Saga 协调器模式（Orchestration）实现

// 订单创建 Saga 定义
@Component
public class CreateOrderSaga {

    @Autowired
    private SagaOrchestrator orchestrator;

    public void execute(CreateOrderRequest request) {
        orchestrator.begin("create-order-saga", request)
            .step("validate-inventory")
                .invoke(() -> inventoryService.validate(request))
                .withCompensation(() -> inventoryService.release(request))
            .step("reserve-payment")
                .invoke(() -> paymentService.reserve(request))
                .withCompensation(() ->
                    paymentService.cancelReservation(request))
            .step("create-shipment")
                .invoke(() -> shippingService.create(request))
                .withCompensation(() ->
                    shippingService.cancel(request))
            .step("confirm-order")
                .invoke(() -> orderService.confirm(request))
            // .withCompensation 不需要补偿，订单确认是最终状态
            .build()
            .execute();
    }
}

// Saga 执行引擎核心
@Component
public class SagaOrchestrator {

    @Autowired
    private SagaStateRepository stateRepository;
    @Autowired
    private ApplicationEventPublisher eventPublisher;

    public SagaBuilder begin(String sagaName, Object payload) {
        return new SagaBuilder(this);
    }

    @Transactional
    public void executeStep(SagaContext context, SagaStep step) {
        try {
            step.getInvoke().run();
            context.markStepCompleted(step.getId());
            stateRepository.save(context);
            eventPublisher.publishEvent(
                new StepCompletedEvent(context, step));
        } catch (Exception e) {
            log.error("Saga step failed: {}", step.getId(), e);
            context.markStepFailed(step.getId(), e);
            stateRepository.save(context);
            compensate(context);
            throw new SagaException("Saga execution failed at step: "
                + step.getId(), e);
        }
    }

    @Transactional
    public void compensate(SagaContext context) {
        List<SagaStep> completedSteps = context.getCompletedSteps();
        Collections.reverse(completedSteps);
        for (SagaStep step : completedSteps) {
            try {
                step.getCompensation().run();
                context.markCompensated(step.getId());
            } catch (Exception e) {
                log.error("Compensation failed for step: {}",
                    step.getId(), e);
                // 记录到死信队列，人工介入
                deadLetterQueue.enqueue(
                    new CompensationFailure(context, step, e));
            }
        }
        stateRepository.save(context);
    }
}

6.2 两阶段提交（2PC）

两阶段提交是传统的分布式事务协议，分为准备阶段（Prepare）和提交阶段（Commit）。在准备阶段，协调者询问所有参与者是否可以提交；如果所有参与者都回复Yes，协调者发出Commit指令。2PC提供了强一致性，但存在协调者单点故障和阻塞问题，不适合高并发场景。

6.3 TCC模式

TCC（Try-Confirm-Cancel）是补偿型分布式事务的一种实现，将每个服务的操作分为三个阶段：Try（预留资源）、Confirm（确认执行）和Cancel（取消回滚）。TCC需要在业务层面设计资源预留逻辑，对业务的侵入性较强，但性能优于2PC。

// TCC 模式实现示例

// 账户服务 TCC 接口
public interface AccountTccService {

    @TwoPhaseBusinessAction(name = "transfer", commitMethod = "confirm", rollbackMethod = "cancel")
    boolean tryTransfer(TccActionContext context,
                        @BusinessActionContextParameter(paramName = "fromAccount") String fromAccount,
                        @BusinessActionContextParameter(paramName = "toAccount") String toAccount,
                        @BusinessActionContextParameter(paramName = "amount") BigDecimal amount);

    boolean confirm(TccActionContext context);

    boolean cancel(TccActionContext context);
}

// TCC 实现类
@Service
@Slf4j
public class AccountTccServiceImpl implements AccountTccService {

    @Autowired
    private AccountRepository accountRepository;
    @Autowired
    private FrozenRecordRepository frozenRepository;

    @Override
    @Transactional
    public boolean tryTransfer(TccActionContext context,
            String fromAccount, String toAccount, BigDecimal amount) {
        log.info("TCC try: freeze {} from account {}", amount, fromAccount);
        Account account = accountRepository.findById(fromAccount)
            .orElseThrow(() -> new RuntimeException("Account not found"));

        // 检查余额是否充足
        if (account.getAvailableBalance().compareTo(amount) < 0) {
            throw new InsufficientBalanceException("余额不足");
        }

        // 冻结资金（预留资源）
        account.setFrozenBalance(account.getFrozenBalance().add(amount));
        accountRepository.save(account);

        // 记录冻结记录便于补偿
        frozenRepository.save(new FrozenRecord(
            context.getXid(), fromAccount, amount, "FROZEN"));
        return true;
    }

    @Override
    @Transactional
    public boolean confirm(TccActionContext context) {
        String fromAccount = (String) context.getActionContext("fromAccount");
        String toAccount = (String) context.getActionContext("toAccount");
        BigDecimal amount = (BigDecimal) context.getActionContext("amount");

        log.info("TCC confirm: transfer {} from {} to {}", amount, fromAccount, toAccount);

        // 扣减源账户冻结金额
        Account source = accountRepository.findById(fromAccount).orElseThrow();
        source.setFrozenBalance(source.getFrozenBalance().subtract(amount));
        source.setBalance(source.getBalance().subtract(amount));
        accountRepository.save(source);

        // 增加目标账户余额
        Account target = accountRepository.findById(toAccount).orElseThrow();
        target.setBalance(target.getBalance().add(amount));
        accountRepository.save(target);

        frozenRepository.updateStatus(context.getXid(), "CONFIRMED");
        return true;
    }

    @Override
    @Transactional
    public boolean cancel(TccActionContext context) {
        String fromAccount = (String) context.getActionContext("fromAccount");
        BigDecimal amount = (BigDecimal) context.getActionContext("amount");

        log.info("TCC cancel: unfreeze {} from account {}", amount, fromAccount);

        // 解冻资金
        Account account = accountRepository.findById(fromAccount).orElseThrow();
        account.setFrozenBalance(account.getFrozenBalance().subtract(amount));
        accountRepository.save(account);

        frozenRepository.updateStatus(context.getXid(), "CANCELLED");
        return true;
    }
}

6.4 事件溯源与最终一致性

事件溯源（Event Sourcing）是一种以事件序列作为系统状态持久化方式的数据存储模式。在微服务中，事件溯源天然支持最终一致性：每个服务维护自己的事件流，通过重放事件可以重建任意时刻的状态。结合消息队列的可靠投递和幂等消费，可以实现不依赖分布式事务协调器的最终一致性方案。

// 基于事件的最终一致性实现

// 幂等消费处理器
@Component
public class IdempotentMessageHandler {

    @Autowired
    private IdempotentRepository idempotentRepository;

    @Transactional
    public <T> void handle(String messageId, T event,
                           Consumer<T> consumer) {
        // 幂等检查：防止重复消费
        if (idempotentRepository.existsById(messageId)) {
            log.info("Duplicate message ignored: {}", messageId);
            return;
        }

        try {
            consumer.accept(event);
            idempotentRepository.save(
                new IdempotentRecord(messageId, Instant.now()));
        } catch (Exception e) {
            log.error("Failed to handle event: {}", messageId, e);
            // 重试队列
            throw new RetryableException(e);
        }
    }
}

// 出站适配器 - 确保"至少一次"投递
@Component
public class OutboxPublisher {

    @Autowired
    private OutboxRepository outboxRepository;
    @Autowired
    private KafkaTemplate<String, Object> kafkaTemplate;

    @Transactional
    public void publish(String aggregateId, Object event) {
        // 将事件写入发件箱表（与业务操作在同一事务中）
        OutboxMessage outbox = new OutboxMessage(
            UUID.randomUUID().toString(),
            aggregateId,
            event.getClass().getTypeName(),
            JsonUtils.toJson(event),
            "PENDING",
            Instant.now());
        outboxRepository.save(outbox);
    }

    // 定时任务：轮询发件箱并发送到消息队列
    @Scheduled(fixedDelay = 1000)
    @Transactional
    public void pollOutbox() {
        List<OutboxMessage> pending = outboxRepository
            .findTop100ByStatusOrderByCreatedAt("PENDING");

        for (OutboxMessage msg : pending) {
            try {
                kafkaTemplate.send(msg.getTopic(),
                    msg.getAggregateId(), msg.getPayload());
                msg.setStatus("SENT");
                msg.setSentAt(Instant.now());
                outboxRepository.save(msg);
            } catch (Exception e) {
                log.error("Failed to send outbox message: {}",
                    msg.getId(), e);
            }
        }
    }
}

6.5 补偿事务

补偿事务是Saga模式中用于撤销已提交操作的逆操作。设计补偿事务时需要遵循幂等性和交换律原则：补偿操作可以被安全地多次执行，且补偿操作的执行顺序应与正向操作的顺序相反。补偿操作应当是语义层面的回滚，而非数据库层面的回滚。

重要提醒：补偿事务无法100%保证数据一致。在某些边界情况下（如第三方支付已扣款但补偿失败），需要人工介入。因此补偿事务设计必须包含告警和人工处理机制。

七、微服务CI/CD

微服务的独立部署能力是其核心价值之一。相比单体应用的单一发布流程，微服务的CI/CD涉及多服务流水线协调、依赖部署顺序管理和复杂的发布策略。

7.1 独立部署与多服务流水线

每个微服务应有独立的CI/CD流水线，包含构建、单元测试、静态分析、容器镜像构建和部署等阶段。多服务流水线的核心挑战是服务间的依赖关系管理：当底层的库或共享接口变更时，如何协调上游服务的重新部署。

// .gitlab-ci.yml - 微服务独立部署流水线

stages:
  - build
  - test
  - security-scan
  - image-build
  - deploy-staging
  - integration-test
  - deploy-production

variables:
  DOCKER_REGISTRY: registry.example.com
  SERVICE_NAME: order-service
  K8S_NAMESPACE: production

build:
  stage: build
  image: maven:3.9-eclipse-temurin-17
  script:
    - mvn clean compile -DskipTests
  artifacts:
    paths:
      - target/classes/
    expire_in: 1 hour

unit-test:
  stage: test
  image: maven:3.9-eclipse-temurin-17
  script:
    - mvn test jacoco:report
    - mvn verify -Pintegration-test
  artifacts:
    reports:
      junit: target/surefire-reports/TEST-*.xml
    paths:
      - target/jacoco-report/
    expire_in: 30 days

image-build:
  stage: image-build
  image: docker:24
  services:
    - docker:24-dind
  script:
    - docker build -t ${DOCKER_REGISTRY}/${SERVICE_NAME}:${CI_COMMIT_SHA} .
    - docker tag ${DOCKER_REGISTRY}/${SERVICE_NAME}:${CI_COMMIT_SHA}
          ${DOCKER_REGISTRY}/${SERVICE_NAME}:latest
    - docker push ${DOCKER_REGISTRY}/${SERVICE_NAME}:${CI_COMMIT_SHA}

deploy-staging:
  stage: deploy-staging
  image: bitnami/kubectl:latest
  script:
    - kubectl set image deployment/${SERVICE_NAME}
          ${SERVICE_NAME}=${DOCKER_REGISTRY}/${SERVICE_NAME}:${CI_COMMIT_SHA}
          -n staging
  environment:
    name: staging
  needs:
    - image-build

integration-test:
  stage: integration-test
  script:
    - chmod +x run-integration-tests.sh
    - ./run-integration-tests.sh
  needs:
    - deploy-staging

deploy-production:
  stage: deploy-production
  image: bitnami/kubectl:latest
  script:
    - kubectl set image deployment/${SERVICE_NAME}
          ${SERVICE_NAME}=${DOCKER_REGISTRY}/${SERVICE_NAME}:${CI_COMMIT_SHA}
          -n production
  environment:
    name: production
  needs:
    - integration-test
  when: manual  # 生产部署需要手动确认
  rules:
    - if: '$CI_COMMIT_BRANCH == "main"'

7.2 蓝绿部署与金丝雀发布

蓝绿部署（Blue-Green Deployment）维护两套完全相同的环境（蓝环境和绿环境），通过切换流量入口完成版本升级。金丝雀发布（Canary Release）则逐步将少量用户流量导向新版本，在监控确认无异常后逐渐扩大流量比例。两者都支持快速回滚。

// Kubernetes + Istio 金丝雀发布配置

// Deployment - 金丝雀版本（v2）
// apiVersion: apps/v1
// kind: Deployment
// metadata:
//   name: order-service-v2
//   labels:
//     app: order-service
//     version: v2
// spec:
//   replicas: 2
//   selector:
//     matchLabels:
//       app: order-service
//       version: v2
//   template:
//     metadata:
//       labels:
//         app: order-service
//         version: v2
//     spec:
//       containers:
//       - name: order-service
//         image: registry.example.com/order-service:2.0.0
//         ports:
//         - containerPort: 8080
//         readinessProbe:
//           httpGet:
//             path: /actuator/health/readiness
//             port: 8080
//           initialDelaySeconds: 10
//           periodSeconds: 5

// Istio VirtualService - 金丝雀流量切分
// apiVersion: networking.istio.io/v1beta1
// kind: VirtualService
// metadata:
//   name: order-service-canary
// spec:
//   hosts:
//   - order-service
//   http:
//   - match:
//     - headers:
//         X-Canary:
//           exact: "true"          # 内部测试流量全部到v2
//     route:
//     - destination:
//         host: order-service
//         subset: v2
//       weight: 100
//   - route:
//     - destination:
//         host: order-service
//         subset: v1
//       weight: 95                # 95%流量到旧版本
//     - destination:
//         host: order-service
//         subset: v2
//       weight: 5                 # 5%流量到新版本

// 金丝雀发布脚本 - 渐进式流量调整
// stage1: 5% 流量 - 观察15分钟
// istioctl create -f canary-5percent.yaml
// sleep 900
// stage2: 20% 流量 - 观察30分钟
// istioctl apply -f canary-20percent.yaml
// sleep 1800
// stage3: 50% 流量 - 观察1小时
// istioctl apply -f canary-50percent.yaml
// sleep 3600
// stage4: 100% 流量 - 完成发布
// istioctl apply -f canary-100percent.yaml

7.3 回滚协调

在微服务架构中，回滚不是一个简单的git revert操作。因为多个服务可能同时发布，回滚时需要协调各服务的版本一致性，同时考虑数据库schema的向前兼容性。建议在每次发布前执行schema变更的兼容性检查，并记录每轮发布的版本映射表。

// 数据库迁移向前兼容示例

// Flyway 迁移脚本 V2__add_shipping_address.sql
// 原则：只增不删，确保旧版本代码仍然兼容

-- 安全的新增列（旧代码会忽略不识别的列）
ALTER TABLE orders
    ADD COLUMN shipping_address VARCHAR(500) NULL;

ALTER TABLE orders
    ADD COLUMN shipping_method VARCHAR(50) NULL;

ALTER TABLE orders
    ADD INDEX idx_shipping_method (shipping_method);

-- 不推荐：ALTER TABLE orders DROP COLUMN old_column;
-- 不推荐：ALTER TABLE orders MODIFY COLUMN status VARCHAR(20);
-- 这些操作会让旧版本的代码崩溃

// 版本映射表 - 用于回滚协调
// CREATE TABLE deployment_versions (
//     id BIGINT AUTO_INCREMENT PRIMARY KEY,
//     deployment_id VARCHAR(100) NOT NULL,
//     service_name VARCHAR(100) NOT NULL,
//     image_tag VARCHAR(200) NOT NULL,
//     schema_version VARCHAR(50) NOT NULL,
//     deployed_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
//     status ENUM('ACTIVE', 'ROLLED_BACK') DEFAULT 'ACTIVE'
// );

// 回滚流程伪代码
// function rollback(deploymentId):
//     // 1. 获取本次部署的所有服务和版本
//     versions = getDeploymentVersions(deploymentId)
//     // 2. 按依赖顺序逆序回滚
//     reversed = reverseTopologicalSort(versions)
//     for each service in reversed:
//         // 3. 对每个服务执行回滚
//         previousImage = getPreviousImage(service.name)
//         kubectl.setImage(service.name, previousImage)
//         // 4. 验证回滚后的健康状态
//         waitForHealthy(service.name)
//     // 5. 回滚数据库schema（如果有必要）
//     flyway.undo(lastMigration)
//     // 6. 标记回滚完成
//     markRollbackComplete(deploymentId)

八、微服务测试

微服务测试比单体应用测试复杂得多，需要从多个层次进行验证。Martin Fowler推荐的测试金字塔在微服务中演变为更复杂的多维测试策略。

8.1 契约测试

契约测试（Contract Testing）是微服务测试的核心实践，通过验证服务间的接口契约来确保服务兼容性。消费者驱动的契约测试（Consumer-Driven Contract Testing, CDC）让服务的消费者编写契约，服务提供者验证契约，从而实现接口的演进式治理。

// Spring Cloud Contract - 消费者驱动契约测试

// 消费者端 - 定义契约（Groovy DSL）
// file: contracts/shouldReturnOrder.groovy

Contract.make {
    description "获取订单信息 - 正常场景"
    request {
        method 'GET'
        url '/api/v1/orders/ORD-20260501-001'
        headers {
            accept(applicationJson())
        }
    }
    response {
        status OK()
        headers {
            contentType(applicationJson())
        }
        body([
            orderId   : "ORD-20260501-001",
            userId    : "USR-10086",
            status    : "CONFIRMED",
            totalAmount: 299.00,
            items     : [
                [productId: "PROD-A001", quantity: 2, unitPrice: 99.50],
                [productId: "PROD-B002", quantity: 1, unitPrice: 100.00]
            ],
            createdAt : $(regex("\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}Z"))
        ])
    }
}

// 服务提供者端 - 验证契约
@SpringBootTest(webEnvironment = WebEnvironment.MOCK)
@AutoConfigureMockMvc
@AutoConfigureContractVerifier(initWith = ContractVerifierAutoConfiguration.class)
class OrderServiceContractVerifierTest {

    @Autowired
    private MockMvc mockMvc;

    @BeforeEach
    void setup() {
        MockMvcContractVerifier verifier =
            new MockMvcContractVerifier(mockMvc);
        // 契约文件会自动从消费者发布的jar包中加载
    }
}

// Pact - 另一种CDC框架实现
@Provider("order-service")
@PactBroker(url = "${pact.broker.url:http://localhost:9292}")
@SpringBootTest(webEnvironment = SpringBootTest.WebEnvironment.RANDOM_PORT)
public class OrderServicePactTest {

    @LocalServerPort
    int port;

    @BeforeEach
    void setup(PactVerificationContext context) {
        context.setTarget(new HttpTestTarget("localhost", port));
    }

    @TestTemplate
    @ExtendWith(PactVerificationInvocationContextProvider.class)
    void pactVerificationTestTemplate(PactVerificationContext context) {
        context.verifyInteraction();
    }

    @State("订单 ORD-20260501-001 存在")
    public void orderExists() {
        // 准备测试数据
        orderRepository.save(Order.builder()
            .orderId("ORD-20260501-001")
            .userId("USR-10086")
            .status(OrderStatus.CONFIRMED)
            .totalAmount(new BigDecimal("299.00"))
            .build());
    }
}

8.2 集成测试

集成测试验证服务与外部依赖（数据库、消息队列、其他服务）之间的交互是否正确。使用Testcontainers库可以在测试中启动真实的容器化依赖，避免使用mock带来的不确定性。

// Testcontainers 集成测试示例

@SpringBootTest
@Testcontainers
class OrderServiceIntegrationTest {

    // 启动真实的PostgreSQL和Kafka容器
    @Container
    static PostgreSQLContainer<?> postgres = new PostgreSQLContainer<>("postgres:16")
        .withDatabaseName("testdb")
        .withUsername("test")
        .withPassword("test");

    @Container
    static KafkaContainer kafka = new KafkaContainer(
        DockerImageName.parse("confluentinc/cp-kafka:7.6.0"));

    @DynamicPropertySource
    static void configureProperties(DynamicPropertyRegistry registry) {
        registry.add("spring.datasource.url", postgres::getJdbcUrl);
        registry.add("spring.datasource.username", postgres::getUsername);
        registry.add("spring.datasource.password", postgres::getPassword);
        registry.add("spring.kafka.bootstrap-servers", kafka::getBootstrapServers);
    }

    @Autowired
    private OrderRepository orderRepository;
    @Autowired
    private KafkaTemplate<String, Object> kafkaTemplate;

    @Test
    void shouldCreateOrderAndPublishEvent() {
        // 准备数据
        CreateOrderRequest request = new CreateOrderRequest();
        request.setUserId("USR-TEST-001");
        request.setItems(List.of(
            new OrderItem("PROD-X", 1, BigDecimal.valueOf(99.0))
        ));

        // 执行业务操作
        Order order = orderService.createOrder(request);

        // 验证数据库持久化
        assertThat(orderRepository.findById(order.getId())).isPresent();
        assertThat(order.getStatus()).isEqualTo(OrderStatus.CREATED);

        // 验证消息已发布
        // 使用KafkaTestUtils消费并断言
        Consumer<String, Object> consumer = createTestConsumer();
        consumer.subscribe(List.of("order.events"));
        ConsumerRecord<String, Object> record =
            KafkaTestUtils.getSingleRecord(consumer, "order.events");
        assertThat(record.value()).isInstanceOf(OrderCreatedEvent.class);

        OrderCreatedEvent event = (OrderCreatedEvent) record.value();
        assertThat(event.getOrderId()).isEqualTo(order.getId());
    }
}

8.3 端到端测试

端到端测试（E2E Testing）模拟用户真实操作，验证完整的业务流程在各个微服务中是否正确流转。E2E测试环境应尽可能接近生产环境，使用独立的测试命名空间。由于E2E测试执行速度慢、稳定性差，应该控制E2E测试的数量，仅覆盖核心业务路径。

// Playwright + Docker Compose E2E 测试

// docker-compose.e2e.yml 定义完整测试环境
// services:
//   gateway:
//     image: registry.example.com/gateway:test
//     ports: ["8080:8080"]
//   user-service:
//     image: registry.example.com/user-service:test
//   order-service:
//     image: registry.example.com/order-service:test
//   product-service:
//     image: registry.example.com/product-service:test
//   payment-service:
//     image: registry.example.com/payment-service:test
//   postgres:
//     image: postgres:16
//   kafka:
//     image: confluentinc/cp-kafka:7.6.0
//   init-data:
//     build: ./test-data

// playwright.config.ts
import { defineConfig } from '@playwright/test';

export default defineConfig({
    testDir: './e2e',
    timeout: 60000,
    retries: 2,
    use: {
        baseURL: 'http://localhost:8080',
        trace: 'on-first-retry',
    },
    projects: [
        { name: 'critical-path', testMatch: 'critical/*.spec.ts' },
        { name: 'business-flow', testMatch: 'flow/*.spec.ts' },
    ],
});

// e2e/critical/order-flow.spec.ts
import { test, expect } from '@playwright/test';

test('完整下单流程：登录 -> 浏览商品 -> 加购物车 -> 下单 -> 支付', async ({ page }) => {
    // 1. 用户登录
    await page.goto('/login');
    await page.fill('[data-testid="username"]', 'testuser');
    await page.fill('[data-testid="password"]', 'TestPass123!');
    await page.click('[data-testid="login-btn"]');
    await expect(page.locator('[data-testid="user-name"]'))
        .toHaveText('testuser');

    // 2. 搜索并浏览商品
    await page.fill('[data-testid="search-input"]', '无线蓝牙耳机');
    await page.click('[data-testid="search-btn"]');
    await page.locator('[data-testid="product-card"]').first().click();

    // 3. 加入购物车
    await page.click('[data-testid="add-to-cart"]');
    await expect(page.locator('[data-testid="cart-badge"]'))
        .toHaveText('1');

    // 4. 下单
    await page.click('[data-testid="checkout-btn"]');
    await page.fill('[data-testid="address-input"]', '上海市浦东新区xx路100号');
    await page.click('[data-testid="submit-order"]');
    await expect(page.locator('[data-testid="order-success"]'))
        .toBeVisible();
    const orderId = await page
        .locator('[data-testid="order-id"]').textContent();

    // 5. 验证订单状态
    await page.goto('/orders/' + orderId);
    await expect(page.locator('[data-testid="order-status"]'))
        .toHaveText('已支付');
});

8.4 服务虚拟化

服务虚拟化（Service Virtualization）或称为API模拟（API Mocking），用于在测试中模拟那些不稳定、昂贵或尚未开发完成的外部依赖服务。WireMock是Java生态中最流行的HTTP模拟框架，Hoverfly则支持更丰富的协议模拟。

// WireMock 服务虚拟化示例

@SpringBootTest
@WireMockTest(httpPort = 9090)
class OrderServiceWireMockTest {

    @Autowired
    private OrderService orderService;

    @BeforeEach
    void setupStubs() {
        // 模拟支付服务
        stubFor(post(urlEqualTo("/api/v1/payments"))
            .withHeader("Content-Type", containing("json"))
            .withRequestBody(matchingJsonPath("$.orderId"))
            .willReturn(aResponse()
                .withStatus(200)
                .withHeader("Content-Type", "application/json")
                .withBody("""
                    {
                        "transactionId": "TXN-98765",
                        "status": "SUCCESS",
                        "amount": 299.00,
                        "processedAt": "2026-05-08T10:30:00Z"
                    }
                    """)
                .withFixedDelay(50)));

        // 模拟物流服务
        stubFor(post(urlEqualTo("/api/v1/shipments"))
            .willReturn(aResponse()
                .withStatus(201)
                .withBody("""
                    {
                        "shipmentId": "SHP-001",
                        "estimatedDelivery": "2026-05-10",
                        "carrier": "SF-Express"
                    }
                    """)
                .withFixedDelay(30)));

        // 模拟库存服务 - 超时场景
        stubFor(get(urlPathMatching("/api/v1/inventory/.*"))
            .willReturn(aResponse()
                .withStatus(200)
                .withFixedDelay(5000)));  // 5秒延迟，测试超时处理
    }

    @Test
    void shouldCompleteOrderWithAllExternalServices() {
        CreateOrderRequest request = new CreateOrderRequest();
        request.setUserId("USR-TEST");
        request.setItems(List.of(
            new OrderItem("PROD-X", 1, BigDecimal.valueOf(299.0))
        ));

        OrderResult result = orderService.createOrder(request);

        assertThat(result.getStatus()).isEqualTo("CONFIRMED");
        assertThat(result.getTransactionId()).isEqualTo("TXN-98765");
        assertThat(result.getShipmentId()).isEqualTo("SHP-001");
    }

    @Test
    void shouldHandleInventoryTimeoutGracefully() {
        // 库存服务延迟测试
        OrderRequest request = new OrderRequest();
        request.setUserId("USR-TEST");
        request.setItems(List.of(
            new OrderItem("INVENTORY-SLOW", 1, BigDecimal.valueOf(100))
        ));

        assertThatThrownBy(() -> orderService.createOrder(request))
            .isInstanceOf(ServiceTimeoutException.class);
    }
}

测试策略总结：契约测试保证服务间接口兼容性（覆盖80%的集成问题）→ 集成测试验证基础设施交互 → E2E测试覆盖核心业务流程（控制在10个以内）→ 服务虚拟化解决外部依赖的不稳定性。使用Claude Code可以自动生成基于OpenAPI规范的契约测试和WireMock桩代码，大幅减少手工编写测试的工作量。

九、Claude Code赋能微服务开发

在微服务开发的完整生命周期中，Claude Code可以在以下环节显著提升效率：

需求分析阶段： 通过分析业务描述，自动识别限界上下文和实体定义，输出DDD聚合模型
代码生成阶段： 根据接口规范自动生成gRPC/Protobuf定义、REST控制器、服务接口和仓储实现
配置管理阶段： 生成Kubernetes部署文件、Istio虚拟服务/DestinationRule配置、CI/CD流水线脚本
测试阶段： 生成基于Spring Cloud Contract的契约测试、Testcontainers集成测试和WireMock桩代码
故障排查阶段： 根据链路追踪数据自动分析调用链，定位性能瓶颈和异常节点
代码审查阶段： 检查服务间耦合度、API版本兼容性、分布式事务的正确性和幂等性实现

最佳实践：在Claude Code中使用MCP工具（如File操作、Bash执行和WebFetch）构建端到端的微服务开发Agent。赋予Agent对项目代码库的完整理解能力，让AI同时扮演架构师、开发者和测试工程师的多重角色，实现从服务拆分到生产部署的全流程智能化辅助。

十、核心要点总结

1. 服务拆分：以DDD限界上下文为核心依据，采用绞杀者模式渐进式迁移单体应用。服务粒度以"独立可部署"为衡量标准，避免分布式单体反模式。

2. 服务通信：内部高频调用使用gRPC（高性能二进制协议），外部API使用REST（通用性），异步解耦使用Kafka/RabbitMQ（事件驱动架构）。服务发现与客户端负载均衡是动态拓扑的基石。

3. API网关：统一入口处理横切关注点（路由、限流、鉴权、熔断），通过令牌桶和滑动窗口实现精细化的流量控制，使用Resilience4j实现熔断降级。

4. 服务治理：注册中心（Nacos/Eureka）+ 配置中心 + OpenTelemetry链路追踪 + ELK日志聚合 + K8s健康检查 + Istio服务网格，构建完整的可观测性和流量管理平台。

5. 分布式事务：优先使用事件驱动加最终一致性方案，业务需要强一致性时采用Saga模式（协调器模式更可控），避免在跨服务操作中使用2PC。

6. CI/CD与发布：每个服务独立流水线，使用金丝雀发布或蓝绿部署降低发布风险，建立完整的版本映射表和回滚流程。

7. 测试策略：契约测试确保接口兼容性，Testcontainers提供真实的集成测试环境，E2E测试覆盖核心业务流程，WireMock隔离外部依赖的不确定性。