以最低风险将原型重构为模块

为什么原型改动风险大

原型之所以感觉快，是因为所有东西都紧靠在一起。一个路由直接访问数据库、整理响应，然后 UI 渲染它。这种速度是真实的，但它掩盖了代价：一旦更多功能加入，最初的“快速路径”就会变成所有东西依赖的路径。

首先出问题的通常不是新代码，而是旧假设。

对路由做一个小改动就可能悄悄改变响应结构，从而破坏两个界面。一个“临时”查询被复制到三个地方后开始返回略有差别的数据，没人知道哪个是正确的。

这也是大规模重写即便出于好意也会失败的原因。它们同时改变结构和行为。当出现 bug 时，你无法判断原因是新的设计选择还是基本错误。信任下降，范围膨胀，重写被拖延。

低风险重构意味着把改动保持得小且可逆。你应该能在任何一步停手，并且应用仍然可用。实践中的规则很简单：

• 每次改动只有一个明确目标（迁移代码，不改变其行为）
• 短周期，可以每次重新测试同一个用户流程
• 一个无惊喜的回滚方案，能快速执行
• 新代码在证明可行前应与旧代码并存

当每一层开始做别的层的工作时，路由、服务、数据库访问和 UI 就会纠缠在一起。解开纠缠不是去追求“完美架构”，而是一次移动一根线。

在动手之前先定规则

把重构当成一次搬家，而不是翻修。保持行为不变，并让结构更容易在以后改变。如果你在重组时顺便“改进”功能，你会忘了是什么地方出了问题。

写下哪些内容暂时不变更。常见的“暂不”项：新特性、UI 重设计、数据库模式更改以及性能优化。这个边界能保持工作低风险。

选一个“黄金路径”用户流程并保护它。选择用户每天都会做的事，比如：

sign in -> create item -> view list -> edit item -> save

你会在每个小步骤后重新跑这个流程。如果行为相同，就可以继续前进。

在第一次提交前就约定回滚方式。回滚应该很无聊：一次 git revert、短期 feature flag，或可恢复的平台快照。如果你在 Koder.ai 上构建，快照与回滚是你在重组时的有用保障。

为每个阶段保留一个小的完成定义。你不需要很长的清单，只要足够防止“迁移＋修改”悄悄发生：

• 相同的输入产生相同的输出（包括错误和空状态）
• 黄金路径通过快速手动测试（或一个小的自动化检查）
• 变更保持在该阶段的范围内（仅路由或仅服务）
• 回滚至少验证过一次（你实际试过）
• 一条简短说明解释哪些东西移动了、现在放在哪里

如果原型只有一个文件同时处理路由、数据库查询和 UI 格式化，不要一次性拆分所有内容。先把路由处理器移动到一个文件夹，保持逻辑不变，即使需要复制粘贴也行。一旦稳定，再在后续阶段提取服务和数据库访问。

快速盘点：路由、页面和数据路径

在开始前，先把现状做个映射。这不是重设计，而是个安全步骤，方便你做小且可逆的移动。

列出每个路由或端点，并用一句话说明它的作用。包括页面路由和 API 路由。如果你用聊天驱动的生成器导出过代码，也按同样方式处理：清单应把用户看到的内容与代码实际触及的内容对应起来。

一个轻量但有用的清单：

• 路由/端点 + 用途（示例："/checkout" 显示支付表单）
• 触发它的 UI 页面/组件
• 涉及的业务规则（定价、校验、权限）
• 触及的数据库表以及访问类型（读/写/事务）
• 复制与重复（相同校验被复制到三个文件）

为每个路由写一条简单的“数据路径”说明：

UI 事件 -> handler -> 逻辑 -> DB 查询 -> 响应 -> UI 更新

在过程中，标注出高风险区域，这样在清理临近代码时不会不小心改动它们：

• 支付与计费
• 认证、会话、角色
• 数据库迁移和种子脚本
• 后台作业和定时任务
• 任何在事务中运行的东西

