用 claude code 将单体应用拆分成微服务的代码重构

去年秋天，我把一个跑了四年的电商后台单体应用拆成了七个微服务，全程用 Claude Code 辅助。拆分完之后，部署时间从 11 分钟降到 2 分 40 秒，但有个前提我必须先说，这次重构最值钱的不是 Claude Code 帮我写了多少行代码，而是它帮我避免了三处差点让订单系统挂掉的架构失误。如果你以为这篇文章是要教你“如何一键让 AI 帮你拆服务”，现在就可以关掉。我想讲的是一个真实得多的故事：工具很好，但真正决定重构成败的是你画的那几道线。

结论先行：Claude Code 在重构中的角色，多数人想错了

我把话说得直白一点：Claude Code 在这个项目里的核心价值，60% 在分析阶段，30% 在模拟验证阶段，只有 10% 在生成代码阶段。 这个比例不是我凭空说的，而是我在六个模块的拆分过程中记录的实际时间分配。

大多数人拿到这个工具的第一反应是，让它帮我生成微服务代码、生成 Dockerfile、生成 k8s 配置。这些它都能做，而且做得不错。但如果你只把它用在这个层面，就好比你买了一台 MRI 扫描仪，却只用来量体温。

真正让我省掉一半重构时间的，是 Claude Code 在三个环节的表现：

第一，它能同时追踪 47 个类之间的 200 多条依赖关系，在 20 秒内给我画出调用图谱，而这件事如果让我手动画，至少得对着 IDE 的 Find Usages 盯两个小时。

第二，它能在我还没写一行拆分代码之前，模拟微服务之间的异步事件流，帮我提前发现“支付挂掉之后库存扣了对不对”这种边界场景。

第三，它能基于我的现有单体代码生成 OpenAPI 规范草案，让我在正式拆分前就把服务契约定下来，而不是拆完之后才发现“原来这两个模块的接口设计互相矛盾”。

所以这篇文章的核心观点是：用 Claude Code 做单体拆分，最重要的不是让它替你写代码，而是让它在代码还没动之前，帮你把架构看清楚、把边界画明白、把风险预演完。

背景：一个四岁单体，为什么到了不得不拆的节点

先交代项目背景。这个电商后台系统是 2021 年用 Spring Boot 写的，最初只有订单和商品两个模块。四年间，陆续加上了库存、支付、会员、营销和报表，代码量从初始的 3 万行涨到 16 万行。

到 2024 年中，我们开始频繁踩到这些坑：

部署耦合让人抓狂。 测试环境每次发版，改了营销模块的一个推荐算法，结果整个应用重新部署，所有模块的缓存都要重建，预热时间比部署本身还长。

数据库连接池告急。 报表模块的 SQL 动不动全表扫描，高峰期抢走 70% 的连接池，导致订单创建排队。运维同事加连接池加到极限也没用，因为本质上是计算资源和事务资源的竞争。

团队协作撞墙。 六个人在同一个代码仓库上并行开发，merge conflict 的解决时间快赶上实际写代码的时间了。每个人都不敢做大的重构，因为一改就可能影响别人。

这些痛点有没有数据支撑？有。拆之前的监控数据：订单接口 P99 延迟从 2024 年初的 340ms 恶化到 11 月的 890ms，库存扣减的 DB 死锁率从每周 3 次上升到每周 11 次。

11 月的一个凌晨，订单服务挂了 40 分钟，因为报表模块的一个慢查询把整个数据库拖崩了。第二天技术 VP 拍板：拆。

误区：如果你以为拆服务就是拆模块，后面有坑等着你

决定拆之后，我最先想的是一个技术博主说过的话：“微服务拆分就是把单体代码里的模块一个个拆出来，每个部署一个独立的服务就行了。” 这句话对了一半，错了一半，错的那一半，足够让你在生产环境上摔一跤。

我在正式动代码之前，先用 Claude Code 做了三天的分析。这三天让我发现，很多所谓的“常识”其实是经验之谈，而经验在另一个项目里不成立。

误区一：“按项目现有的代码目录结构拆就行了”。

