怎样在PHP项目中实现架构分析？

本文目录导读：

1. 核心分析维度
2. 工具链选型
3. 实施步骤
4. 高级技巧
5. 常见问题与解决
6. 输出与行动
7. 最小可行方案

在PHP项目中实现架构分析，通常是为了理清代码结构、发现潜在问题、评估技术债务或为重构提供依据，以下是一套系统化的实践方法，涵盖工具、流程和最佳实践。

---

核心分析维度

在开始之前,先明确要分析哪些方面：

1. 分层与依赖：Controller → Service → Repository → Model 是否清晰？是否存在循环依赖或跨层调用？
2. 模块化：业务模块是否独立？模块间的耦合度如何？
3. 代码健康状况：类长度、方法复杂度、重复代码、未使用代码。
4. 数据库与ORM：N+1查询、索引缺失、反范式设计。
5. 性能瓶颈：热点路径、内存泄漏、慢查询。
6. 安全与配置：敏感信息硬编码、配置分散、权限模型。

---

工具链选型

静态分析工具（无需运行代码）

工具	用途	安装方式
PHPStan	类型错误、潜在bug、架构违规（通过规则集）	composer require --dev phpstan/phpstan
Psalm	类似PHPStan，更侧重类型安全	composer require --dev vimeo/psalm
PHPMD	代码气味检测（过长方法、过多参数等）	composer require --dev phpmd/phpmd
Deptrac	专用于依赖分析，支持定义层间通信规则	composer require --dev qossmic/deptrac-shim
PHP-Parser	解析AST，可自定义规则	composer require --dev nikic/php-parser

动态分析工具（需运行应用）

工具	用途	安装方式
Xdebug + PhpProfiler	函数调用树、执行时间、内存占用	扩展安装 + 配合 Webgrind
Blackfire.io	生产级性能分析（付费+免费额度）	扩展安装 + CLI工具
Tideways	轻量级性能监控，适合集成到CI	扩展安装 + 插桩
PHP Debug Bar	实时查看SQL、内存、请求信息	composer require --dev maximebf/debugbar

架构可视化工具

工具	用途	链接示例
PhpMetrics	生成类图、依赖图、代码复杂度热力图	phpmetrics --report-html=report src/
Deptrac Graphviz	输出依赖关系图（PNG/SVG）	deptrac analyze --formatter=graphviz
vfsStream（虚拟文件系统）	测试时模拟文件结构	不直接用于分析，但辅助测试架构规则

---

实施步骤

步骤1：搭建静态分析基础

在 composer.json 中添加：

"scripts": {
    "analyse:arch": [
        "phpstan analyse --level max src/",
        "phpmd src/ text cleancode,codesize,design"
    ]
}

运行 composer analyse:arch 得到初始报告。

步骤2：定义架构规则（Deptrac实战）

创建 deptrac.yaml：

deptrac:
  paths:
    - ./src
  layers:
    - name: Controller
      collectors:
        - type: className
          regex: .*Controller.*
    - name: Service
      collectors:
        - type: className
          regex: .*Service.*
    - name: Repository
      collectors:
        - type: className
          regex: .*Repository.*
    - name: Model
      collectors:
        - type: className
          regex: .*\\(Entity|Model)\\.*
  ruleset:
    Controller:
      - Service
    Service:
      - Repository
      - Model
    Repository:
      - Model
    Model:
      ~  # Model不应依赖任何上层

运行 deptrac 可发现类似 Controller -> Repository 的直接违规。

步骤3：动态性能分析

场景：分析一个API请求的调用链。

1. 安装Xdebug并配置 xdebug.mode=profile。
2. 用浏览器访问目标页面，生成 cachegrind.out.* 文件。
3. 使用 qcachegrind（Linux/macOS）或 Webgrind 打开，查看：
   • 调用次数最多的函数（如 count() 或 array_merge）。
   • 执行时间最长的路径（瓶颈是数据库还是业务逻辑）。
   • 内存分配峰值。

替代方案：使用 Blackfire 的 CLI 方式：

blackfire run php artisan some-command
blackfire build:create --from-env  # 查看HTML报告

步骤4：数据库架构分析

1. 慢查询日志：在MySQL中 SET GLOBAL slow_query_log=ON;，然后用 pt-query-digest 分析。
2. ORM分析：使用 Laravel Debugbar 或 Symfony Profiler 查看执行的SQL，关注：
   • 是否存在 N+1（可通过 SELECT * FROM users 后再查 comments 发现）。
   • 是否有 SELECT * 且只需要两列。
3. 迁移反模式：检查 migrations/ 目录，避免：
   • 一个迁移做太多事（如同时改表结构+加索引+加数据）。
   • 缺少 down() 方法。

---

高级技巧

类依赖图生成（可视化）

# 安装 phpcpd 和 phpmetrics
composer require --dev sebastian/phpcpd
phpmetrics --report-html=./metrics src/

生成的 dependency.svg 会显示高耦合的类（从箭头数量可看出）。

自定义规则（PHP-Parser 示例）

检测所有 Controller 直接使用 new Model()（应通过Repository）：

use PhpParser\{Node, NodeTraverser, NodeVisitorAbstract, ParserFactory};
$code = file_get_contents('src/Controller/SomeController.php');
$parser = (new ParserFactory)->create(ParserFactory::PREFER_PHP7);
$ast = $parser->parse($code);
$traverser = new NodeTraverser;
$traverser->addVisitor(new class extends NodeVisitorAbstract {
    public function enterNode(Node $node) {
        if ($node instanceof Node\Expr\New_ && 
            strpos($node->class->toString(), 'Entity') !== false) {
            echo "违规：Controller中直接实例化Entity\n";
        }
    }
});
$traverser->traverse($ast);

CI/CD集成

在 gitlab-ci.yml 中：

php-arch:
  stage: test
  script:
    - composer install
    - php vendor/bin/phpstan analyse --level 8 src/ --error-format=github
    - php vendor/bin/deptrac analyze --fail-on-uncovered  # 未覆盖的层会失败

---

常见问题与解决

问题	原因	解决方案
分析报告太多误报	第三方库未排除	在 phpstan.neon 中增加 ignoreErrors 和 paths 排除 vendor/
Deptrac 报错 Unknown layer	类命名未匹配正则	检查deptrac.yaml中的正则，或添加 collector.type=directory 按目录匹配
性能分析影响线上	Xdebug明显拖慢响应	使用Blackfire（低开销）或Tideways的采样模式
静态分析导致CI超时	全量分析太慢	使用 --memory-limit 和 --parallel-jobs，或只分析 src/ 目录

---

输出与行动

最终输出形式：

1. 架构报告PDF：包含依赖图、复杂度热力图、违规列表（按严重程度分级）。
2. CI检查清单：禁止Service层直接操作$_GET”。
3. 重构建议：如“将UserController中的业务逻辑抽离到UserService”。
4. 性能基线：记录当前关键路径的响应时间（P50/P99）,用于后续对比。

行动优先级：

1. 立即修复：严重安全漏洞（如SQL注入）、循环依赖导致的内存泄漏。
2. 短期优化：数据库N+1查询、过长方法（>100行）。
3. 长期重构：模块化拆分、依赖注入规范化。

---

最小可行方案

对于中小型PHP项目,快速搭建架构分析环境的步骤：

composer require --dev phpstan/phpstan qossmic/deptrac-shim
# 创建 deptrac.yaml 和 phpstan.neon
# 运行：deptrac analyze && phpstan analyse src/ --level 6
# 用 phpmd 检查代码气味

定期（如每次release前）运行这些命令，并可视化报告,即可逐步建立架构治理文化。