Arkitect架构解密：从文件结构到运行原理

Arkitect架构解密：从文件结构到运行原理

【免费下载链接】arkitectPut your architectural rules under test!项目地址: https://gitcode.com/gh_mirrors/ar/arkitect

一、如何快速掌握项目核心架构？——功能模块全景图

核心价值：像拼积木一样理解系统组件

面对复杂项目时，开发者常因找不到关键入口而陷入代码迷宫。Arkitect采用"模块化积木"设计，每个目录如同独立功能积木，通过明确的协作规则组合成完整系统。

实现路径：四大核心模块的协作关系

1. Analyzer模块（源码解析器）：作为系统"扫描仪"，从PHP文件中提取类定义、依赖关系等关键信息，为规则检查提供数据基础
2. Expression模块（规则表达式）：定义架构规则的"语法规则"，如类命名规范、依赖限制等
3. Rules模块（规则引擎）：规则检查的"裁判系统"，执行Expression定义的规则并生成检查结果
4. CLI模块（命令行界面）：用户与系统交互的"控制面板"，接收指令并展示检查结果

💡 模块协作流程：用户通过CLI输入命令 → Rules模块加载规则 → Analyzer模块解析源码 → Expression模块定义的规则被应用 → CLI输出检查结果

使用示例：从命令到结果的完整链路

// 核心逻辑：通过CLI触发架构检查 $application = new PhpArkitectApplication(); $application->add(new CheckCommand()); // 注册检查命令 $application->run(); // 启动应用

当执行phparkitect check时，系统会依次激活上述模块，最终在终端展示架构规则的检查结果。

二、如何精准定位关键代码？——核心文件解析

核心价值：找到系统的"神经中枢"

大型项目中，关键文件如同城市的交通枢纽，掌握它们就能快速理解系统运行机制。Arkitect的核心文件围绕"规则定义-源码分析-结果输出"三大环节设计。

实现路径：五大核心文件的功能定位

1. src/Analyzer/FileParser.php- 源码解析器：

// 核心逻辑：将PHP文件解析为抽象语法树 public function parse(string $fileContent): ClassDescriptionCollection { $ast = $this->parser->parse($fileContent); return $this->classDescriptionBuilder->build($ast); }

2. src/Expression/ForClasses/HaveNameMatching.php- 命名规则表达式：

// 核心逻辑：检查类名是否匹配指定模式 public function evaluate(ClassDescription $classDescription): bool { return (bool)preg_match($this->pattern, $classDescription->getName()); }

3. src/Rules/ArchRule.php- 架构规则基类：

// 核心逻辑：定义规则检查的标准接口 public function check(ClassSet $classSet): Violations { $violations = new Violations(); foreach ($classSet->getClasses() as $class) { if (!$this->isSatisfiedBy($class)) { $violations->add($this->createViolation($class)); } } return $violations; }

4. src/CLI/Command/Check.php- 检查命令：

// 核心逻辑：执行架构检查并输出结果 protected function execute(InputInterface $input, OutputInterface $output): int { $config = $this->loadConfig($input); $runner = new Runner($config, $this->createProgress($output)); $result = $runner->run(); return $this->printer->print($result, $output) ? 0 : 1; }

5. src/CLI/Printer/TextPrinter.php- 文本输出器：

// 核心逻辑：将检查结果格式化为可读文本 public function print(AnalysisResult $result, OutputInterface $output): bool { foreach ($result->getViolations() as $violation) { $output->writeln(sprintf( '❌ %s:%d %s', $violation->getFile(), $violation->getLineNumber(), $violation->getMessage() )); } return $result->hasViolations() === false; }

📌 关键提示：这些核心文件构成了Arkitect的"脊柱"，理解它们之间的调用关系是掌握整个系统的关键。

使用示例：自定义架构规则

// 功能说明：检查所有控制器类是否以"Controller"结尾 // 代码片段 ArchRule::allClasses() ->that(new ResideInOneOfTheseNamespaces('App\Controller')) ->should(new HaveNameMatching('*Controller')) ->because('controllers should follow naming convention'); // 效果注释：当存在不符合命名规范的控制器类时，会在检查结果中显示具体文件和行号

三、如何配置适合不同环境的项目？——配置逻辑解析

核心价值：让项目在不同环境"智能切换"