单体应用里，大家通常按功能分 package：order、product、inventory、payment。很多人觉得，把这四个 package 拆成四个服务就完事了。我用 Claude Code 一分析才发现，order 包里的某个类引用了 inventory 包里的两个 repository，product 包又用了 inventory 的 service，真实依赖关系根本不在 package 层面，而在具体的方法调用链上。

Claude Code 帮我画了一张依赖图谱，其中有一个“上帝类”，InventoryManager，同时被订单、商品、支付、营销四个模块调用，而且调用场景各不相同。如果直接按目录拆，这个类不管放到哪个服务里，其他服务都会缺一块逻辑。

误区二：“先拆代码，API 可以后面再对齐”。

这是一个很自然的想法，反正以前模块之间也是通过 Service 调用，拆成微服务之后换成 HTTP 不就行了？但真正拆起来你才会发现，Service 调用和 API 调用完全是两套逻辑。

举一个我从项目里踩到的坑：原来的 OrderService.createOrder 方法，内部调用了 InventoryService.deductStock，而且这个调用是在事务里的。你把它改成 HTTP 调用之后，deductStock 失败了，订单的本地事务已经提交了，怎么回滚？这些“分布式事务”问题不是 API 格式的问题，是方法论的问题。

误区三：“用 AI 重构就是快，让它自动化处理就行”。

这个误区最危险。我实测过，完全让 Claude Code 自动拆分一个中型模块，它确实能生成可以编译通过的代码，但出现了三个问题：数据库 Schema 拆分不合理，把应该留在同一个库里的表分开了；缓存 Key 的命名规则不统一；异步消息的消息体结构缺乏幂等字段。

Claude Code 是放大器，不是替代品。 你给它模糊的指令，它给你模糊的结果；你给它清晰的架构约束，它帮你执行出高质量的输出。区别全在你那几行 prompt 和目标规格说明。

第一道线：依赖解构，在写任何代码前，先画清领域边界

我对边界划分的方法论来自于领域驱动设计，但 Claude Code 让这个方法论的落地效率提升了不止一个量级。

具体怎么做的？我把我当时的操作步骤列出来，可以直接复用：

步骤 1：用 Claude Code 生成调用关系矩阵。

我当时的 prompt 是这一句：“分析整个项目，列出所有类之间的依赖关系，并标识出循环依赖和‘上帝类’。” 这句话的重点是“上帝类”这个术语，因为 Claude 能理解这个架构概念，会自动过滤出被超过三个以上模块同时依赖的类。

结果出来之后我看到了一个让我后背发凉的事实：InventoryManager 这个类被引用了 37 次，来自 14 个不同的类，分布在 5 个 package 里。它做了三件事：库存扣减、库存预留和库存同步。严格来说，这是三个独立的职责。

步骤 2：基于职责聚类，重新画边界。

我让 Claude Code 把 InventoryManager 的 37 个调用点按“调用目的”分类，结果分成三个簇：扣减类 21 个、预留类 9 个、同步类 7 个。每一簇内部的调用链高度内聚，跨簇的调用几乎没有。这就是领域边界，不是靠直觉画的，是靠数据画的。

步骤 3：验证跨边界调用是否真的需要同步。

Claude Code 在这里帮了我一个大忙。我把三类调用点的业务场景列举出来，让它逐个分析“这个调用是否必须同步执行”。结果发现，扣减类 21 个中有 16 个必须在订单创建时同步执行，但同步类的 7 个全都可以在库存变更后异步发布事件。

这个结论直接决定了我的架构设计：库存扣减作为核心能力留在订单服务里用同步调用，库存同步独立成一个异步事件处理器。

这个分析过程，Claude Code 完成了繁重的“找东西”的工作，但“这件事应不应该同步”这个判断，必须由你来做。为什么呢？因为它不知道你的业务容忍度。我们的库存数据允许 200 毫秒内的最终一致性，但有的电商系统不行。这个阈值是人的决定。

第二道线：API 契约，先定合同再搬代码

很多人拆分微服务的时候，代码拆出来了，但是 API 格式是边开发边定的。如果两个服务由不同的开发者负责，等联调的时候会发现两边的理解根本对不上。我在这个项目里用的方式是：在微服务的第一行代码还没写之前，把 API 契约先定好。

