Java 分布式架构设计入门到进阶

单机到集群：为何需要分布式架构

当用户量、数据量或发布频率超过单机/单库舒适区，团队会把系统拆到多台机器上协作。常见驱动力：

• 水平扩展 — 加机器分担读/写吞吐，而不是无限堆单机配置。
• 故障隔离 — 单点故障只影响局部；配合副本与自动切换提高可用性。
• 组织与交付 — 多团队并行演进不同业务能力（与 康威定律 相关，架构风格：单体、SOA 与微服务 展开）。
• 地理与合规 — 多机房、多区域部署降低延迟或满足数据驻留要求。

何时值得认真考虑拆分？ 不必等到「千万 QPS」才行动，下列信号出现时应把分布式纳入架构讨论（满足其一即可启动评估）：

• 单机或单库连接池、CPU、磁盘 IO 长期打满，垂直扩容性价比明显下降。
• 发布耦合：改一个小模块需要全量回归、全量部署，交付周期被拖慢。
• 可用性目标 要求多 AZ/多机房与明确 RTO/RPO，单机故障域无法接受。
• 组织规模 扩大，多团队需并行演进不同业务线。

远程调用：反例 vs 推荐做法

网络分区、时钟漂移与部分失败

分布式系统的默认假设是：网络不可靠、节点会挂、时钟不完全同步。这三点直接决定你不能把远程调用当成本地方法调用。

• 网络分区 — 节点之间暂时不可达，但各自仍在运行；此时「全局一致决策」可能无法同时满足。
• 时钟漂移 — 即使部署 NTP，各节点墙钟仍可能偏差；不要用 System.currentTimeMillis() 在跨服务间排序事件。
• 部分失败 — 请求可能「客户端以为失败、服务端已成功」或相反；必须设计超时、重试、幂等与可补偿流程。

一次下单调用的失败形态

sequenceDiagram
  participant U as 用户
  participant O as order-service
  participant I as inventory-service
  U->>O: 提交订单
  O->>I: POST /reserve (timeout=2s)
  Note over I: 库存已扣减
  I--xO: 响应在网络中丢失
  Note over O: 重试？幂等？人工对账？

调用方视角 × 服务端真实状态

超时后重试：代码层反例与推荐

// 无幂等键、无上限 — 可能重复扣库存
for (int i = 0; i < 10; i++) {
  try {
    inventoryClient.reserve(orderId, skuId, qty);
    break;
  } catch (Exception e) {
    Thread.sleep(100);
  }
}

// 同一 requestId：服务端已处理则直接返回原结果
ReserveResult r = inventoryClient.reserve(
  new ReserveCommand(requestId, orderId, skuId, qty));
if (r.isUnknown()) {
  r = inventoryClient.getReserveStatus(requestId);
}
// 仍不确定 → 标记订单「待对账」，勿直接成功

读超时设多少？（示意滑块）

可扩展性、可用性与一致性三角

工程上常同时追求三者，但在故障与负载压力下必须排序优先级。例如：

场景决策：大促秒杀 vs 财务对账

CAP、BASE 与一致性模型 将用 CAP 定理 与 BASE 把上表落到可讨论的取舍语言。

Java 技术栈在分布式中的常见角色

本课实践以 JVM 企业栈为主。常见分工如下：

• 应用运行时 — Spring Boot、Actuator 健康检查。
• 服务治理 — 注册发现、API 网关、配置中心。
• 服务间通信 — OpenFeign（同步）、Spring Cloud Stream（异步）。
• 数据与一致性 — 本地事务；跨服务用 Saga、Outbox、Seata。

通信模式：同步 vs 异步（标签页）

ShopFlow 逻辑分层（预习）

flowchart LR
  Client[Web / App]
  GW[API Gateway]
  Order[order-service]
  Inv[inventory-service]
  Pay[payment-service]
  Client --> GW
  GW --> Order
  Order -->|同步 HTTP| Inv
  Order -.->|异步事件| Pay

服务间调用：超时须显式配置（预览）

spring:
  cloud:
    openfeign:
      client:
        config:
          inventory-service:
            connectTimeout: 2000
            readTimeout: 2000

本课 ShopFlow 示例业务全景

ShopFlow 按 限界上下文 划分三大域：

常见问题（FAQ）

CAP 定理与工程中的真实取舍

