HCodeFlow

主题

一个 Java 老手、Python 新手，用 AI 协作在 1 天 内完成了跨语言跨框架的全栈重构。 本文记录完整过程：从规划到执行、从踩坑到规则沉淀，所有数据均来自 git 提交记录。

一、为什么要重构 ​

旧系统的痛点 ​

灵智 AI v1：Java 8 / Spring Boot + 3 个 Vue 2 微前端（qiankun）

痛点表现
代码重复3 套 Vuex / 路由 / Webpack 配置，前端 40%+ 重复
构建缓慢Webpack 冷启动 30-50s
部署复杂4 个独立 CI 任务，任一失败需逐个排查
技术栈老化Java 8（无 record/var），Vue 2 EOL

重构目标 ​

Java 8 / Spring Boot    →  Python 3.12 / FastAPI
3 个 Vue 2 微前端        →  1 个 Vue 3 / Vite 单应用
4 个 CI 任务             →  2 个 CI 任务
Webpack 30-50s           →  Vite 2-3s

为什么敢做？ ​

  • 输入确定：27 张表、135 个 API、58 个页面 — 全部可枚举
  • 输出确定：功能等价迁移，不改业务逻辑
  • 已验证：Flocks 项目已用 Python/FastAPI 跑通

核心判断：功能等价迁移 = 高确定性任务，正是 AI 最擅长的场景。

二、整体策略 ​

Strangler Fig 模式 ​

新旧系统并行运行、Nginx 逐域切流，而非 Big Bang 替换：

  • 零停机 — 新旧服务并行，按域逐步切流
  • 可回滚 — 任何一个域出问题，Nginx 秒切回 Java
  • 数据一致 — 两服务共享同一 MySQL + Redis

分层推进：8 个 Phase ​

正式动手前，先产出 PLAN.md（架构蓝图）和 TASKS.md（69 个可执行任务）：

Phase 0: 项目骨架          ← 所有 Phase 的前提
Phase 1: CRUD 资源管理      ← 27 表 + 131 API，建立模板
Phase 2: V5 网关 + WS      ← 依赖 Phase 1
Phase 3: 定时任务          ← 依赖 Phase 2
Phase F1: 前端骨架         ← 可与 Phase 2/3 并行
Phase F2: 页面迁移         ← 依赖 F1 + Phase 1
Phase 5: 部署上线          ← 所有功能完成后

核心原则：滚动细化 ​

不预先拆完所有任务。每个 Phase 入口先做源码分析再细化：

进入 Phase 1 → AI 读 Java 源码 → 产出分析 Spec → 人审批 → 细化为 13 个子任务 → AI 执行

三、完整时间线（来自 56 个 git commit） ​

7 个关键阶段 ​

阶段时间耗时关键动作产出
① 规划4/17 23:5938 min人 + AI 共同产出 PLAN.md、TASKS.md8 Phase 蓝图 + 69 个任务清单
② 骨架4/18 00:3750 minAI 搭建后端骨架 + 读 Java 源码分析FastAPI 应用 + 源码分析 Spec
③ CRUD01:27 ~ 09:04~8hAI 按模板自动批量生成（人 01:40 去休息）36 文件 / 113 API / 27 表 ORM
④ 偏差修复09:2016 min对比验证发现 5 类偏差 → 提炼规则5 条编码规则写入 .claude/rules/
⑤ 网关 + 任务09:34 ~ 19:09~10hAI 按任务顺序推进 Phase 2 + 3WebSocket + 6 个同步任务 + 19 个烟测
⑥ 前端19:16 ~ 20:1054 min14 页面批量迁移 + 7 通用组件4,309 行 Vue 3 代码
⑦ 部署 + 修复21:09 ~ 次日 12:30—部署流水线 + BUGFIX 8 大问题全量修复Docker + Nginx + UI 美化

几个值得说的时间点 ​

① 规划 38 分钟 — 整个重构最重要的投入

后续 AI 能自主领任务、高速执行，完全依赖这 38 分钟建立的"确定性空间"：

  • PLAN.md — 8 Phase 架构蓝图（技术选型、依赖关系、迁移顺序）
  • TASKS.md — 69 个任务（每任务标记 Phase、优先级、状态，AI 按顺序自动领取）
  • CLAUDE.md — AI 的"工作手册"（会话流程 + 编码规范）

③ AI 自动执行 CRUD — 人休息了 6 小时

01:35 人审批了第一个实体（Platform）的模板，01:40 人离开。次日 07:29 回来时，AI 已继续推进到第 3 个实体。后续实体全部自动套用模板，单个实体 3-5 分钟完成。

④ 偏差修复 16 分钟 — 催生了编码规则飞轮

Phase 1 全量完成后运行对比验证（Python vs Java 同请求），发现 5 类问题。16 分钟修复后，5 条规则写入 .claude/rules/，后续 Phase 2/3 再未出现同类问题。

⑥ 前端 54 分钟完成 14 个页面

核心原因：CRUD Store 工厂 + API 工厂消灭了 70% 的重复代码。每个列表页只需 ~80 行，而 V1 需要 ~300 行。

四、踩坑与规则沉淀 ​

6 类典型偏差 ​