Claude Code 在这个环节能做一件传统方法不好做的事：它能扫描现有的代码，把模块之间的隐式“接口”挖出来，然后用 OpenAPI 3.0 格式描述清楚。

操作步骤是这样：

第一步，我让它分析订单模块和库存模块的现有代码交互点。它扫描了 OrderService 对 InventoryService 的所有调用，一共 9 个方法。然后它把这 9 个方法按语义归类，查询库存、扣减库存、释放预留、同步库存状态，然后映射成 REST 资源。

第二步，我让它基于这 9 个方法生成 OpenAPI 3.0 规范，要求明确的请求体、响应体和错误码。它生成的规范里有一个细节让我觉得很有价值：它自动识别出 deductStock 方法的参数里有一个 deductType 枚举值，这个枚举在代码里没有显式的文档说明，它是通过追踪所有调用点逆推出来的。

第三步，也是最关键的一步，我把这个 OpenAPI 文件给所有相关开发者 review，在代码还没写的时候就把接口约定下来。凡是和 OpenAPI 不一致的实现，在上线评审阶段就会被发现。

这里我总结一个表格，展示传统方式和“契约先行”方式的效率差异：

这个表格不是编出来的，是我在这个项目里同时经历过两种方式之后做的实际对比。前两个模块我用了传统方式，联调了三天；后四个模块我用契约先行，联调加起来没超过一天。

第三道线：数据拆分，这是最容易出事的地方

如果说 API 设计不当会导致联调困难，那数据拆分不当会直接让系统不可用。我在这个项目里最大的教训，就发生在这个环节。

核心原则一句话：服务拆分之后，数据库也应该被拆分，不能多个服务共用一个数据库。 但这句话执行起来非常难。单体应用里，所有的表都在一个库里，SQL 可以随意 JOIN，事务可以跨表自由控制。拆库之后，你之前随便写的一条 SQL，可能就成了跨服务的分布式查询。

我用 Claude Code 处理这个环节，核心手法就一个：让它扫描代码里所有的 SQL 和 ORM 调用，分析出“表亲和度”。

具体做法：我把项目里所有的 Repository 和 DAO 文件作为上下文，让 Claude Code 分析这些数据访问层中，哪些表总是作为一组出现在同一条 SQL 或同一个事务里。

分析结果出来之后，我发现了三个很有意思的表簇：

第一个簇是订单表、订单项目表、订单日志表，这三张表几乎在所有 SQL 里都同时出现，JOIN 了不下 15 次。这个簇天然应该归属到订单服务。

第二个簇是用户表、用户地址表和会员等级表，绑定在用户服务里。

问题出在第三个簇：库存表、库存流水表和商品 SKU 表。 这三张表在库存扣减场景下紧密绑定，但在商品查询场景下，SKU 表又和商品详情表强绑定。这意味着库存服务需要 SKU 数据，商品服务也需要 SKU 数据，数据出现了“共享依赖”。

这个发现让我做出了一个设计决策：SKU 表在商品服务里保留主副本，库存服务保留一个只读的冗余副本，通过商品服务发布的事件来同步更新。 这在 CAP 理论里属于牺牲了强一致性换取可用性和分区容忍性，但业务上可以接受。Claude Code 的价值在于，在我做决策之前，它帮我看到了这个共享依赖。

还有一个容易被忽略的点：外键约束。 拆库之后，跨库的外键必须砍掉，但谁砍、在哪个阶段砍，决定了你上线后会不会出现数据孤儿。我的做法是让 Claude Code 先列出所有涉及外键的表和字段，然后逐个分析砍掉外键之后需要同时在应用层加上哪些数据一致性检查。这个环节如果完全靠人肉检查，漏掉一两个外键的概率很高。

第四道线：状态流转与异常预演，别等上线才发现兜底没写

很多人把重构的难度集中在“拆”上，但真正让我紧张的，是拆完之后系统能不能在各种异常场景下自保。

单体应用时代，异常处理相对简单，事务回滚就行了。拆成微服务之后，一个业务操作可能跨越三四个服务，某个中间环节失败了，前面成功的步骤怎么补偿？这些逻辑如果在设计阶段不预演，等到线上出问题只能手动修数据。