CAP 定理（Brewer）指出：在存在网络分区时，分布式系统无法同时满足：

• C（Consistency） — 每次读都能读到最新写入，或返回错误（线性一致视角的简化理解）。
• A（Availability） — 每个请求都能得到非错误响应（不要求读到最新）。
• P（Partition tolerance） — 分区发生后系统仍能继续工作（节点间消息可能丢失/延迟）。

真实部署几乎必须接受 P，于是分区发生时要在 C 与 A 间做选择——不是「三选二」的日常开关，而是按业务路径分别设计。

分区时的二选一（概念图）

flowchart TB
  subgraph normal [无分区]
    W[写入成功] --> R[读到最新]
  end
  subgraph partition [发生分区 P]
    CP[选 CP] -->|拒绝部分读写| ERR[返回错误 / 降级]
    AP[选 AP] -->|继续服务| STALE[可能读到旧副本]
  end
  normal --> partition

对照：CP 与 AP 在 ShopFlow 中的例子

PACELC 延伸（了解即可）

无分区时仍要在延迟（L）与一致（C）间权衡：例如跨地域复制常降低一致级别以换更低延迟。设计评审时可问：「正常时要多一致？分区时要多可用？」

强一致、最终一致与因果一致

「一致性」在不同语境含义不同：数据库事务、副本同步、客户端会话。下表是架构讨论中最常用的划分。

序列图：最终一致下的读延迟

sequenceDiagram
  participant App as order-service
  participant M as DB 主
  participant R as DB 从
  App->>M: UPDATE stock=9
  M-->>App: OK
  App->>R: SELECT stock
  R-->>App: stock=10 (复制滞后)
  Note over M,R: 异步复制追上后读到 9

场景决策：接口选哪种一致级别

互动：副本读一致性级别（示意）

BASE 与互联网业务常见策略

BASE 是对 AP 路径的实操总结（与 ACID 相对）：

• Basically Available — 核心路径尽量有响应，非核心可降级。
• Soft state — 中间状态允许存在（处理中、待对账）。
• Eventually consistent — 通过复制、消息、定时任务达到一致。

ACID vs BASE（单服务 vs 跨服务）

代码：Transactional Outbox 预览

「写订单表 + 发 Kafka」无法靠本地事务一起提交。常见做法：Outbox 与业务写入同一事务，再由投递器异步发消息。

@Transactional
public void createOrder(CreateOrder cmd) {
  orderRepository.save(cmd.toOrder());
  outboxRepository.save(OutboxEvent.orderCreated(cmd.orderId()));
  // 同一 DB 事务；消息由 poller 异步投递，消费者须幂等
}

互联网常见组合拳

• 幂等键 — 重复请求返回同一业务结果。
• 对账任务 — 日终比对订单、支付、库存流水。
• 状态机 — 订单 CREATED → PAID，非法跳转拒绝。
• 降级开关 — 分区时关闭非核心功能，保护核心下单路径。

分布式锁、租约与 fencing token 概念

跨节点互斥（定时任务抢主、库存扣减串行化）常用分布式锁。实现须考虑：锁持有者崩溃、时钟漂移、旧锁未释放就获得新锁。

• 租约（Lease） — 锁带 TTL；持有者须周期性续租，否则自动释放。
• Fencing token — 单调递增令牌；下游存储拒绝比当前令牌更旧的写，防止「僵尸持有者」覆写新主。

流程：为何需要 fencing

sequenceDiagram
  participant N1 as 节点1(旧主)
  participant L as 锁服务
  participant DB as 存储
  N1->>L: 曾持有 lock#5
  Note over N1: GC 停顿后「以为」仍持有锁
  participant N2 as 节点2(新主)
  N2->>L: 获得 lock#6
  N2->>DB: write(token=6)
  N1->>DB: write(token=5) 
  Note over DB: 无 fencing 时旧写可能破坏新写

代码对比：锁值是否单调

// 下游无法区分「旧主迟到的写」
String lockVal = UUID.randomUUID().toString();
redis.set("lock:job", lockVal, NX, PX, 30000);

long token = lockService.acquire("inventory-shard-1", Duration.ofSeconds(30));
inventoryRepository.decrement(skuId, qty, token);
// 仓储层: if (token < lastAppliedToken) reject;

