PHP老项目现代化改造：从技术债务到高效代码

1. 项目背景：当老代码成为技术债务

三年前接手这个PHP项目时，我面对的是一堆运行了8年的"祖传代码"。这个电商系统日均处理10万+订单，但代码库已经出现明显的"腐烂"症状：全局变量随处可见、SQL拼接超过20层嵌套、核心业务逻辑分散在30多个文件中。每次修改功能都像在拆定时炸弹——你永远不知道哪行看似无害的代码会引发连锁崩溃。

典型的"代码腐烂"特征在这个项目中几乎集齐了：

• 超过40%的类方法超过100行
• 重复代码块占比达到35%
• 核心业务逻辑与HTML渲染深度耦合
• 没有单元测试覆盖
• 数据库表字段命名出现create_time/v1_create_time/create_date等多种风格

2. 腐烂代码诊断：建立量化评估体系

2.1 静态分析工具链搭建

首先用PHPStan和Psalm建立静态检查基线，配置规则集从level 3开始逐步提升。关键配置项：

php复制// phpstan.neon
parameters:
    level: 5
    paths:
        - src
    ignoreErrors:
        - '#Call to method [a-zA-Z0-9_]+ on mixed#'
    checkMissingIterableValueType: false

2.2 技术债务度量指标

建立可量化的评估体系（示例数据）：

2.3 依赖关系可视化

使用deptrac生成组件依赖图，发现Controller直接调用DAO层的违规引用超过200处。典型问题案例：

bash复制php deptrac analyze --config-file=depfile.yaml --formatter=graphviz

3. 渐进式重构策略

3.1 建立安全网

先为最核心的订单处理模块添加特性测试：

php复制class OrderProcessingTest extends \PHPUnit\Framework\TestCase 
{
    /**
     * @test
     * @dataProvider orderStatusProvider
     */
    public function should_handle_status_transition_correctly(
        string $currentStatus, 
        string $action, 
        string $expectedStatus
    ) {
        $order = new Order($currentStatus);
        $processor = new OrderProcessor();
        
        $processor->applyAction($order, $action);
        
        $this->assertEquals($expectedStatus, $order->getStatus());
    }
    
    public function orderStatusProvider(): array
    {
        return [
            ['new', 'confirm', 'confirmed'],
            ['confirmed', 'ship', 'shipped'],
            // 其他20种状态组合...
        ];
    }
}

3.2 分层解耦实践

采用"绞杀者模式"逐步替换旧代码：

1. 在原有逻辑前插入新处理层

php复制// 旧代码
function processOrder(array $orderData) {
    // 200行混合逻辑
}

// 改造后
function processOrder(array $orderData) {
    try {
        $validated = (new OrderValidator())->validate($orderData);
        $normalized = (new DataNormalizer())->normalize($validated);
        return (new OrderProcessor())->process($normalized);
    } catch (ValidationException $e) {
        // 回退到旧逻辑
        return legacy_process_order($orderData);
    }
}

2. 使用适配器模式封装旧组件：

php复制class LegacyPaymentAdapter implements PaymentGatewayInterface
{
    public function charge(float $amount, array $options): string
    {
        // 调用原来的global函数
        $result = legacy_charge_payment(
            $amount,
            $options['card_num'],
            $GLOBALS['config']['payment_key']
        );
        
        if ($result['status'] !== 'OK') {
            throw new PaymentFailedException($result['error_msg']);
        }
        
        return $result['txn_id'];
    }
}

3.3 数据库迁移方案

采用双写策略迁移旧数据库：

php复制class OrderRepository
{
    public function save(Order $order): void
    {
        // 写入新库
        $this->entityManager->persist($order);
        
        // 同步写入旧库
        $this->writeToLegacyDb([
            'order_id' => $order->getId(),
            'status' => $order->getStatus(),
            // 其他字段映射...
        ]);
        
        // 通过定时任务校验数据一致性
        $this->dispatcher->dispatch(
            new DataSyncEvent('order', $order->getId())
        );
    }
}

4. 关键改造技术点

4.1 类型系统增强

使用PHP 7.4的typed properties逐步添加类型声明：

php复制class Order {
    private string $id;
    private DateTimeImmutable $createdAt;
    private OrderStatus $status;
    
    /** @var OrderItem[] */
    private array $items;
    
    public function __construct(
        string $id,
        OrderStatus $status,
        array $items
    ) {
        $this->id = $id;
        $this->status = $status;
        $this->items = array_map(
            fn(array $item) => new OrderItem($item),
            $items
        );
        $this->createdAt = new DateTimeImmutable();
    }
}

4.2 依赖注入改造

将全局变量替换为依赖注入：

php复制// 改造前
function sendNotification() {
    global $mailer, $config;
    $mailer->send($config['admin_email'], ...);
}