我在这个环节用 Claude Code 的方式比较独特：我让它扮演“系统崩溃模拟器”。

我给它输入了拆分后的服务拓扑和主要业务流程图，然后给它一系列假设性提问：

“如果支付服务在处理支付回调的时候挂了，订单服务和库存服务各自应该收到什么事件？”

“如果库存扣减成功了但订单创建失败，扣减的库存应该在多少秒内释放？”

“如果消息队列积压，支付成功的通知延迟了五分钟，系统状态是否还能保持一致？”

这些问题，它不会直接给你“正确的答案”，因为答案取决于业务规则。但它会帮你画出每一种异常场景下的状态流转路径，告诉你哪些路径上缺少兜底逻辑。

举一个真实的例子：我对它提了“支付挂掉”这个场景之后，它指出我设计的 Saga 编排里漏了一种情况，支付超时（不是失败，是超时）。支付服务的回调迟迟没来，订单服务在设置了超时定时器之后会取消订单，但这个取消动作没有触发库存释放事件。这是因为我只设计了“支付成功”和“支付失败”两条路径，忽略了“不确定”的状态。上线前修复这个问题，成本几乎为零；上线后才发现，那就是生产事故。

这个预演环节我花了整整一天，但我觉得这是整个重构过程中最值得的一天。代码可以重构，但数据写坏了是不可逆的。

实操：重构执行阶段的顺序、分工和真正该让 Claude Code 做的事

前面三道线画完之后，真正动手拆代码的阶段反而是整个项目里相对简单的部分。但我还是想把这个阶段的经验和教训讲清楚，因为这个环节很多人容易陷入两个极端：要么全部交给 AI，要么完全手工，效率最低的是“让它写一点，你改一点，来回拉扯”。

我最终采用的拆分顺序是这样的：

1. 先拆无状态的独立模块（报表服务、营销服务），这些模块没有写操作，出问题的代价最低。
2. 再拆读写混合但边界清晰的模块（会员服务、商品服务）。
3. 最后拆核心交易链路上的模块（库存服务、支付服务、订单服务），这些模块的拆分风险最高，需要前面积累足够的工具链经验和信心。

这个顺序不是随意定的。前两个梯队拆分时，我会积累 Claude Code 的 prompt 模板、测试用例模式和部署配置模板。到了第三梯队，这些模板已经被打磨得很成熟，出错的概率大幅降低。

Claude Code 在代码迁移阶段帮我做的具体事情：

• 代码拉取：给定一个类列表，它能逐个把相关文件迁移到新的服务仓库，同时自动处理 import 路径的调整。
• 配置拆分：原来的 application.yml 有 400 多行，它帮我按服务拆分，去掉了每个服务不需要的配置项。
• 测试用例迁移：这是最耗时的体力活，它有 80% 的测试可以直接迁移，剩下 20% 需要改 mock 对象，Claude Code 会标注出来让你人工处理。
• Dockerfile 和 CI/CD 脚本：从单体的一份拆成七份，它帮我保证了每份之间的结构一致性。

我不让它做的事：

• 数据库的 DDL 变更：涉及线上数据的 ALTER TABLE，我全部手工写并经过 DBA review。
• 核心业务逻辑的重写：比如库存扣减的并发控制从悲观锁变成分布式锁，这个决策和实现都是我自己做的，Claude Code 只负责生成单元测试来验证并发安全性。

取舍：哪些模块应该拆，哪些应该留，以及为什么

写完前面的内容，可能会有一个印象，好像所有模块都应该拆。但实际上，我在这个项目里做了几个明确的“不拆”的决定，这些决定事后证明都是对的。

没有拆的第一个东西：用户认证和鉴权模块。

原因很简单，用户登录、Token 验证、权限校验这些逻辑，几乎被所有模块依赖。如果把认证拆成独立服务，意味着每次调用都要多一次网络往返。在我们的场景中，这个延迟增加不值得。我把认证逻辑作为一个公共库，每个服务引入，但鉴权数据的更新通过发布-订阅模式同步。这是“代码级复用”和“服务级复用”的取舍。

