阅读时长约 17 分钟 | 难度★★★☆☆ | 篇章第 1 篇 · 项目架构与设计哲学对应源码xuanxiang_ohos_app/code-linter.json5、xuanxiang_ohos_app/entry/build-profile.json5前言在团队协作与代码质量保证中静态代码检查是不可或缺的一环。HarmonyOS 提供了官方的代码检查工具code-linter它基于 TypeScript ESLint 引擎扩展而来专门为 ArkTS 语言特性设计。玄象项目通过code-linter.json5配置文件启用了性能规则集、TypeScript 规则集与安全规则集三大维度确保 45 个.ets文件在性能、类型安全、密码学安全三个层面均符合最佳实践。本篇将深入剖析玄象项目的code-linter.json5配置让您掌握在 ArkTS 项目中实施工业级代码规范的方法。提示code-linter 的安全规则集如security/no-unsafe-aes是 HarmonyOS 区别于普通前端 ESLint 配置的核心特性直接关系到应用上架审核。一、code-linter.json5 全貌1.1 完整配置{ files: [ **/*.ets ], ignore: [ **/src/ohosTest/**/*, **/src/test/**/*, **/src/mock/**/*, **/node_modules/**/*, **/oh_modules/**/*, **/build/**/*, **/.preview/**/* ], ruleSet: [ plugin:performance/recommended, plugin:typescript-eslint/recommended ], rules: { security/no-unsafe-aes: error, security/no-unsafe-hash: error, security/no-unsafe-mac: warn, security/no-unsafe-dh: error, security/no-unsafe-dsa: error, security/no-unsafe-ecdsa: error, security/no-unsafe-rsa-encrypt: error, security/no-unsafe-rsa-sign: error, security/no-unsafe-rsa-key: error, security/no-unsafe-dsa-key: error, security/no-unsafe-dh-key: error, security/no-unsafe-3des: error } }1.2 配置结构解析code-linter.json5的配置分为四大块字段类型作用filesstring[]检查文件范围ignorestring[]忽略文件范围ruleSetstring[]启用的规则集rulesobject单条规则覆盖二、files 与 ignore检查范围控制2.1 files 字段files: [ **/*.ets ]玄象项目检查所有.ets文件。**/*.ets是 glob 通配符**匹配任意层目录*.ets匹配所有 .ets 后缀文件2.2 ignore 字段ignore: [ **/src/ohosTest/**/*, **/src/test/**/*, **/src/mock/**/*, **/node_modules/**/*, **/oh_modules/**/*, **/build/**/*, **/.preview/**/* ]玄象项目忽略以下目录目录忽略理由src/ohosTest/**仪器化测试代码src/test/**单元测试代码src/mock/**Mock 数据node_modules/**第三方依赖oh_modules/**HarmonyOS 依赖build/**构建产物.preview/**预览缓存提示忽略build/**与oh_modules/**是性能优化的关键。这两类目录文件数量巨大纳入检查会显著拖慢 lint 速度。三、ruleSet启用的规则集3.1 性能规则集plugin:performance/recommendedperformance/recommended是 HarmonyOS 官方提供的性能优化规则集主要检查规则检查内容performance/no-uninstantiated-objects未实例化对象检测performance/no-async-in-for-eachforEach 中禁止异步performance/no-large-object-in-stateState 中禁止大对象performance/no-broad-foreachforEach 范围过大检测performance/no-complex-builderBuilder 复杂度检测3.2 TypeScript 规则集plugin:typescript-eslint/recommendedtypescript-eslint/recommended是 TypeScript 官方推荐规则集主要检查规则检查内容typescript-eslint/no-explicit-any禁止使用 any 类型typescript-eslint/no-unused-vars检测未使用的变量typescript-eslint/no-non-null-assertion禁止非空断言typescript-eslint/explicit-function-return-type函数返回值类型标注typescript-eslint/no-inferrable-types可推断类型无需显式标注3.3 玄象项目规则集选择策略玄象项目选择performance/recommendedtypescript-eslint/recommended的组合策略性能优先HarmonyOS 应用对启动性能、内存占用敏感性能规则集是必备。类型安全ArkTS 是 TypeScript 的方言类型安全规则保证代码可维护性。避免冗余未启用style/recommended等代码风格规则集避免与团队约定冲突。提示玄象项目当前未启用arkui/recommended规则集专门检查 ArkUI 组件规范。若团队规模扩大可启用该规则集强化 ArkUI 写法约束。四、rules安全规则集深度剖析4.1 密码学安全规则总览rules: { security/no-unsafe-aes: error, security/no-unsafe-hash: error, security/no-unsafe-mac: warn, security/no-unsafe-dh: error, security/no-unsafe-dsa: error, security/no-unsafe-ecdsa: error, security/no-unsafe-rsa-encrypt: error, security/no-unsafe-rsa-sign: error, security/no-unsafe-rsa-key: error, security/no-unsafe-dsa-key: error, security/no-unsafe-dh-key: error, security/no-unsafe-3des: error }4.2 规则严重等级玄象项目使用了三种严重等级等级含义玄象用途error报错阻止提交/构建密码学高危操作warn警告不阻止构建MAC 算法弱提示off关闭规则-4.3 AES 安全规则security/no-unsafe-aes: errorno-unsafe-aes规则检查 AES 加密算法的安全性危险模式说明AES-ECB 模式ECB 模式不使用 IV相同明文加密后密文相同64 位块大小块大小过小易受生日攻击硬编码密钥密钥不应硬编码在代码中提示玄象项目若未来涉及 AI 助手对话加密必须使用 AES-256-GCM 模式而非 ECB 模式。4.4 哈希算法规则security/no-unsafe-hash: errorno-unsafe-hash规则禁止使用弱哈希算法算法风险替代方案MD5已被破解存在碰撞SHA-256SHA-1已被破解存在碰撞SHA-256CRC32不具备密码学安全性SHA-256玄象项目的命盘生成若需要唯一标识应使用 SHA-256而非 MD5。4.5 RSA/DH/DSA/ECDSA 规则玄象项目对非对称加密算法均启用error级别检查security/no-unsafe-rsa-encrypt: error, security/no-unsafe-rsa-sign: error, security/no-unsafe-rsa-key: error, security/no-unsafe-dsa: error, security/no-unsafe-dsa-key: error, security/no-unsafe-dh: error, security/no-unsafe-dh-key: error, security/no-unsafe-ecdsa: error这些规则主要检查风险检查内容密钥长度不足RSA 密钥应 ≥ 2048 位弱填充方案RSA 应使用 OAEP 或 PSS 填充弱曲线参数ECDSA 应使用 NIST 推荐曲线DH 参数过小DH 素数应 ≥ 2048 位4.6 3DES 算法规则security/no-unsafe-3des: errorno-unsafe-3des规则禁止使用 3DES 算法风险3DES 块大小仅 64 位易受生日攻击。替代方案使用 AES-256。4.7 MAC 算法规则security/no-unsafe-mac: warnno-unsafe-mac规则警告弱 MAC 算法风险CBC-MAC 等弱 MAC 算法存在安全漏洞。替代方案使用 HMAC-SHA256。提示玄象项目将no-unsafe-mac设为warn而非error是因为部分场景下弱 MAC 仍有临时用途。但生产环境必须替换为强 MAC 算法。五、规则集与单条规则的优先级5.1 优先级机制code-linter.json5中的规则优先级如下rules.xxx (最高) ↑ ruleSet[] ↓ 默认规则 (最低)rules中的单条规则会覆盖ruleSet中的同名规则。5.2 玄象项目优先级实战玄象项目当前在rules中仅声明安全规则未覆盖性能规则或 TypeScript 规则rules: { // 仅安全规则未覆盖其他规则集 }若玄象项目未来想关闭 TypeScript 规则集中的no-explicit-any可这样配置rules: { typescript-eslint/no-explicit-any: off }六、玄象项目实际代码规范检查6.1 触发 lint 命令玄象项目可通过 DevEco Studio 的 “Code Linter” 面板触发检查也可在hvigorfile.ts中集成// hvigorfile.ts (假设扩展)import{appTasks}fromohos/hvigor-ohos-plugin;exportdefault{system:appTasks,plugins:[// 集成 lint 任务]};6.2 命令行执行# 通过 hvigor 命令行执行 linthvigorw codeLinter--modemodule-pmoduleentrydefault6.3 检查结果示例玄象项目典型的 lint 警告输出ERROR: src/main/ets/common/utils/LunarCalendar.ets performance/no-large-object-in-state State property lunarData exceeds 1KB, consider using StorageLink or AppStorage WARN: src/main/ets/pages/HomePage.ets typescript-eslint/no-unused-vars Variable tempIndex is declared but never used提示lint 输出后玄象项目开发者应优先修复ERROR级别问题WARN级别问题可在迭代中逐步解决。七、与 IDE 集成的代码提示7.1 DevEco Studio 集成DevEco Studio 默认集成code-linter可在编辑器中实时显示 lint 警告红色波浪线error级别规则违反黄色波浪线warn级别规则违反灰色提示未使用变量等7.2 玄象项目 IDE 提示示例当玄象项目代码出现以下情况时IDE 会立即提示场景IDE 提示使用 MD5 算法“Unsafe hash algorithm: MD5”在 forEach 中调用异步“Async call inside forEach is prohibited”State 中存储大对象“State property too large, use AppStorage instead”使用 any 类型“Type ‘any’ is not allowed”7.3 自动修复部分 lint 规则支持自动修复可通过 DevEco Studio 的 “Quick Fix” 功能⌥ Enter触发// 修复前constdata:anythis.getData();// 修复后constdata:LunarDatathis.getData();八、玄象项目 lint 配置演进路线8.1 当前阶段基础规则集玄象项目当前启用performance/recommendedtypescript-eslint/recommended 12 条安全规则覆盖核心检查维度。8.2 第二阶段ArkUI 规则集玄象项目规模扩大后可启用arkui/recommended规则集ruleSet: [ plugin:performance/recommended, plugin:typescript-eslint/recommended, plugin:arkui/recommended ]该规则集主要检查arkui/no-unused-state未使用的 State 变量arkui/no-direct-dom-access禁止直接 DOM 操作arkui/prefer-builder-over-method建议用 Builder 代替返回组件的方法8.3 第三阶段自定义规则玄象项目最终可定制化 lint 规则例如rules: { // 玄象特定规则 xuanxiang/no-hardcoded-color: error, // 禁止硬编码颜色必须用 Colors.XXX xuanxiang/prefer-styles-import: warn, // 建议 import Styles xuanxiang/no-console-log: error // 禁止 console.log必须用 hilog }总结本篇以玄象项目code-linter.json5配置为蓝本深入剖析了 HarmonyOS ArkTS 项目的静态代码检查体系从files/ignore范围控制、ruleSet规则集选择、rules单条规则覆盖到安全规则集AES / Hash / RSA / 3DES的实战剖析。掌握这套代码规范体系是构建工业级 HarmonyOS 应用、顺利通过 AppGallery 上架审核的必备能力。下一篇《08 · build-profile.json5 与 hvigor 构建链路剖析》将带您深入玄象项目的构建配置与构建工具链。如果这篇文章对你有帮助欢迎点赞、收藏⭐、关注你的支持是我持续创作的动力相关资源HarmonyOS 官方文档代码检查工具 code-linterHarmonyOS 官方文档安全规则集HarmonyOS 官方文档性能规则集TypeScript ESLinttypescript-eslint.io开源鸿蒙跨平台社区https://openharmonycrossplatform.csdn.net