Roger Knowledge hub

Appearance

Return to top
On this page

一次代码重构的思考

← 返回专题记录

背景

系统是一个运行超过 20 年的老项目。由于历史原因，部分功能存在代码重复、结构混乱、可维护性差的问题。同一个 bug 经常需要在多个地方反复修改。

为了减少长期维护成本，我们决定主动治理这类技术债。但老系统的修改必须谨慎：任何改动都可能影响现有功能，因此需要一套低风险、可验证、渐进式的重构方法。

最初并没有完整的方案，而是在实践中逐步总结出的一套工作方式。本文记录关键步骤和经验，供后续类似考古工作参考。

方法

1. 定义问题：理解现状，识别重构点

  • 使用 AI 工具辅助分析代码，标记出重复高、复杂度高的区域。
  • 梳理核心流程（如上传/下载）中的校验规则和行为逻辑，作为后续验证依据。
  • 提取关键行为模式（如 diagram 批量、network 批量）及其初始化方式，明确哪些部分必须保持兼容。

目标不是让 AI 理解全部，而是帮助我们快速建立对现有结构的认知。

2. 制定方案：明确重构策略

  • 基于分析结果，提出具体措施：
    • 拆分职责，推动代码分层；
    • 统一命名，消除歧义；
    • 合并重复的 UI 组件（如 TargetPanel、AccessibleDeviceTablePanel）；
    • 将错误提示、进度反馈等交互逻辑集中处理。

3. 方案审核：评估风险

结合对业务和架构的理解，判断：

  • 修改是否会影响现有调用方？
  • 是否引入新的隐式依赖？
  • 出现问题能否快速回滚？

4. 执行过程：小步推进，控制范围

  • 任务拆分：按依赖关系拆成最小可独立验证的单元，避免上下文过大。
  • 边改边测：每个小模块完成后立即自测并做 Code Review。
  • 复杂模块先分析：对大类（如 800 行以上的类）先画类图，理清内部结构。
  • 重构顺序：
    • 先处理独立模块，再处理耦合模块；
    • 组合逻辑先拆内部，再整合外部；
    • 大类先拆分为组合结构，待职责清晰后再考虑合并。

5. 验证结果：交付可维护的成果

  • 代码：结构清晰、职责单一、重复减少；
  • 行为清单：列出关键场景的预期行为，用于测试覆盖；
  • 文档：说明新结构的设计意图和模块关系，降低后续理解成本。

案例

在实际操作中，我们发现有两个几乎相同的包结构，分别用于向导（wizard）和对话框（dialog），包含重名类如 TargetPanel 和 AccessibleDeviceTablePanel。

最初尝试将所有相关代码一次性交给 AI 分析，但很快遇到问题：

  • 上下文过长，对话频繁中断；
  • AI 输出信息量大，需人工逐条甄别；
  • 交互过程中容易遗漏细节。

于是我们调整策略：控制上下文规模，分阶段处理。

  1. 先合并最独立的 ConnectTypePanel；
  2. 再处理 TargetPanel 的子组件 AccessibleDeviceTablePanel；
  3. 对大类进行内部拆解：将重复逻辑提取为组合对象，逐步缩小原类体积；
  4. 待结构清晰后，完成跨上下文的最终合并。

过程中也发现：AI 在上下文受限时给出的建议有时不够全面，因为丢失了全局视野，很多改动并不合理。但由于改动范围小，我们能及时识别并修正。

最终，我们将两套结构统一为一个 target 包，通过以下方式提升内聚性：

  • 引入 DeviceTableInterface 解耦回调；
  • 用静态类 Defaults 管理不同场景的默认配置；
  • 将 I/O 逻辑抽离到 DeviceTableIoService；
  • 服务类（如 DeviceAvailabilityService）独立封装业务逻辑。

这次整理过程中还配套画了类图，用来帮助理解拆分前后的结构变化。

反思

这次重构让我对人与 AI 的协作有了更务实的认识：

1. AI 是辅助工具，不是替代品

不能指望 AI 自动生成完整方案。它的价值在于加速理解、减少重复劳动，但关键判断仍需人来做。

2. 分治是应对复杂性的有效方法

无论是架构设计还是 AI 协作，把大问题拆成小问题，才能保证每一步可控。所谓“大力出奇迹”在工程实践中往往不可靠。

老生常谈了，架构也是一样，包括微服务。越庞大的系统，越需要分治的思想来降低认知负荷和执行难度。对 AI 也适用。比如我们常见的一句话需求：“我要做个 XXX 系统。”严谨的做法也是需要进行 ABCD 分解：业务建模、需求、分析、设计。每个流程又继续分治，直到场景足够小的时候，上下文也可以做到足够清晰，对 AI 和自己都能很好地降低难度。

为什么会出现 agent 军团、Claude 的架构设计，本质上也是这些原因。“大力出奇迹”的思路我认为是不对的，俗话说样样通样样松。

3. 上下文治理

AI 的输出质量高度依赖上下文。未来好的 AI 产品应该能结构化地管理产品上下文——包括用户习惯、特定领域知识等等，而不是每次从零开始。

这是我对未来 AI 产品方向的一个预判：一定是基于上下文的治理。上下文就是领域知识，就是具体场景的前提。在编码里，上下文就是其他类的代码、整体项目的架构设计、规范约束；在 Claude 里，上下文就是用户记忆，这些都是上下文。AI 好不好用，很大程度上取决于这个。

除了对一件事的整体分治、结构化，上下文也一样，需要详细的结构化治理。每个流程、活动需要的上下文不一样，类似 RUP 4+1 模型，每个流程的视角和关注点不一样。上下文治理就像星型模型的建立一样，不是凭空生成，而是根据一个事实模型，来做多维度转换。这些知识作为垂直领域 AI 的底座，才能更好地驱动 AI 去完成垂直领域的场景。