Java 生态常见组件：Redis Redisson、ZooKeeper Curator、数据库 SELECT … FOR UPDATE（有单点边界）。能不用锁就不用：优先幂等、分区键串行、CRDT 等业务手段。

读己之写、单调读等客户端语义

即使存储标记为「最终一致」，产品仍常要求会话级体验保证（由网关粘滞、读写路由或版本号实现）：

配置预览：读写分离时的「读主」开关

shopflow:
  datasource:
    read-your-writes: true
    # 创建订单后的 5s 内，该 userId 查询走主库

FAQ

下一章讨论 架构风格：单体、SOA 与微服务，把本章取舍落到架构形态选择。

分层单体与模块化单体的边界

分层单体（Layered Monolith）：按技术层划分包结构，所有业务能力共享同一部署单元与数据库。优点是上手快、本地调试简单、事务在进程内完成；风险是边界模糊时演变成「大泥球」——改订单逻辑可能误触库存表。

典型分层（概念）

flowchart TB
  UI[Web / API Controller] --> APP[Application Service]
  APP --> DOM[Domain Model]
  DOM --> INF[Infrastructure / JPA]
  INF --> DB[(单一数据库)]

模块化单体（Modular Monolith）

仍在一个进程、一次部署，但按业务能力或限界上下文划分子模块（Maven/Gradle 多模块），模块间通过显式 API 通信，禁止随意跨模块访问对方表。

• shopflow-order、shopflow-inventory、shopflow-payment 模块，共享 shopflow-app 启动器。
• 模块内可继续分层；模块间仅暴露接口（Java interface / 应用服务门面）。
• 为将来拆成独立服务做「排练」：边界清晰后再加网络与注册发现。

代码对比：跨边界访问

// 反例：订单服务直接操作库存表
@Service
class OrderService {
  @Autowired InventoryRepository inventoryRepo; // 跨上下文泄漏
  void placeOrder(...) {
    inventoryRepo.decrement(skuId, qty);
  }
}

// 推荐：通过 inventory 模块公开门面
@Service
class OrderService {
  private final InventoryFacade inventory;
  void placeOrder(...) {
    inventory.reserve(new ReserveCommand(orderId, skuId, qty));
  }
}

SOA、ESB 与微服务的演进脉络

2000 年代前后，面向服务架构（SOA） 强调将企业能力封装为可复用服务，常配合企业服务总线（ESB） 做路由、转换、编排与集中治理。

演进时间线（简化）

timeline
  title 从集中到分布式的常见路径
  2000s : 分层单体 / 大泥球
  2005-2015 : SOA + ESB 集中编排
  2014+ : 微服务 + 轻量消息总线 / API 网关
  近年 : 模块化单体复兴 + 选择性微服务

SOA + ESB 的典型拓扑

flowchart LR
  O[订单系统] --> ESB[ESB 总线]
  I[库存系统] --> ESB
  P[支付系统] --> ESB
  ESB --> T[转换 / 路由 / 编排规则]

微服务的关键转向

• 智能端点， dumb pipe：业务逻辑在服务内；管道尽量简单（HTTP/gRPC、消息中间件），避免 ESB 里堆满业务规则。
• 去中心化数据：每服务自有数据库（或 schema），不再默认「全企业一个库」。
• 独立部署：团队拥有从设计到运行的全生命周期（DevOps）。

微服务收益、成本与适用场景

微服务不是「更先进的单体」，而是用运维与组织复杂度交换独立演进能力。下表帮助你在评审会上说清利弊。

场景决策表

康威定律与团队拓扑

康威定律（Conway's Law）：设计系统的组织，其产生的设计等价于组织内的沟通结构。换言之一一你的架构图最终会像你的组织架构图。

对微服务拆分的含义

• 若订单与库存由同一小队维护，硬拆成两个远程服务只会增加沟通成本，而不会 magically 变快。
• 若支付由合规独立团队负责，payment-service 作为独立部署单元更自然。
• 平台团队提供注册发现、网关、CI 模板，让业务小队专注域逻辑（Team Topologies 中的 Platform / Enabling）。

flowchart TB
  subgraph teamOrder [订单小队]
    OS[order-service]
  end
  subgraph teamInv [库存小队]
    IS[inventory-service]
  end
  subgraph teamPay [支付小队]
    PS[payment-service]
  end
  subgraph platform [平台小队]
    GW[API Gateway]
    REG[注册中心]
  end
  GW --> OS
  GW --> IS
  OS -->|同步 reserve| IS
  PS -->|PaymentCompleted 事件| OS