类别发生了什么影响沉淀的规则
跨语言字段映射AI 基于代码推测写 ORM，字段名与实际 DB 不一致5 个字段错误写 ORM 前必须查实际表结构
框架 API 差异Pydantic v2 的字段别名机制与 v1 不同全部序列化输出错误统一使用 alias 模式
异步编程陷阱忘记 await 异步函数，不报错但不工作Redis 操作全部静默失败异步函数必须 await
初始化时机模块级创建 DB 连接，绑定了错误的 event loop测试和多 worker 报错延迟到应用启动时初始化
路由匹配顺序/list 路径被 /{id} 动态路由抢先匹配405 错误固定路由必须在动态路由之前
N+1 查询列表接口循环查询关联数据性能问题批量查询 + map 映射

规则沉淀的飞轮效应 ​

AI 踩坑 → 人发现偏差 → 提炼规则 → 写入 .claude/rules/ → AI 不再犯 → 越写越快
时间点累计规则数效果
Phase 0 完成0AI 自由发挥，踩坑概率高
Phase 1 验证后5字段/序列化/异步三类问题消失
Phase 2 完成后11新增性能、状态机、安全等规则
Phase 3 完成后14规则覆盖全面，后续开发质量稳定

越写越快、越写越准 — 这就是"确定性空间"不断扩大的过程。

五、人与 AI 的分工 ​

角色做了什么花的时间
人写 PLAN.md + TASKS.md（架构决策）~38 min
审批第一个实体模板（Platform）~5 min
发现偏差，提炼编码规则~20 min
审批 Spec + 确认任务顺序~15 min
审批 BUGFIX Sprint 依赖顺序~10 min
小计~88 min
AI源码分析（读 Java 代码，梳理 27 表 135 端点）—
按模板批量生成后端代码（36 文件 113 API）—
前端页面迁移（14 页面 + 7 组件）—
烟测 + 单元测试编写—
BUGFIX-PLAN 依赖分析 + 全量修复—

协作模式 ​

人维护"确定性空间"的边界 ←→ AI 在边界内高速执行
       ↑                              ↓
   规则沉淀 ←── 偏差发现 ←── AI 执行产出

六、量化数据 ​

产出总览 ​

维度数据
总周期36.5 小时（4/17 23:59 ~ 4/19 12:30）
主体开发4/18 一天（53/56 commit，占 95%）
人工参与~88 分钟
后端 Python8,675 行 / 93 文件
前端 Vue 34,309 行 / 38 文件
测试代码747 行 / 8 文件
代码总计14,983 行 / 143 文件
Git commit56 个
Feature 分支26 个
Merge 操作20 次
API 端点131 个
ORM 模型27 张表
前端页面14 个
编码规则14 条

效率对比（仅供参考） ​

模块传统估算AI 协作实际倍率
后端 CRUD（27 表）2-3 周1 天~15x
前端页面（14 页）1-2 周54 分钟~100x
部署流水线2-3 天1 小时~20x

这些倍率基于"功能等价迁移"这一高确定性场景。需求不明确的新功能开发，倍率会低很多。

七、时间线全景 ​

4/17                    4/18                                        4/19
23:59                   00:00    06:00    12:00    18:00    00:00    12:30
  │                       │        │        │        │        │        │
  ├─ ① 规划 ─┐            │        │        │        │        │        │
  │  38min   │            │        │        │        │        │        │
  │          ├─ ② 骨架 ──┐│        │        │        │        │        │
  │          │  50min    ││        │        │        │        │        │
  │          │           │├─ 休息 ─┤        │        │        │        │
  │          │           ││ ~6h    │        │        │        │        │
  │          │           ││        ├─ ③ CRUD ────────┤        │        │
  │          │           ││        │  (AI 自动执行)    │        │        │
  │          │           ││        │                  ├─ ④ 偏差修复     │
  │          │           ││        │                  │  16min │        │
  │          │           ││        │                  ├─ ⑤ 网关+任务 ──┤
  │          │           ││        │                  │                │
  │          │           ││        │                  │     ⑥ 前端 54m │
  │          │           ││        │                  │     ⑦ 部署     │
  │          │           ││        │                  │                │
  │          │           ││        │                  │          BUGFIX │
  ▼          ▼           ▼▼        ▼                  ▼                ▼
START      骨架完成    人休息    CRUD开始           验证通过        全功能完成

八、可复制的方法论 ​

适用场景 ​

  • 功能等价迁移 — 换语言/框架，不改业务逻辑
  • 遗留系统现代化 — 有完整旧系统可参考
  • 标准化批量开发 — 多个相似实体的 CRUD

五个关键成功因素 ​

  1. 先规划，后执行 — PLAN.md + TASKS.md 建立确定性空间，AI 才能自主领任务
  2. 第一个实体建模板 — Platform 通过后，后续 10+ 实体 3-5 分钟自动套用
  3. 踩坑即刻写规则 — 每次偏差沉淀为规则文件，AI 不犯第二次
  4. 烟测优先 — Phase 完成立即验证，快速发现问题
  5. 滚动细化 — 不预拆所有任务，每个 Phase 入口先分析再细化

什么时候不适合 ​

  • 需求不明确的探索性项目（输入不确定）
  • 业务逻辑需要重新设计的重构（输出不确定）
  • 没有参考实现的全新开发

角色转变 ​

你最大的价值不是写出那 14,983 行代码，而是写出那 14 条规则 —— 它们让 AI 从"不可控"变成"可控"。

Copyright ©️ 2026, CodeFlow Contributors