如同手机的"情景模式"，项目配置需要根据开发、测试、生产等不同环境动态调整。Arkitect通过Composer配置和自定义规则文件实现环境适配。

实现路径：双维度配置体系

1. 开发/生产环境依赖差异：

{ "require": { "php": "^7.4 || ^8.0", "symfony/console": "^5.2", // 生产环境核心依赖 "nikic/php-parser": "^4.10" // PHP语法解析器 }, "require-dev": { "phpunit/phpunit": "^9.5" // 仅开发环境需要的测试工具 } }

2. 自动加载规则（PSR-4规范→PHP自动加载标准）：

{ "autoload": { "psr-4": { "Arkitect\\": "src/" // 生产代码命名空间映射 } }, "autoload-dev": { "psr-4": { "Arkitect\\Tests\\": "tests/" // 测试代码命名空间映射 } } }

3. 自定义架构规则配置（phparkitect.php）：

// 功能说明：为不同环境定义不同规则 // 代码片段 return static function (Config $config): void { if (getenv('APP_ENV') === 'production') { // 生产环境规则：严格检查所有依赖 $config->add(ArchRule::allClasses() ->should(new NotHaveDependencyOutsideNamespace())); } else { // 开发环境规则：允许测试相关依赖 $config->add(ArchRule::allClasses() ->that(new NotResideInTheseNamespaces('Tests')) ->should(new NotHaveDependencyOutsideNamespace())); } }; // 效果注释：通过环境变量APP_ENV自动切换规则严格程度

💡 配置技巧：使用composer install --no-dev命令可在生产环境中自动排除开发依赖，减小部署体积。

使用示例：多环境配置切换

# 开发环境：包含测试工具和宽松规则 APP_ENV=development composer install ./vendor/bin/phparkitect check # 生产环境：仅安装核心依赖和严格规则 APP_ENV=production composer install --no-dev ./phparkitect check

四、新手常见误区⚠️

误区1：过度复杂的规则定义

// 错误示例 ArchRule::allClasses() ->should(new HaveNameMatching('*Service')) ->andThat(new ResideInOneOfTheseNamespaces('Service')) ->andThat(new NotExtend('BaseClass')) ->andThat(new ...); // 规则链过长导致难以维护 // 正确做法：拆分规则，使用有意义的变量名 $serviceNamingRule = ArchRule::allClasses() ->that(new ResideInOneOfTheseNamespaces('Service')) ->should(new HaveNameMatching('*Service')); $serviceInheritanceRule = ArchRule::allClasses() ->that(new ResideInOneOfTheseNamespaces('Service')) ->should(new NotExtend('BaseClass')); $config->add($serviceNamingRule); $config->add($serviceInheritanceRule);

误区2：忽略命名空间与文件路径对应关系

⚠️ 错误：命名空间是App\Controller但文件放在src/Controllers/目录下
✅ 正确：遵循PSR-4规范，命名空间与文件路径严格对应，如App\Controller\UserController应放在src/Controller/UserController.php

误区3：在生产环境启用调试输出

// 错误示例：生产环境保留调试代码 $progress = new DebugProgress(); // 开发环境专用进度条 // 正确做法：根据环境选择组件 $progress = $isProduction ? new ProgressBarProgress() : new DebugProgress();

五、快速上手指南

1. 项目安装

# 克隆仓库 git clone https://gitcode.com/gh_mirrors/ar/arkitect # 安装依赖（开发环境） cd arkitect composer install # 安装依赖（生产环境） composer install --no-dev

2. 创建配置文件

# 生成默认配置文件 ./phparkitect init

3. 自定义规则

编辑phparkitect.php文件，添加架构规则：

return static function (Config $config): void { $config->add(ArchRule::allClasses() ->that(new ResideInOneOfTheseNamespaces('Domain')) ->should(new NotDependOnTheseNamespaces('Infrastructure')) ->because('domain layer should be independent')); };

4. 执行架构检查

# 开发环境 ./vendor/bin/phparkitect check # 生产环境 ./phparkitect check

通过这套架构检查机制，团队可以将架构规则"代码化"，确保项目始终遵循预设的设计规范，就像给代码质量安装了"自动安检系统"。无论是新项目初始化还是大型系统重构，Arkitect都能成为架构一致性的可靠守护者。

【免费下载链接】arkitectPut your architectural rules under test!项目地址: https://gitcode.com/gh_mirrors/ar/arkitect