最后，草拟一个简单的目标模块映射。保持扁平。你是在选择目的地，而不是构建一个新系统：

routes/handlers, services, db (queries/repositories), ui (screens/components)

如果你无法解释一段代码应放在哪里，那这块代码就是一个适合以后重构的候选，等你建立了更多信心再来做。

阶段 1：稳定路由而不改逻辑

先把路由（或 controller）当作边界，而不是改进代码的地方。目标是在把端点放到可预测的位置时保持每个请求的行为不变。

为每个功能域创建一个薄薄的模块，例如 users、orders 或 billing。避免“移动时清理”的做法。如果你在同一个提交中既重命名又重组文件又重写逻辑，就很难发现哪里出错了。

一个安全的顺序：

• 按功能把现有的路由处理器分组，即使内部很混乱
• 先只移动接线代码：读取参数、基本校验、调用同样已有的函数
• 保持响应一致：状态码、错误信息和载荷结构都不变
• 每个路由添加一个很小的黄金路径检查（必须保持可用的快乐路径调用）

具体示例：如果你有一个单文件处理 POST /orders，它解析 JSON、校验字段、计算总额、写数据库并返回新订单，不要重写它。把处理器提取到 orders/routes，并调用旧逻辑，比如 createOrderLegacy(req)。新的路由模块成为前门；旧逻辑暂时保持不动。

如果你在处理生成的代码（例如在 Koder.ai 中导出的 Go 后端），心态不变。把每个端点放到可预测的位置，封装遗留逻辑，并证明常见请求仍然成功。

阶段 2：把业务逻辑拉到服务层

路由不是业务规则的好归宿。它们会迅速增长、混合关注点，每次改动都显得风险很大，因为你触及了所有东西。

为每个面向用户的动作定义一个服务函数。路由应收集输入、调用服务并返回响应。把数据库调用、定价规则和权限检查移出路由。

当服务函数只做一件事、输入清晰、输出明确时，它们更容易理解。如果你不断在里面添加“还有……”，就把它拆分。

一个常用的命名模式：

• CreateOrder(input) -> order
• CancelOrder(orderId, actor) -> result
• GetOrderSummary(orderId) -> summary

把规则放在服务层，而不是 UI。例如：不要仅靠 UI 根据“高级用户可以创建 10 个订单”来禁用按钮，把这条规则放在服务层强制执行。UI 仍然可以展示友好提示，但规则应只在一处。

在继续之前，增加足够的测试以使改动可逆：

• 一个成功路径测试，确认创建/更新正确
• 一个错误路径测试（缺少必填字段、权限被拒）

如果你使用像 Koder.ai 这样的快速生成/迭代工具，服务层会成为你的锚点。路由和 UI 可以演进，但规则保持稳定且易测。

阶段 3：安全地隔离数据库访问

一旦路由稳定且服务存在，就不要让数据库“随处可见”。把原始查询隐藏在一个小而无聊的数据访问层后面。

创建一个小模块（repository/store/queries），暴露少量命名清晰的函数，例如 GetUserByEmail、ListInvoicesForAccount 或 SaveOrder。不要追求优雅。目标是为每个 SQL 字符串或 ORM 调用找到一个明显的位置。

把这个阶段严格限定在结构上。避免模式变更、索引调整或“既然在这里顺便做了”的迁移。这些应当是各自计划好的变更与回滚。

把事务放在一个地方

一个常见的原型味道是事务散落各处：一个函数开始事务，另一个默默打开自己的事务，错误处理各不相同。

相反，创建一个入口点在事务中运行回调，并让 repository 接受事务上下文。

保持移动小颗粒度：

• 每次把一个查询移动到 repository，保持相同的输入/输出
• 服务直接调用新的 repository 函数（不要加额外逻辑）
• 在一个 helper 中统一事务的 begin/commit/rollback
• 标准化错误映射（例如“未找到” vs “意外错误”）

