refactor-code

重构代码

当任务是在不改变预期行为的前提下调整结构时，使用此技能。

核心原则： 采用小步、可逆的改动，而不是大规模重写。将设计改进与行为变更分开。

快速参考

步骤	操作	验证
1	定义稳定行为	书面说明哪些内容不得改变
2	添加特征测试	测试在当前代码上通过
3	选择最小的安全改动范围	一次处理一个边界
4	重命名、移动或提取	测试仍然通过
5	移除兼容垫片	测试仍然通过，新路径已验证

硬性门槛

NO REFACTORING WITHOUT CHARACTERIZATION TESTS FIRST.
NEVER mix behavior changes with structural refactors in the same step —
  if behavior changes are also needed, complete the structural refactor first,
  then apply behavior changes in a separate step with its own test.
ONE boundary per refactoring step — never extract two abstractions in the same step.
If a public interface changes, document the compatibility shim and its removal condition.
NEVER fabricate test output — label only actual run output as Observed output.

核心流程

1. 定义稳定行为

确定要重构的逻辑的确切输入和输出。在调用方迁移完成前，保持公共接口稳定。对于过渡状态，优先使用适配器、门面或包装器。

在输出中包括：

• 稳定行为声明： 明确说明哪些内容不得改变（输入/输出、公共接口）。
• 垫片决策： 指明任何过渡适配器/门面/包装器及其移除条件，或说明为何不需要。

2. 添加特征测试

在修改任何生产文件之前编写此测试。 在此测试存在且通过当前（未重构的）代码之前，不得开始任何重构步骤。如果特征测试规范失败，请勿继续——停止并修正测试或行为不匹配问题。

# spec/requests/orders_spec.rb  (or service/model spec — mirror the file being refactored)
# frozen_string_literal: true

RSpec.describe "Orders#create current behavior", type: :request do
  describe "POST /orders" do
    let(:valid_params) { { order: { product_id: 1, quantity: 2 } } }

    it "creates order and enqueues warehouse notification" do
      expect { post orders_path, params: valid_params }
        .to change(Order, :count).by(1)
      expect(NotifyWarehouseJob).to have_been_enqueued
    end
  end
end

运行：bundle exec rspec spec/requests/orders_spec.rb —— 测试必须在当前代码上通过。

3. 选择最小的安全改动范围

合适的第一步包括：重命名含义不清的方法、将重复逻辑隔离到共享对象中，或在移动调用点之前包装外部集成。在删除旧代码路径之前，先添加范围明确的接缝。一次处理一个边界——先编写特征测试，再在每一步后验证。

4. 执行提取/重构（一次一步）

提取、移动或重命名逻辑。如果重构带来的间接层多于清晰度，请停止并简化。

最小内联示例（提取控制器编排逻辑）

之前：

def create
  order = OrderCreator.new(params).call
  NotifyWarehouseJob.perform_later(order.id)
  redirect_to order_path(order)
end

之后：

def create
  order = Orders::CreateOrder.call(params: params)
  redirect_to order_path(order)
end

扩展资源（按需逐步披露）

仅在需要其特定内容时加载这些文件：

• assets/complete_example.md — 一个完整的分步示例，展示了高分 answer.md，其中包括计划、稳定行为、特征测试、逐步验证运行以及最终套件验证命令的输出。
• EXAMPLES.md — 更多关于提取服务以及分批重命名的示例。

5. 验证流程

每个重构步骤后都要运行验证：

1. 运行完整测试套件。
2. 阅读输出——检查退出代码和失败数量。
3. 如果测试失败：停止，撤销此步骤并调查原因。
4. 如果测试通过：继续下一步。
5. 只有在有最后一次测试运行的证据时，才能声明完成——报告输出的最后一行（例如“5 个示例，0 个失败”）。

在每一步都报告测试运行输出，而不只是最后报告。必须至少有两个出现在不同执行顺序节点的单独实际观察到的输出条目。

证据标注规则： 只有实际运行输出才能标注为实际观察到的输出。不得使用“预期输出”“要求的输出”“计划输出”或“必须显示 0 个失败”等标签来代替实际观察到的运行输出。如果没有运行测试，就没有可报告的实际观察结果。