反模式：组织未拆，服务先拆

两个团队仍共用一个 backlog，却维护六个微服务 — 变更仍需全员协调，却背上分布式排障成本。这叫分布式单体（领域建模、边界上下文与 API 契约 会进一步约束边界）。

何时不应拆微服务

下列信号出现越多，越应推迟物理拆分，优先模块化单体或合并服务。

• 边界不清：Order 与 Inventory 实体互相引用，无法一句话说清谁拥有哪张表。
• 无自动化：没有 CI/CD、容器化、集中日志与链路追踪，却要先上 8 个服务。
• 事务密集：大量跨模块强一致 ACID 需求，拆后只能上重型分布式事务。
• 团队过小：5 人维护 12 个服务，人均运维负担超过业务开发。
• 为技术而拆：「微服务很潮」但流量与组织规模仍适合单体。

渐进路径

1. 模块化单体 — 在进程内练边界与契约。
2. 绞杀者（Strangler） — 新能力在新服务，旧模块逐步下线（演进模式、反模式与架构评审 再展开）。
3. 选择性拆分 — 先拆变化最快或需独立扩缩的上下文（如 Inventory 读多写多）。

下一章进入 领域建模、边界上下文与 API 契约，把「模块/服务边界」落到限界上下文与 OpenAPI。

DDD 战略设计：限界上下文与子域

领域驱动设计（DDD）战略设计关注「大问题如何切」：识别子域（Subdomain）类型，并为每个核心能力划定限界上下文（Bounded Context）。

子域三分法

限界上下文的关键属性

• 统一语言（Ubiquitous Language）：上下文内术语一致；Order 里的 OrderLine 与 Inventory 里的 StockReservation 不必强行合并。
• 模型边界：实体、聚合根、仓储仅在本上下文内完整；对外只暴露 DTO / 应用服务 / 事件。
• 与部署单元的关系：理想上一上下文对应一个可独立演进的服务（或模块化单体中的一个模块），与 康威定律 对齐。

flowchart LR
  subgraph orderCtx [Order 上下文]
    O[Order 聚合]
    OL[OrderLine]
  end
  subgraph invCtx [Inventory 上下文]
    S[Sku / Stock]
    R[Reservation]
  end
  subgraph payCtx [Payment 上下文]
    P[Payment]
    Ref[Refund]
  end
  orderCtx -->|ReserveCommand API| invCtx
  orderCtx -->|InitiatePayment API| payCtx
  payCtx -->|PaymentCompleted 事件| orderCtx

按业务能力拆分 vs 按技术层拆分

架构风格：单体、SOA 与微服务 已对比分层单体与模块化单体；本节从 DDD 视角强调：微服务边界应沿业务能力（限界上下文）切，而非沿 Controller / Service / Repository 等技术层切。

两种切法对比

代码对比：集成方式

// 反例：按「层」拆服务，却共享 order 表与实体
// order-query-service 直接读 order 表 join inventory 表
@Query("SELECT o, i FROM Order o JOIN Inventory i ON ...")
List<OrderDetailDto> findAllWithStock();

// 推荐：Order 上下文通过契约调用 Inventory
public OrderView getOrder(UUID orderId) {
  Order order = orderRepo.findById(orderId);
  StockSnapshot stock = inventoryClient.getSku(order.getSkuId());
  return OrderView.from(order, stock); // 组合视图，非共享实体
}

REST 资源建模、版本化与错误码规范

限界上下文对外通常以 RESTful HTTP API 暴露能力（practice 阶段亦用 OpenFeign 消费）。好的资源建模让调用方「读 URI 即懂语义」，并预留演进空间。

资源 URI 原则

• 名词复数、表意资源：/orders、/skus/{skuId}/reservations，避免 /createOrder 动词路径。
• 动作用语义子资源或 PATCH：取消订单 POST /orders/{id}/cancel 或 PATCH /orders/{id} + {"status":"CANCELLED"}。
• 跨上下文 ID 引用：Order 只存 skuId，不在 URI 里嵌 inventory 内部仓库 ID，除非该 ID 已是稳定集成标识。
• 幂等键：写操作（如 POST /reservations）要求 Header Idempotency-Key 或 body 内 requestId，应对 部分失败 重试。

