Arcanist扩展开发：构建自定义代码审查规则与工作流

Arcanist扩展开发：构建自定义代码审查规则与工作流

【免费下载链接】arcanistCommand line interface for Phabricator项目地址: https://gitcode.com/gh_mirrors/arc/arcanist

Arcanist是Phabricator的命令行接口工具，它允许开发者通过自定义扩展来构建符合团队需求的代码审查规则与工作流。本文将详细介绍如何开发Arcanist扩展，包括自定义代码审查规则和工作流的完整步骤，帮助你轻松提升代码质量和开发效率。

一、Arcanist扩展开发基础

1.1 了解Arcanist架构

Arcanist的核心架构基于可扩展的插件系统，主要包含Linter（代码审查规则）和Workflow（工作流程）两大扩展点。开发者可以通过继承核心基类来实现自定义功能：

• Linter扩展：继承ArcanistLinter类，实现代码检查逻辑，如语法验证、代码风格检查等。
• Workflow扩展：继承ArcanistWorkflow类，自定义命令行工作流程，如提交规范、自动部署等。

1.2 环境准备

首先，克隆Arcanist项目到本地：

git clone https://gitcode.com/gh_mirrors/arc/arcanist

核心代码位于src/目录，其中：

• 代码审查规则相关类在src/lint/linter/
• 工作流相关类在src/workflow/

二、构建自定义代码审查规则（Linter）

2.1 创建基础Linter类

自定义Linter需继承ArcanistLinter抽象类，并实现关键方法。以检查文件命名规范为例：

// src/lint/linter/ArcanistFilenameLinter.php final class ArcanistFilenameLinter extends ArcanistLinter { public function getLinterName() { return 'Filename'; // 定义Linter名称 } public function lintPath($path) { $filename = basename($path); if (!preg_match('/^[a-z0-9_]+\.php$/', $filename)) { $this->raiseLintAtPath( 'invalid-filename', '文件名必须使用小写字母、数字和下划线，且以.php结尾。' ); } } }

2.2 实现核心方法

• getLinterName()：返回Linter唯一标识，如'Filename'。
• lintPath($path)：对指定文件执行检查逻辑，通过raiseLintAtPath()或raiseLintAtLine()报告问题。
• getLintSeverityMap()：定义错误代码与严重级别（ERROR/WARNING/ADVICE）的映射。

2.3 注册与配置Linter

在项目根目录的.arclint文件中注册自定义Linter：

{ "linters": { "filename": { "type": "FilenameLinter", "include": ["**/*.php"] } } }

三、开发自定义工作流（Workflow）

3.1 工作流扩展基础

工作流扩展通过继承ArcanistWorkflow类实现，例如创建一个自动生成提交信息的工作流：

// src/workflow/ArcanistAutoCommitWorkflow.php final class ArcanistAutoCommitWorkflow extends ArcanistWorkflow { public function run() { $message = $this->generateCommitMessage(); $this->getEngine()->getRepositoryAPI()->execx( 'commit -m %s', $message ); return 0; } private function generateCommitMessage() { // 从分支名或JIRA任务生成规范提交信息 return "[TASK-123] 修复登录页面bug"; } }

3.2 注册自定义命令

在src/toolset/ArcanistArcToolset.php中注册新命令：

protected function buildWorkflowList() { return array( 'auto-commit' => 'ArcanistAutoCommitWorkflow', ); }

使用自定义命令：

arc auto-commit

四、高级扩展技巧

4.1 利用XHPAST进行语法分析

Arcanist内置XHPAST解析器，可对PHP代码进行深度语法分析。例如检查未使用的变量：

// src/lint/linter/xhpast/rules/ArcanistUnusedVariableXHPASTLinterRule.php final class ArcanistUnusedVariableXHPASTLinterRule extends ArcanistXHPASTLinterRule { public function process(XHPASTNode $root) { $variables = $root->selectDescendantsOfType('n_Variable'); foreach ($variables as $var) { if (!$this->isVariableUsed($var)) { $this->raiseLintAtNode( $var, 'unused-variable', '变量未被使用。' ); } } } }

4.2 配置文件与依赖管理

扩展可通过.arcconfig文件定义自定义配置：

{ "project_id": "myproject", "custom_linter_rules": ["MyCustomLinter"] }

五、测试与调试

5.1 单元测试

Arcanist提供完善的测试框架，测试文件位于src/__tests__/目录。为自定义Linter编写测试：

// src/lint/linter/__tests__/ArcanistFilenameLinterTestCase.php final class ArcanistFilenameLinterTestCase extends ArcanistLinterTestCase { public function testValidFilename() { $linter = new ArcanistFilenameLinter(); $this->executeTestsInDirectory($linter, 'tests/valid'); } }

5.2 调试工具

使用arc lint --trace命令查看Linter执行过程，或通过phutil_log()输出调试信息。

六、扩展分发与共享

6.1 打包扩展

将自定义扩展打包为独立库，通过Composer发布：

{ "name": "mycompany/arcanist-extensions", "autoload": { "psr-4": { "MyCompany\\Arcanist\\": "src/" } } }

6.2 集成到项目

在项目中通过.arcconfig引用扩展：

{ "load": ["vendor/mycompany/arcanist-extensions/src"] }

总结

通过Arcanist扩展开发，团队可以定制符合自身需求的代码审查规则和工作流，显著提升开发效率和代码质量。从简单的文件名检查到复杂的语法分析，Arcanist提供了灵活的扩展机制，助力团队构建更智能的开发流程。

官方文档：docs/official.md
Linter基础类：src/lint/linter/ArcanistLinter.php
工作流基础类：src/workflow/ArcanistWorkflow.php

【免费下载链接】arcanistCommand line interface for Phabricator项目地址: https://gitcode.com/gh_mirrors/arc/arcanist