没有拆的第二个东西：配置中心本身还没来得及引入之前，不拆基础设施相关的模块。

我们这个项目当时还没有 Apollo 或 Nacos，如果先把应用拆了，配置文件散落在七个仓库里，运维成本会急剧上升。所以我等到拆完之后的第一周，先把配置中心搭好了，才把各个服务的配置迁移过去。

主动拆了一个别人可能会留的东西：定时任务。

原来的单体里有一个定时任务模块，里面有七套不同的定时任务逻辑，分别服务于不同的业务。我把这个模块拆开了，每个服务的定时任务归各自的仓库管理。这样改需求时不用拉全量的代码，部署时的风险面也更小。代价是需要在监控层面统一管理这些分散的任务，我用了一个轻量级的任务管理平台来解决。

关于拆与不拆的决策矩阵，我总结了一个简单但实用的判断框架：

这个矩阵不是什么权威理论，是我在这个项目里反复纠结“拆还是不拆”的时候，和团队一起定的判断标准。如果你也面临同样的决策，可以参考这个框架，但你的答案应该基于你的业务上下文来调整。

上线策略：灰度、回滚和“最后一刻的检查清单”

拆了七个服务，最紧张的不是拆分的过程，而是上线的那个晚上。在单体应用时代，上线就是一个部署包的替换。拆了之后，上线意味着七个服务要以正确的顺序、用正确的配置、带着正确的数据库变更，同时（或依次）启动起来。

我的上线策略分了四步走，每一步都有 Claude Code 帮忙生成执行脚本，但脚本必须在测试环境跑过两遍以上才敢用。

第一步：数据库变更先行。 先执行 DDL，保证新表结构已经就位。这时旧单体还在运行，新表的字段要保持和旧表的兼容性。我让 Claude Code 帮我检查了每一个 ALTER TABLE 语句是否会锁表，它通过分析数据量和索引结构来判断。

第二步：灰度切流。 先在网关层把 5% 的流量导向新服务，剩下的继续走旧单体。这一步的关键是监控两个通道的数据一致性。我让 Claude Code 帮我写了一段对比脚本，每次订单创建后，对比新旧两边的库存扣减结果是否一致。

第三步：逐步放量。 灰度跑了两个小时后，从 5% 提到 30%，再提到 100%。每次提量之前，我会检查错误日志和延迟数据。这里有个细节：提量不是手动操作，是通过配置中心的动态路由实时生效的，这个能力比改代码再部署管用得多。

第四步：回滚预案的热键。 我给每个服务都准备了一个回滚开关。一旦新服务出现不可接受的错误率，网关可以在 30 秒内切回旧单体的路由。这个回滚脚本也是 Claude Code 帮我检查过没有遗漏的，我让它模拟了“当某一个服务挂了但其他服务正常时，回滚是否会误伤其他服务”的场景。

上线那晚的实际结果是：有一个小插曲，支付服务的 redis 配置没挂载正确，导致前 5 分钟的缓存没有生效，但应用本身没挂，错误率在千分之三以内，30 秒回滚预案没有触发。修复配置之后一切正常。整个切换过程持续了三个半小时，但实际的新老割接只花了四分钟。前面花的三个多小时，都是按照计划在观察和验证。

反思：哪些事我做对了，哪些事如果再给我一次机会会不一样

重构完成之后我做了一次复盘，和团队一起把整个过程中“值得重复的做法”和“下次可以改进的地方”列出来。这些反思比任何方法论都真实。

做对了的几件事：

第一，我坚持了“分析先于行动”的原则。用 Claude Code 做了三天的依赖分析、边界识别和异常预演，这三天的投入在后续的代码迁移阶段直接省了两周的人天。如果一上来就直接改代码，我见过太多项目是这么做的，做到一半才发现边界画错了，回头改的代价是成倍的。

第二，我没让任何一个开发者独立负责“从单体到微服务的全部迁移”。我让每个人负责一个服务，但数据库拆分的方案是全员 review 过的，API 契约是所有人签字确认的。这让知识不只是集中在一个人脑子里。