ShopFlow 核心端点（示意）

版本化策略

统一错误响应

{
  "code": "INVENTORY_INSUFFICIENT",
  "message": "SKU-1001 可售库存不足",
  "traceId": "7f3a2b1c-...",
  "details": { "skuId": "SKU-1001", "requested": 5, "available": 2 }
}

• code：机器可读、文档化枚举（各服务可前缀 ORDER_ / INV_，网关可映射为统一表）。
• traceId：与日志、链路追踪关联，便于排障。
• HTTP 状态码表达协议层语义（404 资源不存在、409 冲突、422 业务校验失败），body 的 code 表达业务层语义。

契约优先：OpenAPI 与消费者驱动契约

契约优先（Contract First）：先写 OpenAPI 规范，再生成/实现 Controller 与客户端桩代码。这样 Order 与 Inventory 团队在编码前就对齐字段、错误码与幂等语义。

OpenAPI 片段（Inventory · 预留库存）

openapi: 3.1.0
info:
  title: ShopFlow Inventory API
  version: 1.0.0
paths:
  /api/v1/reservations:
    post:
      operationId: createReservation
      parameters:
        - name: Idempotency-Key
          in: header
          required: true
          schema: { type: string, format: uuid }
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [orderId, skuId, quantity]
              properties:
                orderId: { type: string, format: uuid }
                skuId: { type: string }
                quantity: { type: integer, minimum: 1 }
      responses:
        '201':
          description: 预留成功
        '409':
          description: 库存不足或冲突

契约优先工作流

1. 领域专家 + 开发在 PR 中评审 openapi/inventory-api.yaml。
2. CI 校验 breaking change（如删除字段、改类型）。
3. 实现方对照契约写 Spring MVC / WebFlux；消费方用 OpenFeign + 生成 DTO 或手写映射。
4. 契约测试（Pact 等）在 CI 验证「消费者期望 ⊆ 提供者实现」。

消费者驱动契约（CDC）

在 微服务 集成中，调用方（消费者） 定义「我需要哪些字段与状态码」，写入契约文件；提供方 在 CI 中验证能否满足。这样 inventory 重构内部表结构时，只要仍满足 order-service 的契约，集成测试即可通过。

sequenceDiagram
  participant OC as order-service 消费者
  participant Pact as 契约仓库 / CI
  participant IS as inventory-service 提供者
  OC->>Pact: 提交期望契约（reserve 201/409）
  IS->>Pact: Provider 验证任务
  Pact->>IS: 验证通过 / 失败
  Note over OC,IS: 实现前对齐；改 API 须双方评审

ShopFlow：订单、库存、支付上下文划分

将本章方法落到 ShopFlow 全课主线：三个上下文各司其职，通过 API 网关 对外统一入口，内部走同步 API + 异步事件。

上下文职责表

下单 happy path（集成视图）

sequenceDiagram
  participant U as 用户
  participant GW as API Gateway
  participant O as order-service
  participant I as inventory-service
  participant P as payment-service
  U->>GW: POST /api/v1/orders
  GW->>O: 转发
  O->>I: POST /reservations (Idempotency-Key)
  I-->>O: 201 Reserved
  O->>P: POST /payments
  P-->>O: 202 Accepted
  O-->>U: 201 Order PENDING_PAYMENT
  P-->>O: PaymentCompleted 事件
  O->>O: 状态 → PAID

上下文映射（Context Map）简图

• Order → Inventory：Customer-Supplier（Order 为客，Inventory 为供）；Inventory 上游发布 OpenAPI，Order 消费。
• Order → Payment：同上；Payment 完成后以事件通知 Order（避免 Payment 同步回调 Order 造成环依赖）。
• Anti-corruption Layer：Order 内 InventoryClient 将外部 DTO 转为域内 ReservationResult，隔离外部模型变化。

下一章 通信模式：同步、异步与事件驱动 将把同步/异步、编排与编舞、Outbox 与本章契约映射到 Spring Cloud 概念。

请求/响应、RPC 与 gRPC 适用场景

请求/响应（Request/Response）是分布式中最直观的模式：调用方发请求、阻塞或异步等待响应。在 Java 微服务中常体现为 REST + OpenAPI 契约，practice 阶段用 OpenFeign 消费。