// 改造后
class NotificationService {
    private MailerInterface $mailer;
    private string $adminEmail;
    
    public function __construct(
        MailerInterface $mailer,
        string $adminEmail
    ) {
        $this->mailer = $mailer;
        $this->adminEmail = $adminEmail;
    }
    
    public function send(): void {
        $this->mailer->send($this->adminEmail, ...);
    }
}

4.3 异步处理改造

用消息队列解耦耗时操作：

php复制class OrderService {
    private MessageBusInterface $bus;
    
    public function confirmOrder(string $orderId): void
    {
        // 同步操作
        $this->orderRepository->updateStatus($orderId, 'confirmed');
        
        // 异步操作
        $this->bus->dispatch(new OrderConfirmedEvent($orderId));
    }
}

// 消费者
class OrderConfirmedHandler
{
    public function __invoke(OrderConfirmedEvent $event)
    {
        // 发送邮件、更新推荐系统等
        $this->emailService->sendConfirmation($event->orderId);
        $this->recommendationService->update($event->orderId);
    }
}

5. 性能优化实战

5.1 查询优化方案

改造前典型的N+1查询问题：

php复制$orders = $db->query("SELECT * FROM orders WHERE status = 'new'");
foreach ($orders as $order) {
    $items = $db->query("SELECT * FROM items WHERE order_id = ".$order['id']);
    // 处理逻辑
}

优化后使用预加载模式：

php复制$orders = $this->entityManager->createQueryBuilder()
    ->select('o', 'i')
    ->from(Order::class, 'o')
    ->leftJoin('o.items', 'i')
    ->where('o.status = :status')
    ->setParameter('status', 'new')
    ->getQuery()
    ->getResult();

5.2 缓存策略实施

多级缓存设计方案：

php复制class ProductService {
    private CacheInterface $cache;
    
    public function getProductDetails(string $id): array 
    {
        $cacheKey = "product_{$id}";
        
        // 第一层：本地内存缓存
        if ($data = $this->cache->get($cacheKey)) {
            return $data;
        }
        
        // 第二层：分布式缓存
        $data = $this->redis->get($cacheKey);
        if (!$data) {
            // 第三层：数据库
            $data = $this->fetchFromDatabase($id);
            $this->redis->set($cacheKey, $data, 3600);
        }
        
        $this->cache->set($cacheKey, $data, 60);
        return $data;
    }
}

6. 持续改进机制

6.1 代码质量门禁

在CI流水线中加入质量检查：

yaml复制# .github/workflows/ci.yml
jobs:
  quality-gate:
    steps:
      - run: composer run static-analysis
      - run: composer run tests -- --coverage-text --colors=never
      - run: |
          coverage=$(phpunit --coverage-text | grep 'Lines' | awk '{print $4}' | sed 's/%//')
          if (( $(echo "$coverage < 70" | bc -l) )); then
            echo "Coverage below 70%: $coverage%"
            exit 1
          fi

6.2 自动化重构工具

使用Rector进行机械式重构：

php复制// rector.php
return static function (RectorConfig $rectorConfig): void {
    $rectorConfig->rule(ReplaceGlobalWithDependencyInjectionRector::class);
    $rectorConfig->rule(ReplaceStringClassnameWithClassConstantRector::class);
    $rectorConfig->rule(AddParamTypeDeclarationRector::class);
};

6.3 监控与告警

关键指标监控配置：

bash复制# Prometheus配置示例
- name: php_app
  rules:
  - alert: HighErrorRate
    expr: rate(php_application_errors_total[1m]) > 5
    for: 5m
    labels:
      severity: critical
    annotations:
      summary: "High error rate on {{ $labels.service }}"
      description: "Error rate is {{ $value }} errors/sec"

7. 经验总结与避坑指南

1. 数据库迁移黄金法则：

   • 始终保留旧字段三个月以上
   • 使用触发器保持双写一致性
   • 迁移后立即建立数据校验任务

2. 重构时序控制：

   • 避免在促销季前进行重大重构
   • 每次发布只包含一个主要重构项
   • 新老代码并行运行至少两周

3. 性能陷阱警示：

   • ORM的延迟加载在循环中会产生N+1问题
   • 过度使用DI容器会导致内存泄漏
   • 批量处理时注意内存峰值

4. 团队协作建议：

   • 建立代码审查checklist
   • 使用Git blame保留修改记录
   • 每周分享一个"坏味道"代码案例

这个项目最终用18个月完成了现代化改造，核心指标对比如下：

关键收获是：老项目改造不是一次性工程，而是需要建立持续优化的工程文化。我们后来将这套方法提炼为"渐进式现代化框架"，已经成功应用到其他5个遗留系统中。