求支持自定义边界规则限制类导入的PHP代码检查工具（Monorepo场景）

架构老林

2026-5-6

绝对有！PHP生态里完全有工具能帮你实现这类依赖边界管控，和你提到的ESLint的no-restricted-imports、nx-enforce-module-boundaries这类规则功能对标，甚至能完美适配DDD六边形架构的分层要求。下面给你详细拆解可行的方案：

1. PHP_CodeSniffer (phpcs) 自定义Sniff实现依赖管控

phpcs本身支持通过自定义Sniff来检查代码中的use语句、类引用，正好能用来限制模块间的不当依赖。你可以针对你的Monorepo目录结构和依赖规则，编写专属的Sniff：

步骤1：创建自定义Sniff类
比如要禁止PaymentModule引用OrderModule、禁止单体应用引用新模块，你可以写一个Sniff扫描所有use语句，当发现违反规则的引用时抛出错误。示例思路：

<?php
namespace YourProject\Sniffs\Dependency;

use PHP_CodeSniffer\Sniffs\Sniff;
use PHP_CodeSniffer\Files\File;

class ForbiddenModuleDependencySniff implements Sniff
{
    // 定义禁止的依赖映射：key是依赖方命名空间，value是被禁止的依赖源命名空间列表
    public $forbiddenDependencies = [
        'App\PaymentModule' => ['App\OrderModule'],
        'App\Monolith' => ['App\OrderModule', 'App\PaymentModule'],
    ];

    public function register()
    {
        return [T_USE];
    }

    public function process(File $phpFile, $stackPtr)
    {
        $useDeclaration = $phpFile->getDeclarationName($stackPtr);
        if (empty($useDeclaration)) {
            return;
        }

        // 获取当前文件的命名空间
        $namespacePtr = $phpFile->findNext(T_NAMESPACE, 0);
        $currentNamespace = $namespacePtr ? $phpFile->getDeclarationName($namespacePtr) : '';

        // 检查当前命名空间是否存在禁止依赖的规则
        if (isset($this->forbiddenDependencies[$currentNamespace])) {
            foreach ($this->forbiddenDependencies[$currentNamespace] as $forbiddenNs) {
                if (str_starts_with($useDeclaration, $forbiddenNs)) {
                    $error = '禁止依赖 %s，当前模块 %s 不允许引用该命名空间';
                    $phpFile->addError($error, $stackPtr, 'ForbiddenDependency', [$forbiddenNs, $currentNamespace]);
                }
            }
        }
    }
}

步骤2：配置phpcs加载自定义Sniff
在你的phpcs.xml配置文件中，注册这个Sniff并启用：

<?xml version="1.0"?>
<ruleset name="YourProjectDependencyRules">
    <rule ref="YourProject\Sniffs\Dependency\ForbiddenModuleDependencySniff"/>
</ruleset>

2. PHPStan：更强大的静态分析方案

如果你想用更现代化的静态分析工具，PHPStan是绝佳选择，它支持通过自定义规则或灵活配置来实现依赖边界管控：

自定义规则：PHPStan的规则API偏向于类型和符号分析，能更精准地捕捉间接依赖。你可以编写规则来验证某个命名空间下的类是否引用了被禁止的命名空间，甚至能检查通过依赖注入产生的间接依赖。
配置驱动的限制：你也可以通过PHPStan的参数配置快速实现基础的依赖限制，比如禁止某个命名空间引用特定类：
```
parameters:
    forbiddenClasses:
        App\PaymentModule\:
            - App\OrderModule\*
```

3. 适配DDD六边形架构的分层管控

针对DDD六边形架构的分层要求（应用层、领域层、基础设施层），你只需要把上述工具的规则进一步细化，对应到各层的依赖限制：

领域层：禁止引用基础设施层（比如数据库实现、第三方API客户端）和应用层代码，确保领域模型的纯粹性，只依赖自身的领域对象和端口定义。
应用层：允许引用领域层，但禁止直接引用基础设施层，必须通过端口（Port）和适配器（Adapter）交互。
基础设施层：可以引用领域层和应用层的端口，但不能反向影响领域层的独立性。

比如在phpcs的Sniff中，你可以更新禁止依赖配置：

public $forbiddenDependencies = [
    'App\Domain' => ['App\Infrastructure', 'App\Application'],
    'App\Application' => ['App\Infrastructure'],
];

额外提示

如果你用的是Symfony或Laravel这类框架，部分社区扩展已经实现了类似的DDD分层检查规则，你可以直接搜索“DDD PHP CodeSniffer rules”或“PHPStan DDD rules”找到现成的实现。
把这些规则集成到CI/CD流程中，就能确保所有提交的代码都符合依赖边界要求，从源头避免不当耦合。

内容的提问来源于stack exchange，提问作者Matt Janssen