三种同步风格对比

OpenFeign 调用预览（YAML）

# 详见 OpenFeign、负载均衡与服务间调用；此处仅示意超时与幂等头
spring:
  cloud:
    openfeign:
      client:
        config:
          inventory-service:
            connectTimeout: 1000
            readTimeout: 2000
# 调用时 Header: Idempotency-Key: {orderId}

消息队列、发布订阅与事件通知

当调用方不必立即知道下游处理结果，或需要削峰、解耦多订阅者时，使用异步消息。ShopFlow 中 PaymentCompleted、OrderCreated 等领域事件适合走 Kafka 等 MQ（详见 Kafka 事件驱动与 Redis 缓存）。

核心概念

• 消息队列（Queue）：点对点，一条消息通常被一个消费者处理（任务分发）。
• 发布/订阅（Pub/Sub）：一条事件可被多个订阅者各自处理（订单创建 → 库存、积分、通知各订一份）。
• 领域事件：用过去式命名（OrderCreated、PaymentCompleted），载荷含最小集成字段 + 事件 ID。
• 消费者组：同组内竞争消费保证扩展；不同组各自完整消费一遍。

flowchart LR
  Pay[payment-service] -->|publish| K[(Kafka topic)]
  K --> G1[order-service 消费者组]
  K --> G2[analytics 消费者组]
  G1 --> O[更新订单 PAID]
  G2 --> A[报表入库]

编排 vs 编舞（Choreography）

跨多个服务的业务流程（如下单 → 预留 → 支付 → 确认）如何协调？两种主流思路：编排（Orchestration） 由中央协调者按脚本推进；编舞（Choreography） 各服务监听事件、自行决定下一步，无中心大脑。

对比表

sequenceDiagram
  participant O as order-service 编排者
  participant I as inventory-service
  participant P as payment-service
  O->>I: 同步 reserve
  I-->>O: 201
  O->>P: 同步 initiate payment
  P-->>O: 202
  Note over O: 等待 PaymentCompleted 事件
  P-->>O: event PaymentCompleted
  O->>O: 状态 PAID

幂等键、去重与 Outbox 模式预览

异步与重试使「至少一次投递」成为常态。须从生产端与消费端双侧保证正确性。

消费端：幂等与去重

• 幂等键：同步写操作 Header Idempotency-Key；异步用 eventId 或业务键。
• 去重表：消费者处理前插入 processed_events(event_id)，重复则跳过。
• 业务幂等：如「订单已 PAID 则忽略重复 PaymentCompleted」。

生产端：Transactional Outbox

问题：订单入库与发 Kafka 两个操作无法共用一个本地事务。 Outbox 将待发事件与业务写入同一数据库事务，后台投递器异步发到 MQ。

@Transactional
void createOrder(CreateOrder cmd) {
  Order order = orderRepo.save(new Order(cmd));
  outboxRepo.save(new OutboxEvent(
    "OrderCreated",
    order.getId().toString(),
    toJson(new OrderCreatedPayload(order.getId(), ...))
  ));
  // 同一事务；投递器稍后 poll outbox → Kafka
}

为 Spring Cloud 实战做概念映射

basics 阶段原理收官。下表将本章概念映射到 practice 阶段 ShopFlow 工程（Java 21 + Spring Boot 3.5 + Spring Cloud 2025）。

JDK 21、Maven BOM 与 Spring Cloud 2025 对齐

本课栈：Java 21 LTS、Spring Boot 3.5.x、Spring Cloud 2025.0.x（2025.1 发布列车）。Spring Cloud 采用发布列车（Release Train）命名：2025.0.1 与 Boot 3.5 在官方兼容矩阵中配对，子项目通过 BOM import 继承版本。

父 POM：Boot 父 + Cloud BOM

<!-- shopflow/pom.xml 片段 -->
<parent>
  <groupId>org.springframework.boot</groupId>
  <artifactId>spring-boot-starter-parent</artifactId>
  <version>3.5.0</version>
</parent>

<properties>
  <java.version>21</java.version>
  <spring-cloud.version>2025.0.1</spring-cloud.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>
  </dependencies>
</dependencyManagement>

多模块工程：api / service / common 分层

