★ FEATURED ARTICLE 跨平台前端移动开发OpenHarmony【免费下载链接】flutter_flutter本仓库是 Flutter SDK 与 Flutter Engine 的 OpenHarmony 适配版本由 CPF-Flutter 团队维护。开发者可使用熟悉的 Flutter 技术栈开发 OpenHarmony 应用3.35.7 及以后的适配版本可基于本仓库源码构建支持 OpenHarmony 的 Flutter Engine。项目地址https://gitcode.com/CPF-Flutter/flutter_flutter点击查看免费下载导读ArkTS Linter 是 flutter_flutterFlutter 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不创建检查结果全部来自 codelinterpython 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 命令行参数总览参数说明默认值--codelinter-pathcodelinter 路径.bat 文件或 index.js无不启用 codelinter--node-pathNode.js 路径当 codelinter-path 是 index.js 时需要自动探测--target-path要检查的目标路径文件或目录必需无--output, -o输出报告路径arkts_lint_report.json--config, -ccodelinter 配置文件路径code-linter.json5无--rules-config自定义规则配置文件路径YAML 格式包内config/rules.yaml--incremental, -i增量检查仅检查变更文件关闭--no-builtin-rules不使用内置规则只使用 codelinter关闭--error-threshold严重错误阈值超过则门禁失败0--warning-threshold一般警告阈值超过则门禁失败10需要说明的是阈值参数--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.03finally\s*\{[^}]*\b(return|break|continue|throw)\b多行匹配阻止 finally 中使用 return/break/continue/throwCWE 584。4.2 规则 ID 与 CWE 映射规则名统一遵循两类命名一类是G.XXX.NN 中文描述源自通用编码规范门禁如 G.NAM.01、G.FMT.02另一类是SecH_ATs_HW_CBG_CS_xxx_OpenHarmonyHarmonyOS 安全编码门禁。工具在 utils/helpers.py 的extract_rule_id()中通过正则([GS]\.[A-Z]\.\d|SecH_[A-Za-z_])从规则名提取标准化规则 ID用于报告中的rule_id字段。多数规则还标注了 CWECommon 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字段作用相关规则示例check_release/check_close命中后检查后续代码是否有close(/release(/reclaim(无则报资源泄漏图片/数据库/socket 资源泄漏CRITICALcheck_catch命中后检查当前函数范围内是否有.catch(或try无则报异常未捕获SecH_ATs_HW_CBG_CS_promise_catch_OpenHarmonycheck_finally命中后检查剩余代码是否含finally文件流关闭规则sensitive_keywords命中且所在行不含mask/anony匿名化处理时报告敏感信息泄露禁止日志打印敏感信息、G.WST.01unsafe_algorithms匹配文本属于不安全算法列表时报告MD5/SHA1/DES 相关规则check_hardcode检测行内超过 8 字符的字符串字面量硬编码SecH_ATs_HW_CBG_CS_HardCode_OpenHarmonycheck_try_catch通过is_inside_try_block()判断命中行是否已处于 try 块内在块内则不报JSON.parse/stringify 异常捕获in_class_only仅当命中行位于类定义内且非接口且无访问修饰符时报告G.EXT.01 类属性访问修饰符require_braces/require_braces_always检测 if/for/while 语句是否强制使用大括号多行条件自动豁免G.FMT.09、G.FMT.11multiline_match以re.MULTILINE | re.DOTALL对全文跨行匹配G.FMT.06else/catch 同行、G.FMT.10、G.ERR.03operator_at_line_start专门检查表达式换行时运算符是否误放行首应放行末G.FMT.03check_commented_code对原始行含注释匹配检测被注释掉的代码G.OTH.03check_indentation校验 switch 的 case/default 是否比 switch 多缩进 2 个空格G.FMT.12naming_convention/exclude_patterns命名规范与豁免模式G.NAM.01~G.NAM.045.2 兼容更多检查器的细节注释剥离默认情况下检查器会先用 checker.py 的_remove_comments_from_lines()对每行做「字符串感知」的注释剥离保留//字符串内的//与/*保持行号对齐再套用规则正则因此注释里的疑似代码不会误报——除非该规则显式设置check_commented_code同类去重同一行命中同一规则只报告一次reported_lines集合去重见 checker.py避免正则多分组产生重复 issue异常隔离单条规则正则出错re.error只会打印警告、不影响其余规则继续执行。六、作为 Python 包使用除了命令行工具还提供了面向二次开发/流水线脚本的 Python API。包级入口在init.py导出ArkTSLinter与mainfrom arkts_linter import ArkTSLinter # 创建 linter 实例 linter ArkTSLinter( codelinter_pathD:/command-line-tools/bin/codelinter.bat, use_builtin_rulesTrue ) # 执行检查 report linter.check( target_path./src, output_pathreport.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三个等价属性issuesLintIssue列表每个问题含file_path、line、column、rule_id、rule_name、severity、message、suggestion、cwerule_statistics以规则名为 key 的命中次数统计字典gate_result/gate_message门禁结论PASS/FAIL与说明。LintIssue数据类models.py的cwe字段默认空串当规则配置中未给出 CWE 编号时留空。七、输出报告与门禁判定7.1 JSON 报告结构报告由 utils/report.py 的ReportGenerator生成以 UTF-8 2 空格缩进写入 JSONensure_asciiFalse中文可读包含 README 列出的全部要素项目路径project_path扫描时间scan_time检查文件数total_files问题统计严重/一般/提示三级计数问题详情列表issues含文件、行、列、规则 ID/名称、级别、消息、建议、CWE规则统计rule_statistics每条规则命中次数门禁结果gate_result/gate_message7.2 门禁判定逻辑与退出码门禁判定report.py当前规则为发现任意严重CRITICAL问题即 FAIL一般NORMAL问题超过 10 条即 FAIL仅提示HINT问题不影响通过。判定结果同时映射到进程退出码arkts_linter.py0门禁 PASSgate_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 形态做了适配路径以.js结尾 → 视为 IDE 内置插件命令为[node_path, index.js]路径以.bat结尾且运行在 Linux/macOS → 自动寻找同名.sh脚本找不到则回退直接执行其余情况 → 视为独立 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 JSONJSON 解析失败时会把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-styleLICENSE_HW许可README 标注为 MIT License规则配置与源码同目录存放便于直接审计与二次裁剪。十、实战建议快速落地门禁流水线最小接入在 CI 中直接执行python ci/scripts/arkts_linter_cli.py --target-path 模块源码目录 --output arkts_report.json利用内置 64 条门禁规则即可获得第一道安全/规范防线无需外部依赖强校验接入为 DevEco 环境配置--codelinter-path与--config code-linter.json5让官方引擎与内置规则并行覆盖内置规则未触及的语义类问题增量提速对大型仓使用--incremental结合版本管理工具仅提交变更文件路径把全量扫描的分钟级耗时压缩到秒级规则定制复制config/rules.yaml为my_rules.yaml按第五节字段语义追加团队专属规则如特定业务关键词、内部 API 白名单用--rules-config接入门禁联动根据退出码 0/1/2 控制流水线分支把 JSON 报告归档为构建产物方便事后按rule_name/cwe维度聚合分析历史问题趋势。以上所有命令、配置与结论均可直接在 flutter_flutter 仓库的 ci/scripts/arkts_linter 目录中复现验证。赞分享跨平台前端移动开发OpenHarmony【免费下载链接】flutter_flutter本仓库是 Flutter SDK 与 Flutter Engine 的 OpenHarmony 适配版本由 CPF-Flutter 团队维护。开发者可使用熟悉的 Flutter 技术栈开发 OpenHarmony 应用3.35.7 及以后的适配版本可基于本仓库源码构建支持 OpenHarmony 的 Flutter Engine。项目地址https://gitcode.com/CPF-Flutter/flutter_flutter点击查看免费下载相关推荐flutter_flutter 仓库的 Agent 开发规则与代码质量门禁实践指南flutter_flutter 仓库的 Agent 开发规则与代码质量门禁实践指南 本篇指南围绕本仓库根目录 AGENTS.md https://link.gi跨平台前端移动开发OpenHarmonyBasalt快速入门指南5分钟搭建你的第一个视觉惯性里程计系统Basalt快速入门指南5分钟搭建你的第一个视觉惯性里程计系统 Basalt是一个功能强大的视觉惯性里程计VIO系统能够帮助机器人和无人机实现精准的定位计算机视觉机器人SVGR代码质量门禁示例自动化质量检查SVGR代码质量门禁示例自动化质量检查 在前端开发中SVG图标作为React组件使用时常常面临质量不一致、属性冲突和格式不规范等问题。本文将通过SVGR的命前端开发工具上一篇MTK设备终极救砖指南零基础快速解锁联发科芯片的完整解决方案下一篇微博图片爬虫高效批量下载与智能管理解决方案创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
阅读完成 · 觉得有帮助？
