企业官网建设流程全解析

• 跨平台
• 前端
• 移动开发
• OpenHarmony

导读

ArkTS Linter 是 flutter_flutter（Flutter SDK 与 Flutter Engine 的 OpenHarmony 适配版本）仓库中 ci/scripts/arkts_linter 目录下的一套代码门禁检查工具，它基于 ArkTS 门禁规则集，通过内置正则规则与 DevEco Studio codelinter 的双引擎机制，实现 64 条门禁规则的自动化检查。本文以该工具的 README 为骨架，结合其 Python 源码与 YAML 规则配置逐层拆解：你将掌握命令行/包级两种调用方式、内置门禁规则与 codelinter 的协作原理、YAML 规则配置的完整字段语义、JSON 报告结构与门禁判定逻辑，并能直接照抄命令在 OpenHarmony 项目中落地 ArkTS 代码门禁流水线。

一、工具定位与项目结构

ArkTS Linter 面向 OpenHarmony 应用开发中的 ArkTS（.ets/.ts）源码，服务于 CI 门禁场景：任何一次提交都可以通过它快速完成安全类与代码规范类检查，发现问题即以 JSON 报告输出并直接决定流水线通过/失败（退出码 0/1/2）。

从仓库目录 ci/scripts/arkts_linter 看，其完整结构如下：

arkts_linter/ ├── __init__.py # 包初始化，导出 ArkTSLinter 与 main ├── arkts_linter.py # 主入口（命令行接口）+ ArkTSLinter 主类 ├── config/ │ ├── __init__.py │ └── rules.yaml # 规则配置文件（YAML 格式），内置 64+ 条门禁规则 ├── core/ │ ├── __init__.py │ ├── models.py # 数据模型（LintIssue, LintReport, RuleLevel 等） │ ├── rule_loader.py # 规则配置加载器（解析 YAML、映射枚举） │ ├── scanner.py # 文件扫描器（递归收集 .ets/.ts） │ ├── runner.py # codelinter 运行器（外部进程调度） │ └── checker.py # 规则检查器（正则匹配 + 特定条件判定） ├── utils/ │ ├── __init__.py │ ├── helpers.py # 工具函数（注释剥离、try 块判定、规则 ID 提取） │ └── report.py # 报告生成器（统计、门禁判定、JSON/摘要输出） └── README.md # 本文件

顶层还保留了一个向后兼容入口 ci/scripts/arkts_linter_cli.py，它把包目录注入sys.path后直接转发到arkts_linter.main()，因此你可以用python arkts_linter_cli.py或python -m arkts_linter两种方式启动。

从源码结构可以推断，整个工具的检查管线是一条清晰的流水线：ArkTSLinter.check()（见 arkts_linter.py）依次执行「扫描文件 → 内置规则逐文件检查 → 调用 codelinter 并合并结果 → 生成报告 → 保存 JSON → 打印摘要」六个步骤，这与 README 描述的「64 条门禁规则自动化检查」能力一一对应。

二、安装依赖

工具本身只依赖 Python 3 标准库与 PyYAML，安装极其轻量：

pip install pyyaml

除此之外没有其他第三方依赖——内置规则检查完全由 core/checker.py 中的正则引擎驱动；只有当你需要叠加 DevEco Studio 的 codelinter 检查时，才需要额外准备 Node.js 环境（详见第四节）。

三、命令行使用详解

3.1 基本用法：内置规则检查（推荐，默认方式）

不配置任何外部工具时，工具直接使用内置的 64+ 条门禁规则（配置见 config/rules.yaml）进行检查：

python arkts_linter_cli.py --target-path ./src --output report.json

--target-path是唯一必需参数，既可以传目录（工具会递归扫描），也可以传单个 .ets/.ts 文件。默认不传--output时，报告会写入当前目录下的arkts_lint_report.json。

3.2 叠加 codelinter：内置规则 + 外部引擎双保险

codelinter 是 DevEco Studio 自带的 ArkTS 代码检查引擎，官方推荐两种接入形态：

# 方式一：IDE 内置插件（index.js，需要指定 Node.js 路径） python arkts_linter_cli.py --codelinter-path "D:/DevEco Studio/plugins/codelinter/run/index.js" \ --target-path ./src --output report.json # 方式二：独立命令行工具（.bat 文件） python arkts_linter_cli.py --codelinter-path "D:/command-line-tools/bin/codelinter.bat" \ --target-path ./src --output report.json

两条命令都会在「内置规则检查」之外再调用 codelinter 对同一目标目录执行一次检查，并把两类问题合并进同一份报告。注意 README 与源码 epilog 都明确提示：codelinter 需要在 HarmonyOS 项目根目录下运行（它依赖项目中的code-linter.json5配置与模块上下文）。

