@umacloud/knowledge 1.0.1

package/development/05-cases/case-microservice-migration.md

@@ -0,0 +1,375 @@
+---
+id: case-microservice-migration
+title: 案例研究：从单体到微服务的迁移实战
+domain: development
+category: 05-cases
+difficulty: intermediate
+tags: [agent, case, checklist, development, microservice, migration, 元数据]
+quality_score: 70
+last_updated: 2026-06-15
+---
+# 案例研究：从单体到微服务的迁移实战
+
+## 元数据
+
+| 字段 | 值 |
+|------|------|
+| 行业 | 电商平台 |
+| 系统规模 | 日活 500 万，峰值 QPS 12,000 |
+| 团队规模 | 后端 28 人，运维 6 人，QA 8 人 |
+| 时间跨度 | 18 个月（2023-01 至 2024-06） |
+| 核心模式 | Strangler Fig Pattern + Branch by Abstraction |
+| 迁移前架构 | Java Spring Boot 单体 + MySQL 主从 |
+| 迁移后架构 | 23 个微服务 + API Gateway + Service Mesh |
+
+---
+
+## 一、背景
+
+### 1.1 业务现状
+
+某头部电商平台运营 5 年，核心系统为 Java Spring Boot 单体应用：
+
+- 代码仓库：单一 Git Repo，约 120 万行 Java 代码
+- 部署单元：单一 WAR 包，部署在 8 台物理机集群
+- 数据库：MySQL 8.0 主从架构，主库 32 核 128GB
+- 发布频率：每两周一次全量发布，窗口 4 小时
+- 团队结构：4 个功能团队共享同一代码库
+
+### 1.2 痛点分析
+
+| 痛点 | 表现 | 影响 |
+|------|------|------|
+| 发布耦合 | 任一模块变更需全量发布 | 发布频率低，阻塞业务迭代 |
+| 编译缓慢 | 全量构建 45 分钟 | 开发体验差，CI 队列拥堵 |
+| 故障扩散 | 商品模块 OOM 导致全站不可用 | 年度 P0 事故 4 次 |
+| 扩展受限 | 订单高峰需要整体扩容 | 资源浪费 70%+ |
+| 技术锁定 | 所有模块必须用同一框架版本 | 无法引入新技术栈 |
+
+### 1.3 迁移目标
+
+- 核心域独立部署、独立扩容
+- 发布频率提升到每日多次
+- 单模块故障不影响全站
+- 构建时间降到 5 分钟以内
+
+---
+
+## 二、挑战
+
+### 2.1 技术挑战
+
+1. **数据耦合深重**：120 张核心表之间存在 340+ 外键关联，模块间直接 JOIN 查询超过 600 处
+2. **分布式事务**：订单-库存-支付流程涉及 3 个模块的强一致事务
+3. **共享状态**：Session 存储在本地内存，HttpSession 有 40+ 处直接读写
+4. **代码纠缠**：通过 IDE 分析，模块间循环依赖 87 处
+5. **基础设施空白**：无容器化经验，无服务发现/治理能力
+
+### 2.2 组织挑战
+
+1. **团队无微服务经验**：28 人团队中仅 3 人有微服务项目经历
+2. **业务不能停**：迁移期间平台日交易额 2000 万+，不允许长时间停服
+3. **时间压力**：管理层要求 18 个月内完成，双十一前必须稳定
+4. **知识断层**：核心开发者 2 人已离职，部分模块无人完全理解
+
+### 2.3 数据挑战
+
+1. 单库 2.8TB 数据需要拆分到独立数据库
+2. 报表系统依赖跨模块 JOIN，涉及 15 个核心报表
+3. 历史数据迁移不允许丢失
+4. 迁移期间新旧系统数据一致性保障
+
+---
+
+## 三、方案选择
+
+### 3.1 方案对比
+
+| 方案 | 优势 | 劣势 | 风险 |
+|------|------|------|------|
+| 大爆炸重写 | 架构最优 | 周期长、风险极高 | 业务中断 |
+| Strangler Fig | 渐进式、可回滚 | 需要维护双系统 | 一致性复杂 |
+| 模块化单体 | 改动最小 | 无法独立部署 | 收益有限 |
+| 领域驱动拆分 | 边界清晰 | 需要深入理解业务 | 建模门槛高 |
+
+### 3.2 最终决策
+
+选择 **Strangler Fig Pattern + DDD 领域驱动设计**，理由：
+
+1. 业务不能停，必须渐进式替换
+2. DDD 划分确保拆分边界合理
+3. 可逐步验证每个微服务的稳定性
+4. 允许团队在实践中积累微服务经验
+
+### 3.3 技术栈选型
+
+| 组件 | 选型 | 理由 |
+|------|------|------|
+| 服务框架 | Spring Cloud 2022 + Spring Boot 3 | 团队 Java 背景，学习成本最低 |
+| 服务网关 | Spring Cloud Gateway | 统一入口，灰度切流 |
+| 服务发现 | Nacos 2.x | 注册中心 + 配置中心一体 |
+| 服务通信 | gRPC（内部）+ REST（外部） | 内部高性能，外部兼容性 |
+| 消息队列 | RocketMQ 5.x | 事务消息支持，团队有经验 |
+| 链路追踪 | SkyWalking | Java 生态原生，零侵入接入 |
+| 容器编排 | Kubernetes 1.27 | 行业标准，云厂商支持好 |
+| Service Mesh | Istio 1.18 | 流量治理，灰度发布 |
+
+---
+
+## 四、实施步骤
+
+### 4.1 第一阶段：基础设施准备（第 1-3 月）
+
+**目标**：搭建微服务基础设施，团队能力建设
+
+```
+里程碑：
+Week 1-2:  Kubernetes 集群搭建（3 Master + 12 Worker）
+Week 3-4:  CI/CD 流水线迁移（Jenkins → GitLab CI + ArgoCD）
+Week 5-6:  Nacos/SkyWalking/RocketMQ 部署与调通
+Week 7-8:  Istio Service Mesh 部署与流量验证
+Week 9-12: 团队培训（微服务设计 + K8s 运维 + DDD 工作坊）
+```
+
+**关键实践**：
+- 搭建完整的 Staging 环境，与生产 1:1 映射
+- 编写《微服务开发规范》和《服务拆分指南》
+- 每周一次 DDD 领域建模工作坊，全员参与
+
+### 4.2 第二阶段：领域建模与试点拆分（第 4-6 月）
+
+**目标**：完成领域划分，试点拆分第一个微服务
+
+**领域划分结果**：
+
+```
+核心域：
+├── 商品域（Product Context）     → product-service
+├── 订单域（Order Context）       → order-service
+├── 支付域（Payment Context）     → payment-service
+├── 库存域（Inventory Context）   → inventory-service
+└── 用户域（User Context）        → user-service
+
+支撑域：
+├── 物流域（Logistics Context）   → logistics-service
+├── 营销域（Promotion Context）   → promotion-service
+├── 搜索域（Search Context）      → search-service
+└── 通知域（Notification Context）→ notification-service
+
+通用域：
+├── 认证域（Auth Context）        → auth-service
+├── 文件域（File Context）        → file-service
+├── 配置域（Config Context）      → config-service
+└── 审计域（Audit Context）       → audit-service
+```
+
+**试点选择**：通知服务（Notification Service）
+
+选择理由：
+1. 业务逻辑独立，与其他模块耦合度最低
+2. 非核心链路，出问题影响可控
+3. 边界清晰，短信/邮件/站内信三个子域
+4. 团队可通过试点积累实战经验
+
+**试点实施步骤**：
+
+```
+Step 1: 在单体中抽取 NotificationFacade 接口
+Step 2: 新建 notification-service 独立工程
+Step 3: 实现 Facade 接口的微服务版本
+Step 4: 通过 API Gateway 灰度切流（1% → 10% → 50% → 100%）
+Step 5: 验证稳定后删除单体中的通知代码
+```
+
+### 4.3 第三阶段：核心域拆分（第 7-12 月）
+
+**目标**：完成 5 个核心域的拆分
+
+**拆分顺序与策略**：
+
+```
+Month 7:  用户服务（User Service）
+          - 抽取用户注册/登录/资料管理
+          - Session 改造：本地 Session → Redis + JWT
+          - 影响面：全站登录态，需全量回归
+
+Month 8:  商品服务（Product Service）
+          - 抽取商品 CRUD / SKU / 分类管理
+          - 数据库拆分：商品相关 35 张表迁移到独立库
+          - 引入 CQRS：写操作走主库，搜索走 Elasticsearch
+
+Month 9-10: 库存服务（Inventory Service）
+          - 抽取库存扣减/预占/回补逻辑
+          - 最复杂部分：分布式库存扣减一致性
+          - 方案：TCC 事务（try-confirm-cancel）+ 最终一致性
+
+Month 11: 订单服务（Order Service）
+          - 抽取下单/取消/退款流程
+          - Saga 编排模式处理长事务
+          - 引入 RocketMQ 事务消息保证最终一致
+
+Month 12: 支付服务（Payment Service）
+          - 抽取支付/退款/对账逻辑
+          - 独立支付网关，PCI DSS 合规隔离
+          - 幂等设计防止重复支付
+```
+
+**Strangler Fig 切流策略**：
+
+```
+每个服务切流步骤一致：
+Day 1:   部署微服务 + 影子流量验证
+Day 2-3: 灰度 1%，观察错误率/延迟/日志
+Day 4-5: 灰度 10%，压测验证承载能力
+Day 6-7: 灰度 50%，准备回滚预案
+Day 8:   灰度 100%
+Day 9-14: 稳定性观察期（14天）
+Day 15:  删除单体中对应代码
+```
+
+### 4.4 第四阶段：支撑域拆分与治理（第 13-16 月）
+
+**目标**：完成剩余服务拆分，建立服务治理体系
+
+- 按优先级拆分搜索、物流、营销等支撑域服务
+- 建立统一的服务治理仪表盘
+- 实现熔断（Sentinel）、限流、降级策略
+- 建立全链路灰度发布能力
+
+### 4.5 第五阶段：清理与优化（第 17-18 月）
+
+**目标**：下线单体应用，全面进入微服务架构
+
+- 删除单体应用残余代码
+- 统一监控告警体系
+- 编写运维手册和故障应急预案
+- 全链路压测，验证双十一承载能力
+
+---
+
+## 五、关键技术难点与解决方案
+
+### 5.1 分布式事务：订单创建流程
+
+**问题**：下单涉及订单创建 + 库存扣减 + 优惠券核销，三个服务需要事务一致
+
+**方案**：Saga 编排模式 + 事务消息
+
+```
+正向流程：
+1. Order Service: 创建订单（PENDING）
+2. → 发送 RocketMQ 事务消息
+3. Inventory Service: 扣减库存
+4. Promotion Service: 核销优惠券
+5. Order Service: 更新订单状态（CONFIRMED）
+
+补偿流程：
+- 库存扣减失败 → 取消订单
+- 优惠券核销失败 → 回补库存 → 取消订单
+- 超时未完成 → 定时任务扫描 PENDING 订单 → 触发补偿
+```
+
+### 5.2 数据库拆分：双写过渡
+
+```
+阶段 1: 单体写旧库 → 同步到新库（binlog 同步）
+阶段 2: 单体双写（旧库为主）→ 对账校验
+阶段 3: 微服务双写（新库为主）→ 对账校验
+阶段 4: 微服务单写新库 → 旧库只读归档
+```
+
+### 5.3 跨服务查询：报表系统改造
+
+**问题**：15 个核心报表依赖跨 5 个库的 JOIN 查询
+
+**方案**：引入数据中台（基于 ClickHouse）
+
+```
+各微服务 → binlog/消息 → 数据同步服务 → ClickHouse 宽表
+报表系统直接查询 ClickHouse，不再依赖业务库
+```
+
+---
+
+## 六、结果数据
+
+### 6.1 核心指标对比
+
+| 指标 | 迁移前 | 迁移后 | 改善幅度 |
+|------|--------|--------|----------|
+| 发布频率 | 2 周一次 | 日均 8 次 | 56x |
+| 构建时间 | 45 分钟 | 3-5 分钟 | 9x |
+| 部署时间 | 4 小时 | 8 分钟 | 30x |
+| P0 事故/年 | 4 次 | 0 次 | -100% |
+| 故障恢复时间 | 45 分钟 | 5 分钟 | 9x |
+| 资源利用率 | 25% | 68% | +172% |
+| 峰值 QPS | 12,000 | 85,000 | 7x |
+| P99 延迟 | 1.2s | 180ms | 6.7x |
+
+### 6.2 组织效能
+
+| 指标 | 迁移前 | 迁移后 |
+|------|--------|--------|
+| 需求交付周期 | 3-4 周 | 3-5 天 |
+| 代码冲突频率 | 日均 12 次 | 日均 0.3 次 |
+| 新人上手时间 | 4 周 | 1 周（只需了解所属服务） |
+| 独立团队数 | 1（共享代码库） | 6（每个域一个团队） |
+
+### 6.3 成本
+
+| 项目 | 金额 |
+|------|------|
+| 基础设施投入 | K8s 集群 + 中间件：120 万/年 |
+| 团队培训 | 外部顾问 + 内部培训：35 万 |
+| 迁移期额外人力 | 6 人月（3 名外包）：36 万 |
+| 节省的服务器成本 | 资源利用率提升节省 80 万/年 |
+| **净收益（首年）** | **-111 万（投入期）** |
+| **净收益（第二年起）** | **+80 万/年** |
+
+---
+
+## 七、经验教训
+
+### 7.1 做对的事
+
+1. **先试点再推广**：通知服务的试点让团队积累了完整的微服务实战经验，后续核心域拆分效率提升 3 倍
+2. **Strangler Fig 渐进切流**：每个服务从 1% 灰度开始，累计发现 23 个兼容性问题，均在全量切流前修复
+3. **领域建模先行**：花 2 个月做 DDD 工作坊看似慢，但避免了后期因边界不清导致的返工
+4. **基础设施先行**：先花 3 个月搭好 K8s + 可观测性，让后续每次切流都有充分的数据支撑决策
+5. **双写 + 对账**：数据库拆分期间的双写对账机制发现了 17 处数据不一致，全部在切流前修复
+
+### 7.2 做错的事
+
+1. **低估了分布式事务复杂度**：最初计划用 Seata AT 模式，实测性能不满足要求，切换到 Saga 模式额外花了 1 个月
+2. **缺少 API 版本管理**：早期微服务之间通过 gRPC 直连，接口变更导致多次联调失败，后来才引入 Proto 版本管理
+3. **监控体系建设滞后**：第 7 个月才建完整的 Dashboard，前期切流决策主要靠人工判断
+4. **测试覆盖不足**：集成测试和契约测试建设太晚，前 3 个服务上线时靠手工回归
+
+### 7.3 关键认知
+
+- 微服务不是银弹，拆分粒度过细会引入更多的分布式复杂度
+- 基础设施投入是前提，没有可观测性的微服务比单体更危险
+- 组织结构必须跟着架构调整（康威定律），否则拆了也白拆
+- 数据拆分是最难的部分，比代码拆分难 3 倍以上
+
+---
+
+## Agent Checklist
+
+在 AI Agent 辅助执行类似微服务迁移项目时，应逐项确认：
+
+- [ ] **领域分析**：是否完成了领域建模，明确了 Bounded Context 和上下文映射
+- [ ] **依赖图谱**：是否生成了模块间依赖关系图，识别了循环依赖
+- [ ] **拆分顺序**：是否按耦合度从低到高排列拆分顺序
+- [ ] **试点选择**：首个拆分目标是否为非核心、低耦合模块
+- [ ] **基础设施**：K8s / 服务发现 / 配置中心 / 链路追踪是否就绪
+- [ ] **灰度切流**：是否建立了从 1% 到 100% 的渐进切流机制
+- [ ] **回滚预案**：每次切流是否有明确的回滚步骤和触发条件
+- [ ] **数据迁移**：数据库拆分是否有双写 + 对账机制
+- [ ] **分布式事务**：跨服务事务是否有明确的一致性方案（Saga/TCC/事务消息）
+- [ ] **API 契约**：服务间接口是否有版本管理和契约测试
+- [ ] **监控告警**：是否建立了服务级 SLO 和告警规则
+- [ ] **压测验证**：每个服务上线前是否通过了全链路压测
+- [ ] **团队培训**：团队是否具备微服务开发和运维能力
+- [ ] **文档齐全**：运维手册 / 故障预案 / 架构决策记录是否完整
+- [ ] **成本评估**：是否计算了迁移期总成本和预期收益周期