例如，如果“创建项目”既插入项目又插入默认设置，把这两次调用放在同一个事务 helper 中。如果某处失败，你就不会出现只有项目存在但其设置不存在的情况。

一旦服务依赖接口而不是具体的 DB 客户端，你就能在不使用真实数据库的情况下测试大部分行为。这会降低恐惧感，这正是本阶段的目的。

阶段 4：在不重设计的前提下清理 UI 组件

UI 清理不是为了美化，而是为了让屏幕可预测并减少意外副作用。

按功能把 UI 代码分组，而不是按技术类型。一个功能文件夹可以包含其页面、更小的组件和本地 helper。当你看到重复的标记（相同的按钮行、卡片或表单字段），就抽取它，但先保持标记和样式不变。

保持 props 简单。只传递组件需要的内容（字符串、id、布尔值、回调）。如果你传了一个巨大的对象“以防万一”，就定义一个更小的结构。

把 API 调用移出 UI 组件。即使有了服务层，UI 代码仍常常包含 fetch、重试和映射。为每个功能（或每个 API 区域）创建一个小的客户端模块，返回页面可直接使用的数据。

然后统一屏幕间的加载和错误处理。选一个模式并复用：可预测的加载状态、带一个重试操作的统一错误信息、以及能说明下一步的空状态。

每次抽取后都做一个快速的界面检查：点击主要动作、刷新页面并触发一个错误用例。小步胜过大改。

一个现实示例：端到端重构一个功能

想象一个小原型包含三个页面：登录、列出项、编辑项。它能用，但每个路由都混合了认证检查、业务规则、SQL 和 UI 状态。目标是把这个功能变成一个干净的模块，变更可回退。

之前与之后：东西都移动到了哪里

之前，“items” 逻辑可能分散如下：

server/
  main.go
  routes.go
  handlers.go          # sign in + items + random helpers
  db.go                # raw SQL helpers used everywhere
web/
  pages/
    SignIn.tsx
    Items.tsx          # fetch + state + form markup mixed

之后，行为保持相同，但边界更清晰：

server/
  routes/
    items_routes.go
  handlers/
    items_handler.go
  services/
    items_service.go
  repositories/
    items_repo.go
web/
  pages/
    Items.tsx
  components/
    ItemForm.tsx

一次端到端的小步骤（可逆）

先移动代码而不改逻辑。保持函数名和返回形状相同，这样回滚主要就是文件移动。

先重构一个路由。处理器只应处理 HTTP，不做规则或 SQL：

// handlers/items_handler.go
func (h *ItemsHandler) UpdateItem(w http.ResponseWriter, r *http.Request) {
  userID := h.auth.UserIDFromRequest(r) // same auth logic as before
  itemID := mux.Vars(r)["id"]

  var in UpdateItemInput
  json.NewDecoder(r.Body).Decode(&in)

  item, err := h.itemsService.UpdateItem(r.Context(), userID, itemID, in)
  if err != nil { writeError(w, err); return }
  writeJSON(w, item)
}

接着，把业务规则移动到服务层。在这里放像“用户只能编辑自己的项”或“名称不能为空”这类检查。服务调用 repository 执行 DB 工作：

// services/items_service.go
func (s *ItemsService) UpdateItem(ctx context.Context, userID, itemID string, in UpdateItemInput) (Item, error) {
  if strings.TrimSpace(in.Name) == "" { return Item{}, ErrInvalidName }
  return s.repo.UpdateItem(ctx, userID, itemID, in)
}

然后在 repository 中隔离数据库访问：

// repositories/items_repo.go
func (r *ItemsRepo) UpdateItem(ctx context.Context, userID, itemID string, in UpdateItemInput) (Item, error) {
  row := r.db.QueryRowContext(ctx,
    `UPDATE items SET name=$1 WHERE id=$2 AND user_id=$3 RETURNING id, name`,
    in.Name, itemID, userID,
  )
  var it Item
  err := row.Scan(&it.ID, &it.Name)
  return it, err
}