将 领域建模、边界上下文与 API 契约 中的 ShopFlow 三上下文落到 Maven 模块：每个上下文至少 api + service，共享能力放入 common。这与 模块化单体 的分模块思路一致，只是 service 模块将独立进程部署为 微服务。

flowchart TB
  subgraph parent[shopflow-parent]
    C[shopflow-common]
    OA[order-api]
    OS[order-service]
    IA[inventory-api]
    IS[inventory-service]
    PA[payment-api]
    PS[payment-service]
  end
  OS --> OA
  OS --> C
  IS --> IA
  IS --> C
  PS --> PA
  PS --> C

各层职责

order-service 最小依赖

<!-- shopflow-order-service/pom.xml -->
<dependencies>
  <dependency>
    <groupId>com.shopflow</groupId>
    <artifactId>shopflow-order-api</artifactId>
  </dependency>
  <dependency>
    <groupId>com.shopflow</groupId>
    <artifactId>shopflow-common</artifactId>
  </dependency>
  <dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-web</artifactId>
  </dependency>
  <dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-actuator</artifactId>
  </dependency>
</dependencies>

配置外部化与 Profile 约定

多服务本地联调时，端口、数据源、日志级别必须可切换且可预测。ShopFlow 约定：

• 默认：application.yml 放共享默认（应用名、Actuator 暴露端点）。
• 环境：application-local.yml 本地 H2/端口；application-docker.yml 供 Compose（见 practice-02）。
• 激活：spring.profiles.active=local（IDE Run Configuration 或环境变量）。
• 敏感项：不进 Git；用 .env / 环境变量占位（生产走 Config Server，见 advanced 章）。

spring:
  application:
    name: order-service
management:
  endpoints:
    web:
      exposure:
        include: health,info
  endpoint:
    health:
      show-details: when_authorized

server:
  port: 8081
logging:
  level:
    com.shopflow: DEBUG

ShopFlow 仓库结构与本地启动顺序

推荐 monorepo 根目录 shopflow/，与课程 Demo 对齐。首章只需能启动 order-service 并访问健康检查；inventory / payment 可先留空模块占位。

目录树（精简）

shopflow/
├── pom.xml                      # 父 POM + BOM
├── shopflow-common/
├── shopflow-order-api/
├── shopflow-order-service/
│   └── src/main/java/.../OrderServiceApplication.java
├── shopflow-inventory-api/
├── shopflow-inventory-service/
├── shopflow-payment-api/
└── shopflow-payment-service/

本地启动顺序（本章）

1. 确认 java -version 为 21；根目录 mvn -q -DskipTests install 编译全模块。
2. 进入 shopflow-order-service，mvn spring-boot:run -Dspring-boot.run.profiles=local。
3. 访问 http://localhost:8081/actuator/health，期望 {"status":"UP"}。
4. （可选）用 IDE 运行 OrderServiceApplication，VM options 加 -Dspring.profiles.active=local。

健康检查 Actuator 与统一日志格式

Spring Boot Actuator 提供生产就绪端点。本地与 K8s 探针都依赖 /actuator/health；统一 JSON 日志则便于后续接入 ELK 与 traceId（可观测性 章展开）。

健康检查分组（入门）

• liveness：进程是否存活（默认 health 即可）。
• readiness：是否可接流量（后续加 DB、注册中心检查）。
• 勿对外暴露 env、beans 等敏感端点；生产用 Spring Security 或网络策略。

统一 JSON 日志（Logback）

<!-- shopflow-common/src/main/resources/logback-spring.xml 片段 -->
<appender name="JSON" class="ch.qos.logback.core.ConsoleAppender">
  <encoder class="net.logstash.logback.encoder.LogstashEncoder">
    <includeMdcKeyName>traceId</includeMdcKeyName>
    <customFields>{"service":"${spring.application.name:-unknown}"}</customFields>
  </encoder>
</appender>

本章在 common 中引入 logstash-logback-encoder，各 service 自动继承；日志行含 service、预留 traceId MDC 字段，与 Cloud 可观测组件 后续对齐。

Eureka / Nacos 注册中心选型对比

服务注册发现：服务启动时向注册中心登记自己的 host、port、元数据；消费者从注册中心查询可用实例，而不是写死 URL。ShopFlow 本课选用 Netflix Eureka（Spring Cloud 一等公民）；Nacos 在阿里生态与配置中心一体化场景更常见。

Eureka vs Nacos（ShopFlow 视角）