第三，我把重构过程记录成了一个内部 wiki，每一步的 prompt、每一步的架构决策和权衡、每一步踩到的坑都记录在案。现在团队里任何一个人要拆新模块，照着这个 wiki 走，犯错率大幅降低。

如果再做一次，我会做的不一样的事：

我不会在拆服务的同一周升级基础组件。我们在这个周期里同时把 Spring Boot 从 2.6 升到了 3.2，把 RabbitMQ 客户端也升级了版本。这样出问题的时候，你搞不清楚是新架构的问题还是组件升级的问题。

我不会把消息中间件的选择放在重构的第一个 sprint 里做决定。RabbitMQ 换到 Kafka 是后来才做的，但这个技术选型的变动导致之前写的一些异步逻辑需要重写。应该先把同步调用拆出来跑通，异步的部分单独作为第二个阶段。

我会更早引入可观测性。拆完之后的第一周，七个服务都起来了，但调用链追踪还没接好，出了问题排查起来比单体时代还费劲。后来把 OpenTelemetry 接上之后，这个痛点才解决。微服务没有好的可观测性，就是瞎子上高速。

工具之外：什么样的团队适合用 Claude Code 做重构

说了这么多，我不想给你一个“Claude Code 是万能的”错觉。这个工具适合特定的人群和特定的场景。

适合的团队画像：

这个团队至少有一个对现有代码有深度理解的人。Claude Code 可以帮你分析代码，但它不知道三年前你为什么把扣减逻辑写在了 Service 层而不是 Domain 层。这个上下文只有人知道，如果团队里没有这样的人，AI 的分析结果可能看起来很对但实际上是错的。

这个团队有基本的架构评审机制。如果你让 Claude Code 生成一个拆分方案就直接上线，风险极高。我们这个项目里的每一步 AI 输出，都有两个人的 Code Review。

这个团队的成员愿意写 prompt 和 review AI 输出，而不是抱着“AI 不可靠所以我不用的心态”，同时也不迷信“AI 生成的都对”。这个平衡感很重要。

不适合的场景：

如果代码质量本身很差，类之间耦合得像意大利面条，先别急着拆微服务，先把内部的结构理顺。Claude Code 在处理这种极端耦合的代码时，给出的依赖分析会非常复杂，复杂到你很难从中提取可执行的拆分策略。

如果业务还在快速试错期，需求的变动导致模块边界频繁调整，这时候拆微服务的维护成本会超过它带来的收益。单体在早期阶段是合理的，不要为了微服务而微服务。

如果团队人数少于三个人，拆微服务带来的运维负担会让你得不偿失。我们是在六个人的团队里拆成七个服务，平均每人负责一两个，这个比例是比较健康的。

结语：工具是放大器，你的判断才是核心

整个重构走下来，从第一天的依赖分析到最后一天的全量上线，历时二十个工作日，七个服务，十六万行代码被重新组织。关键指标上，部署时间从 11 分钟降到 2 分 40 秒，订单接口 P99 延迟从 890ms 降到 210ms，DB 死锁率从每周 11 次降到零，因为每个服务有自己的数据库了。

但我想在最后说的是，Claude Code 改变了重构的效率，但没有改变重构的难度。真正困难的事情，判断边界画在哪里、决定这个操作应该同步还是异步、权衡是不是该为了一致性放弃性能，这些事情仍然需要你来做。

把 Claude Code 当作你身边一个精力无限的编程搭档，它能帮你在 30 秒内做完两个小时的分析工作，能把你的想法快速转化成可运行的代码，能在上线前陪你一遍遍推演异常场景。但它不会替你思考，也不会替你担责任。

所以我的建议是这样的：如果你们的单体应用已经到了该拆的节点，先别急着动手。花两天时间，用 Claude Code 把依赖图画出来，把领域边界跑一遍，把异常场景模拟一次。这两天不会白花，它会让你在整个代码迁移阶段走得又稳又快。

至于下一步怎么做？把你当前项目里被引用最多的前十个类找出来，看看它们分别被哪些模块调用、调用目的是什么、能不能归类。你可能会发现一些你之前没意识到的边界，这些边界就是重构的起点。