历史遗留代码重构通用方法论

本文最后更新于166 天前，其中的信息可能已经过时，如有错误请发送邮件到184874483@qq.com

核心重构流程（七步法）

第一步：发现与识别阶段

// 1. 使用搜索工具定位重复方法
// IDE搜索: "function get_xxx" 或 "->get_xxx("
// 命令行: grep -r "function get_" .

// 2. 记录所有发现
// 创建重构清单：
// | 方法名 | 定义位置 | 调用位置 | 实现差异 |

第二步：深度分析阶段

分析维度检查表：

功能是否完全相同？
参数签名是否一致？（类型、数量、顺序）
返回值是否一致？
异常处理是否一致？
依赖关系是什么？（需要什么上下文？）
是否有副作用？（修改了哪些状态？）

特别关注参数命名：

// 识别参数命名模式：
// $user, $current_user, $wp_user, $user_object
// $id, $user_id, $uid
// $data, $params, $args

// 确定语义等价性：
// $current_user ≈ $user (当来自 wp_get_current_user())
// $user_id ≈ $id (当表示用户ID)

第三步：设计统一接口

设计原则：

// 原则1：向下兼容
public static function unified_method($param = null) {
    // 处理旧版所有调用方式
}

// 原则2：清晰文档
/**
 * 统一方法名
 * 
 * @param mixed $input 支持多种输入格式：
 *                    - WP_User对象
 *                    - 用户ID (整数)
 *                    - null (使用当前用户)
 *                    - 其他历史格式...
 * @return mixed 明确返回值类型
 * @throws 明确异常类型
 */

第四步：创建统一实现

板示例：

class Unified_Helper {
    /**
     * 统一方法 - 处理所有历史调用
     * 
     * 历史调用可能包括：
     * 1. SomeClass::old_method($user)
     * 2. $this->old_method($current_user)
     * 3. OtherClass::old_method($id)
     */
    public static function unified_method($input = null) {
        // 1. 参数标准化
        $standardized_input = self::standardize_input($input);
        
        // 2. 业务逻辑（原多个方法的交集）
        $result = self::core_logic($standardized_input);
        
        // 3. 结果标准化
        return self::standardize_output($result);
    }
    
    private static function standardize_input($input) {
        // 处理所有历史参数格式
        if (is_null($input)) {
            return wp_get_current_user();
        }
        
        if (is_numeric($input)) {
            return get_user_by('id', $input);
        }
        
        if ($input instanceof WP_User) {
            return $input;
        }
        
        // 其他历史格式...
        throw new InvalidArgumentException('不支持的参数格式');
    }
}

第五步：渐进式替换策略

替换顺序：

// 阶段1：先添加统一方法，保持旧方法
class Old_Class {
    public function old_method($user) {
        return Unified_Helper::unified_method($user);
    }
}

// 阶段2：修改调用点（分批次）
// 优先级顺序：
// 1. 简单调用（参数明确）
// 2. 内部调用（同一类内）
// 3. 外部调用（跨类调用）

// 阶段3：删除旧方法（标记为弃用）
/**
 * @deprecated 3.0.0 使用 Unified_Helper::unified_method()
 */
public function old_method($user) {
    _deprecated_function(__METHOD__, '3.0.0', 'Unified_Helper::unified_method');
    return Unified_Helper::unified_method($user);
}

第六步：变量名处理策略

变量名统一指南：

// 规则1：上下文优先
function process_current_user() {
    $current_user = wp_get_current_user(); // 好：明确当前用户
    $user_level = get_user_level($current_user);
}

function process_user($user) {
    $user_level = get_user_level($user); // 好：参数已命名
}

// 规则2：作用域明确
class User_Processor {
    private $current_user; // 实例属性
    
    public function process() {
        $local_user = $this->current_user; // 局部变量
        $level = get_user_level($local_user);
    }
}

// 规则3：避免全局变量滥用
// ❌ 不好：直接使用全局变量
function bad_example() {
    global $current_user;
    return get_user_level($current_user);
}

// ✅ 好：通过函数获取
function good_example() {
    return get_user_level(wp_get_current_user());
}

第七步：测试与验证

测试矩阵示例：

$test_cases = [
    // 历史调用方式 -> 期望结果
    ['input' => null, 'context' => '当前用户'],
    ['input' => 123, 'context' => '用户ID'],
    ['input' => $user_object, 'context' => '用户对象'],
    ['input' => 'admin@example.com', 'context' => '历史遗留格式'],
];

// 验证所有历史路径
foreach ($test_cases as $case) {
    $result = Unified_Helper::unified_method($case['input']);
    assert_equals($result, $expected, "Failed for: {$case['context']}");
}

具体工具与技术

1. IDE重构工具

# PHPStorm 重构功能：
# - Rename (Shift+F6)    # 重命名
# - Extract Method (Cmd+Alt+M) # 提取方法
# - Inline Method (Cmd+Alt+N)  # 内联方法
# - Change Signature (Cmd+F6)   # 修改签名

2. 静态分析工具

# PHPStan / Psalm 检查类型
vendor/bin/phpstan analyse --level max src/

# 检测重复代码
phpcpd src/ --min-lines 5 --min-tokens 30

3. 版本控制策略

# 使用特性分支
git checkout -b refactor/unified-user-method

# 小步提交
git add -p  # 交互式添加
git commit -m "refactor: 统一get_user_level调用步骤1"

# 保持可回退
git tag backup-before-refactor

最佳实践清单

遇到新重复方法时的检查表：

文档化现有实现

// 创建对比表格
// | 位置 | 参数 | 返回值 | 特殊逻辑 |

分析调用上下文

// 记录每个调用点的：
// 1. 参数来源
// 2. 结果用途
// 3. 异常处理

设计兼容接口

// 考虑：
// - 最通用的参数类型
// - 合理的默认值
// - 向后兼容方案

制定替换路线图

// 分阶段计划：
// 阶段1: 添加统一方法 + 包装器
// 阶段2: 替换低风险调用
// 阶段3: 替换高风险调用
// 阶段4: 删除旧方法

创建回归测试

// 确保：
// - 所有历史用例通过
// - 边界条件处理
// - 性能不受影响

经验法则

变量名处理黄金规则：

不破坏现有代码的情况下，优先统一逻辑，其次统一命名
变量名在作用域内自解释即可，不强求全局统一
通过代码审查逐步改善命名，而不是大规模重命名

参数设计原则：

// 好：灵活但明确
public static function get_user_data($identifier = null, $context = 'current') {
    // $identifier: ID、对象、email等
    // $context: 'current', 'any', 'admin'等
}

// 不好：过于死板
public static function get_user_data_by_id($user_id) {
    // 只能处理ID
}

常见陷阱与解决方案

陷阱1：过早删除旧方法

// 解决方案：弃用周期
class Legacy_Support {
    /**
     * @deprecated 使用 Unified_Helper::new_method()
     */
    public static function old_method() {
        trigger_error('已弃用', E_USER_DEPRECATED);
        return Unified_Helper::new_method();
    }
}

陷阱2：忽略边缘情况

// 解决方案：防御性编程
public static function unified_method($input) {
    try {
        return self::do_work($input);
    } catch (Exception $e) {
        // 记录历史兼容性警告
        error_log("兼容性问题: " . $e->getMessage());
        return self::fallback_for_legacy($input);
    }
}

陷阱3：性能倒退

// 解决方案：基准测试
$start = microtime(true);
// 新方法调用
$time_new = microtime(true) - $start;

$start = microtime(true);
// 旧方法调用  
$time_old = microtime(true) - $start;

assert($time_new <= $time_old * 1.2); // 允许20%性能损失