3.3 仅使用 codelinter：禁用内置规则

如果你希望完全以 DevEco 官方检查为准，可以加--no-builtin-rules标志，此时内置规则不加载、CustomRuleChecker不创建，检查结果全部来自 codelinter：

python arkts_linter_cli.py --codelinter-path "D:/command-line-tools/bin/codelinter.bat" \ --target-path ./src --output report.json --no-builtin-rules

从 arkts_linter.py 的解析逻辑看，内置规则默认开启，只有显式指定--no-builtin-rules才会关闭，避免用户误操作导致安全规则漏检。

3.4 增量检查与自定义规则配置

# 增量检查（-i/--incremental），仅检查变更文件 python arkts_linter_cli.py --target-path ./src --incremental --output report.json # 使用自定义规则配置文件（YAML 格式） python arkts_linter_cli.py --target-path ./src --rules-config ./my_rules.yaml --output report.json

--incremental会被透传给 codelinter 的-i参数（见 runner.py），适合在大规模仓库中只重查改动文件以缩短 CI 耗时；--rules-config则让内置检查引擎完全改用你提供的规则集，具体格式见第五节。

3.5 命令行参数总览

需要说明的是，阈值参数（--error-threshold/--warning-threshold）在当前版本的 ReportGenerator.generate_report 中，门禁判定采用的是硬编码逻辑「严重问题数 > 0 即 FAIL，一般问题数 > 10 即 FAIL」；阈值参数已接入 CLI 解析层，可供后续版本将判定阈值参数化，这一点从源码结构可以推断。

四、门禁规则体系：内置规则集的构成

README 声明内置规则覆盖 64 条门禁规则，实际打开 config/rules.yaml 可以看到65 个规则条目（其中 G.TYP.08 存在带 [OpenHarmony] 后缀与不带后缀的重复条目，去重后为 64 条有效规则，与 README 描述吻合）。规则按严重级别分为三档：

• CRITICAL（严重）：3 条资源泄漏类规则——图片资源（image.createImageSource/createPixelMap）、数据库资源（rdbStore/resultSet/querySql）、socket/rcp 会话（new TCPSocket/rcp.createSession等）打开后未释放/未关闭即直接判定门禁失败；
• NORMAL（一般）：安全类规则为主体，含 21 条SecH_ATs_HW_CBG_CS_*系列 HarmonyOS 安全规则，以及「禁止密钥硬编码」「禁止日志打印敏感信息」「JSON.parse/stringify 未捕获异常」「文件流未在 finally 中关闭」等中文命名的安全检查；
• HINT（提示）：代码规范类，31 条以G.*编号的规则，覆盖命名（G.NAM）、类型（G.TYP）、格式（G.FMT）、声明（G.DCL）、异常（G.ERR）、控制流（G.CTL）、扩展（G.EXT）、变量（G.VAR）、其他（G.OTH）等多个维度。

4.1 关键规则速览

以下几条规则最能代表这套规则集的能力边界（均摘自 config/rules.yaml）：