在 UI 端，保持页面布局，但把重复的表单标记抽成一个被“新建”和“编辑”共用的组件：

• pages/Items.tsx 保留抓取与导航
• components/ItemForm.tsx 负责输入字段、校验提示和提交按钮

如果你使用 Koder.ai（koder.ai），它的源代码导出在做更深层重构前会很有用，快照/回滚能帮助你在移动出问题时快速恢复。

增加风险的常见陷阱

最大风险是把“移动”工作和“修改”工作混在一起。当你在同一个提交中既移动文件又改写逻辑，错误会隐藏在嘈杂的 diff 里。保持迁移无趣：相同的函数、相同的输入、相同的输出，只是换了个地方。

另一个陷阱是清理时改变了行为。重命名变量可以；但重命名概念就不行。如果 status 从字符串变为数字，你改变的就是产品而非代码。那类改动要留到之后带着清晰测试并有计划地发布。

会悄悄制造麻烦的模式

一开始你可能想为未来构建一个很大的文件夹树和多层结构。那通常会拖慢你并让你更难看清真实工作所在。先从最小有用的边界开始，当下一个特性迫使你时再扩展。

还要注意 UI 直接访问数据库（或通过 helper 调用原始查询）的捷径。它看起来快，但让每个页面都要负责权限、数据规则和错误处理。

风险放大器要避免：

• 大幅重构的提交同时修改很多文件并更改逻辑
• 共享返回形状在未更新所有调用方的情况下改变
• 在没有明确理由的情况下新增层级
• 错误处理被简化（所有错误都变成 null 或通用消息）

一个小例子：如果某屏幕期望 { ok: true, data }，但新的服务返回 { data } 并在出错时抛出异常，半个应用可能就停止展示友好消息。先在边界处保持旧形状，然后逐个迁移调用方。

在进入下一阶段前的快速检查

在下一步之前，证明你没有破坏主要体验。每次都跑相同的黄金路径（登录、创建项、查看、编辑、删除）。一致性能帮助你发现小的回归。

每个阶段后使用一个简单的通过/不通过门：

• 黄金路径端到端仍然有效，包括常见错误情况
• 路由/控制器很薄：读取输入、调用一个服务、返回响应
• 服务可移植：可以从路由、后台任务或 UI 操作中调用，而不用知道 HTTP
• 数据库访问集中，事务模式一致且错误处理统一
• 回滚快速且已验证

如果有一项不通过，停下来修复再往上构建。小裂缝之后会变大。

一个快速的“我们能撤销吗？”演练

合并后花五分钟验证能否回退：

• 在本地分支撤销最近一次提交并确认应用能启动且黄金路径能跑通
• 关闭新的代码路径（feature flag、配置开关或条件判断）并确认旧行为仍存在
• 查看日志和数据库写入，确认黄金路径的存储行为未改变

后续步骤：随着产品增长保持模块化

胜利不在于第一次清理，而在于随着功能增加依然保持形状。你不是追求完美架构，而是让未来改动可预测、小且容易撤销。

根据影响度和风险选择下一个模块，而不是选择最令人烦恼的地方。好的目标是用户经常触达的部分，且行为已经被理解。把不明确或脆弱的区域留到你有更好的测试或更明确的产品答案时再做。

保持简单节奏：小的 PR 移动一件事、短周期审查、频繁发布，以及一个停止规则（如果范围扩大，就拆分并先发布小块）。

在每个阶段之前设定一个回滚点：git tag、release 分支或你知道可部署的工作构建。如果你在 Koder.ai 上构建，Planning Mode 可以帮助你分阶段变更，避免不小心同时重构三层。

模块化应用架构的实用规则：每个新特性遵循相同边界。路由保持薄、服务负责业务规则、数据库代码集中在一处、UI 组件专注于展示。当新特性违背这些规则时，越早重构越好，因为改动还小。