order-service、inventory-service 注册与心跳

在 脚手架 基础上，为各 service 模块添加 Eureka Client（版本由 Spring Cloud BOM 管理），并新增独立模块 shopflow-discovery-server（或 Docker 镜像）作为注册中心。

Discovery Server（Eureka Server）

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

# discovery-server / application-local.yml
server:
  port: 8761
eureka:
  client:
    register-with-eureka: false
    fetch-registry: false

业务服务注册（Client）

<dependency>
  <groupId>org.springframework.cloud</groupId>
  <artifactId>spring-cloud-starter-netflix-eureka-client</artifactId>
</dependency>

# order-service / application-local.yml
spring:
  application:
    name: order-service
eureka:
  client:
    service-url:
      defaultZone: http://localhost:8761/eureka/
  instance:
    prefer-ip-address: true
    lease-renewal-interval-in-seconds: 10

inventory-service 同理，spring.application.name 必须为 inventory-service（与 Gateway 路由 lb://inventory-service 一致）。

sequenceDiagram
  participant O as order-service
  participant E as Eureka :8761
  participant I as inventory-service
  O->>E: REGISTER (8081)
  I->>E: REGISTER (8082)
  loop 每 10s
    O->>E: RENEW 心跳
    I->>E: RENEW 心跳
  end
  Note over E: 超时未续约则剔除实例

Spring Cloud Gateway 路由与谓词过滤器

新增 shopflow-gateway 模块，依赖 spring-cloud-starter-gateway-server-webflux（Spring Cloud 2025 命名；WebFlux 网关为 ShopFlow 默认）。Gateway 从 Eureka 拉取实例，按路由（Route） = 谓词（Predicate）+ 过滤器（Filter）+ 目标 URI 转发流量。

最小路由：按路径前缀

# gateway / application-local.yml（Spring Cloud 2025 属性前缀）
server:
  port: 8080
spring:
  application:
    name: api-gateway
  cloud:
    gateway:
      server:
        webflux:
          routes:
            - id: order-route
              uri: lb://order-service
              predicates:
                - Path=/api/orders/**
            - id: inventory-route
              uri: lb://inventory-service
              predicates:
                - Path=/api/inventory/**

lb:// 表示通过 Spring Cloud LoadBalancer 从 Eureka 选实例。若从旧版迁移，可用 spring-boot-properties-migrator 对照 spring.cloud.gateway.* → spring.cloud.gateway.server.webflux.*。

统一入口：鉴权头透传与路径重写

外部客户端只访问 https://api.shopflow.example（本地 :8080），Gateway 负责 TLS 终止（生产）、JWT 校验（安全与部署 章）与把用户身份传给下游。业务服务不应再对外暴露端口。

StripPrefix + 鉴权头透传

spring:
  cloud:
    gateway:
      server:
        webflux:
          routes:
            - id: order-api
              uri: lb://order-service
              predicates:
                - Path=/api/orders/**
              filters:
                - StripPrefix=1
                - AddRequestHeader=X-ShopFlow-User-Id, #{headers['X-ShopFlow-User-Id']}
# 外部: GET /api/orders/123  →  order-service: GET /orders/123

本章仅演示头透传占位；完整 OAuth2 Resource Server 在 Gateway 统一验签后，将 sub 写入 X-ShopFlow-User-Id 即可。勿在 Gateway 写「下单编排」——那是 order-service 职责。

本地 Docker Compose 最小依赖栈

本地联调推荐 Compose 起 Eureka；业务服务仍可用 IDE / Maven 启动便于断点。Gateway 与 order / inventory 需能访问 8761。

compose 片段

# demos/practice-02-discovery-gateway-lab/docker-compose.yml
services:
  discovery-server:
    image: eclipse-temurin:21-jre
    ports:
      - "8761:8761"
    # 实际项目: 挂载 discovery-server.jar 或 build 镜像
    environment:
      SPRING_PROFILES_ACTIVE: docker

推荐启动顺序

1. docker compose up -d discovery-server（或本地跑 DiscoveryServerApplication）
2. 打开 http://localhost:8761，确认 Eureka 控制台可用
3. 启动 inventory-service（8082）、order-service（8081），在控制台看到 UP 实例
4. 启动 api-gateway（8080），curl http://localhost:8080/api/orders/actuator/health（经路由转发）