• 图片资源泄漏（CRITICAL）：正则image\.createImageSource|createPixelMap命中后，check_release: true触发「资源使用完成后释放」检查——检查器会扫描命中行之后的代码（剥离注释后）是否存在close(/release(/reclaim(，否则报错；
• 隐式启动携带敏感数据：startAbility.*implicitWant命中即报「隐式启动应用组件时携带严重级别数据或敏感数据」；
• 不安全的 MD5 算法：MD5|md5命中且属于unsafe_algorithms列表（MD5/SHA1/DES），建议改用 AES256、SHA256、RSA2048 等合规算法，CWE 编号 327；
• 硬编码公网地址（G.OTH.05）：正则https?://(?!localhost|127\.0\.0\.1|.*\.local)通过负向断言豁免本地地址，报「禁止代码中包含公网地址」；
• finally 块异常跳转（G.ERR.03）：finally\s*\{[^}]*\b(return|break|continue|throw)\b多行匹配，阻止 finally 中使用 return/break/continue/throw，CWE 584。

4.2 规则 ID 与 CWE 映射

规则名统一遵循两类命名：一类是G.XXX.NN 中文描述（源自通用编码规范门禁，如 G.NAM.01、G.FMT.02），另一类是SecH_ATs_HW_CBG_CS_xxx_OpenHarmony（HarmonyOS 安全编码门禁）。工具在 utils/helpers.py 的extract_rule_id()中通过正则([GS]\.[A-Z]+\.\d+|SecH_[A-Za-z_]+)从规则名提取标准化规则 ID，用于报告中的rule_id字段。多数规则还标注了 CWE（Common Weakness Enumeration）编号，例如 CWE 321（密钥硬编码）、CWE 532（敏感信息泄露）、CWE 312（敏感数据存储）、CWE 1078（代码格式）、CWE 1099（命名规范），方便与安全漏洞库联动。

五、规则配置：YAML 格式与扩展能力

规则配置文件使用 YAML 格式，位于 config/rules.yaml。你可以修改现有规则配置、添加新规则，或用--rules-config指定自定义配置文件。配置顶层是一个rules映射，每个规则名对应一个配置对象：

rules: "规则名称": level: NORMAL # 严重级别: CRITICAL, NORMAL, HINT cwe: "123" # CWE 编号 pattern: '正则表达式' suggestion: "修改建议" # 其他配置选项...

其中level会被 rule_loader.py 转换为 models.py 中的RuleLevel枚举（严重/一般/提示）。若指定的配置文件不存在，加载器会抛出FileNotFoundError，避免静默降级。

5.1 特殊检查开关：从 YAML 字段到检查语义

除了pattern这一基础正则，checker.py 的_apply_rule/_check_specific_condition还支持一整套按需启用的语义化检查字段，让正则命中后再做上下文判定、降低误报。以下字段均可直接写进自定义规则的 YAML：

5.2 兼容更多检查器的细节

• 注释剥离：默认情况下，检查器会先用 checker.py 的_remove_comments_from_lines()对每行做「字符串感知」的注释剥离（保留"/'/`字符串内的//与/*，保持行号对齐），再套用规则正则，因此注释里的疑似代码不会误报——除非该规则显式设置check_commented_code；
• 同类去重：同一行命中同一规则只报告一次（reported_lines集合去重，见 checker.py），避免正则多分组产生重复 issue；
• 异常隔离：单条规则正则出错（re.error）只会打印警告、不影响其余规则继续执行。

六、作为 Python 包使用

除了命令行，工具还提供了面向二次开发/流水线脚本的 Python API。包级入口在init.py，导出ArkTSLinter与main：

from arkts_linter import ArkTSLinter # 创建 linter 实例 linter = ArkTSLinter( codelinter_path="D:/command-line-tools/bin/codelinter.bat", use_builtin_rules=True ) # 执行检查 report = linter.check( target_path="./src", output_path="report.json" ) # 查看结果 print(f"门禁结果: {report.gate_result}") print(f"总问题数: {report.total_issues}")

构造函数签名（见 arkts_linter.py）与命令行参数一一对应：codelinter_path、node_path、use_builtin_rules、rules_config_path。check()返回的LintReport对象（models.py）包含以下字段：

• project_path、scan_time：项目路径与扫描时间（ISO 8601 格式）；
• total_files：涉及问题的文件数（按文件路径去重）；
• total_issues/error_count/warning_count/suggestion_count：总数与严重/一般/提示三级计数（另有critical_count/normal_count/hint_count三个等价属性）；
• issues：LintIssue列表，每个问题含file_path、line、column、rule_id、rule_name、severity、message、suggestion、cwe；
• rule_statistics：以规则名为 key 的命中次数统计字典；
• gate_result/gate_message：门禁结论（PASS/FAIL）与说明。

LintIssue数据类（models.py）的cwe字段默认空串，当规则配置中未给出 CWE 编号时留空。

七、输出报告与门禁判定

7.1 JSON 报告结构

报告由 utils/report.py 的ReportGenerator生成，以 UTF-8 + 2 空格缩进写入 JSON（ensure_ascii=False，中文可读），包含 README 列出的全部要素：

• 项目路径（project_path）
• 扫描时间（scan_time）
• 检查文件数（total_files）
• 问题统计：严重/一般/提示三级计数
• 问题详情列表（issues，含文件、行、列、规则 ID/名称、级别、消息、建议、CWE）
• 规则统计（rule_statistics，每条规则命中次数）
• 门禁结果（gate_result/gate_message）

7.2 门禁判定逻辑与退出码

门禁判定（report.py）当前规则为：发现任意严重（CRITICAL）问题即 FAIL；一般（NORMAL）问题超过 10 条即 FAIL；仅提示（HINT）问题不影响通过。判定结果同时映射到进程退出码（arkts_linter.py）：

• 0：门禁 PASS（gate_result == "PASS"），流水线继续；
• 1：门禁 FAIL，流水线中断；
• 2：检查过程异常（如目标路径不存在、规则配置缺失、运行时异常），此时会打印堆栈便于排障。

7.3 控制台摘要

每次检查后工具还会打印一份对齐的控制台摘要，便于本地开发即时查看，例如：

============================================================ ArkTS 门禁检查报告 ============================================================ 项目路径: ./src 扫描时间: 2026-10-13T12:30:00.000000 检查文件数: 12 ------------------------------------------------------------ 严重问题: 0 一般问题: 3 提示问题: 5 总问题数: 8 ------------------------------------------------------------ 门禁结果: PASS 门禁信息: 所有检查通过 ============================================================

随后输出问题详情（默认只打印前 20 条，超出部分提示查阅 JSON 报告）。

八、工作原理：从扫描到门禁的完整链路

8.1 文件扫描：.ets/.ts 双后缀

core/scanner.py 的ArkTSFileScanner定义ARKTS_EXTENSIONS = {'.ets', '.ts'}，对目录使用os.walk递归收集（后缀大小写不敏感），对单文件则直接判定后加入列表。这也解释了--target-path既能传文件又能传目录的原因——检查范围天然覆盖 ArkTS 的两种源码形态。

8.2 codelinter 集成：命令构建与 Node 探测

core/runner.py 的CodeLinterRunner负责外部进程调度，命令构建逻辑对三种 codelinter 形态做了适配：

1. 路径以.js结尾 → 视为 IDE 内置插件，命令为[node_path, index.js]；
2. 路径以.bat结尾且运行在 Linux/macOS → 自动寻找同名.sh脚本，找不到则回退直接执行；
3. 其余情况 → 视为独立 CLI 直接执行。

参数映射：-c（配置，code-linter.json5）、-f（输出格式，默认 json）、-o（输出文件）、-i（增量）、-e（错误级别，默认 error），目标路径作为最后一个位置参数。若未显式传--node-path，_find_node()会依次尝试：环境变量NODE_PATH→ 各平台常见安装路径（Windows 的 DevEco Studio 内置 node、Linux/macOS 的/usr/local/bin/node、nvm 通配路径等）→where/which命令 → 最终回退到 PATH 中的node。执行后优先读取-o指定的输出文件，否则尝试解析 stdout JSON；JSON 解析失败时会把stdout/stderr/returncode原样打包返回。

8.3 双引擎结果合并

ArkTSLinter.check()会把内置规则检查器产出的LintIssue与_parse_codelinter_result()解析出的 codelinter 问题合并到同一个all_issues列表。codelinter 结果解析按通用字典格式处理：遍历files[].messages[]，将line、column、ruleId、message、suggestion映射为LintIssue；严重级别通过_map_severity()完成 2=严重、1=一般、0=提示 的映射（arkts_linter.py），使得两套引擎的输出可以统一进同一份报告与同一条门禁判定。

8.4 面向 OpenHarmony 的规则特色

作为 flutter_flutter 适配仓的 CI 工具链成员，这套规则集带有明显的 OpenHarmony 平台烙印：21 条SecH_ATs_HW_CBG_CS_*规则直指 HarmonyOS 特有 API 的误用——startUsingPermission需错误处理、javaScriptProxy注册需带permission属性、onOverrideUrlLoading是不可信回调不应承载业务逻辑、onRemoteMessageRequest需校验 InterfaceToken、setWebDebuggingAccess(true)禁止开启、敏感数据禁止落盘到/sdcard/、/storage/、/data/app/等非加密路径。配合 CWE 编号，这些规则构成了一套可审计、可追溯的 OpenHarmony 安全编码基线，可直接嵌入仓库的 CI 门禁流程。

九、支持的平台与许可

工具本体为纯 Python 实现，跨平台支持Windows、Linux、macOS三端；codelinter 部分对.bat与.sh做了自动互转适配，因此三端均可接入 DevEco 的检查引擎。代码版权归属 2025 Huawei Device Co., Ltd.，遵循 BSD-style（LICENSE_HW）许可，README 标注为 MIT License；规则配置与源码同目录存放，便于直接审计与二次裁剪。

十、实战建议：快速落地门禁流水线

1. 最小接入：在 CI 中直接执行python ci/scripts/arkts_linter_cli.py --target-path <模块源码目录> --output arkts_report.json，利用内置 64 条门禁规则即可获得第一道安全/规范防线，无需外部依赖；
2. 强校验接入：为 DevEco 环境配置--codelinter-path与--config code-linter.json5，让官方引擎与内置规则并行，覆盖内置规则未触及的语义类问题；
3. 增量提速：对大型仓使用--incremental，结合版本管理工具仅提交变更文件路径，把全量扫描的分钟级耗时压缩到秒级；
4. 规则定制：复制config/rules.yaml为my_rules.yaml，按第五节字段语义追加团队专属规则（如特定业务关键词、内部 API 白名单），用--rules-config接入；
5. 门禁联动：根据退出码 0/1/2 控制流水线分支，把 JSON 报告归档为构建产物，方便事后按rule_name/cwe维度聚合分析历史问题趋势。

以上所有命令、配置与结论均可直接在 flutter_flutter 仓库的 ci/scripts/arkts_linter 目录中复现验证。

• 跨平台
• 前端
• 移动开发
• OpenHarmony