HarmonyOS应用《玄象》开发实战：code-linter.json5 配置：ArkTS 严格模式下的代码规范
阅读时长：约 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的配置分为四大块：
| 字段 | 类型 | 作用 |
|---|---|---|
files | string[] | 检查文件范围 |
ignore | string[] | 忽略文件范围 |
ruleSet | string[] | 启用的规则集 |
rules | object | 单条规则覆盖 |
二、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/recommended"@performance/recommended是 HarmonyOS 官方提供的性能优化规则集，主要检查：
| 规则 | 检查内容 |
|---|---|
@performance/no-uninstantiated-objects | 未实例化对象检测 |
@performance/no-async-in-for-each | forEach 中禁止异步 |
@performance/no-large-object-in-state | @State 中禁止大对象 |
@performance/no-broad-foreach | forEach 范围过大检测 |
@performance/no-complex-builder | Builder 复杂度检测 |
3.2 TypeScript 规则集
"plugin:@typescript-eslint/recommended"@typescript-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/recommended+@typescript-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": "error"no-unsafe-aes规则检查 AES 加密算法的安全性：
| 危险模式 | 说明 |
|---|---|
| AES-ECB 模式 | ECB 模式不使用 IV，相同明文加密后密文相同 |
| 64 位块大小 | 块大小过小易受生日攻击 |
| 硬编码密钥 | 密钥不应硬编码在代码中 |
提示：玄象项目若未来涉及 AI 助手对话加密，必须使用 AES-256-GCM 模式，而非 ECB 模式。
4.4 哈希算法规则
"@security/no-unsafe-hash": "error"no-unsafe-hash规则禁止使用弱哈希算法：
| 算法 | 风险 | 替代方案 |
|---|---|---|
| MD5 | 已被破解，存在碰撞 | SHA-256 |
| SHA-1 | 已被破解，存在碰撞 | SHA-256 |
| CRC32 | 不具备密码学安全性 | 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": "error"no-unsafe-3des规则禁止使用 3DES 算法：
- 风险：3DES 块大小仅 64 位，易受生日攻击。
- 替代方案：使用 AES-256。
4.7 MAC 算法规则
"@security/no-unsafe-mac": "warn"no-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}from'@ohos/hvigor-ohos-plugin';exportdefault{system:appTasks,plugins:[// 集成 lint 任务]};6.2 命令行执行
# 通过 hvigor 命令行执行 linthvigorw codeLinter--modemodule-pmodule=entry@default6.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:any=this.getData();// 修复后constdata:LunarData=this.getData();八、玄象项目 lint 配置演进路线
8.1 当前阶段：基础规则集
玄象项目当前启用@performance/recommended+@typescript-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-linter
- HarmonyOS 官方文档：安全规则集
- HarmonyOS 官方文档：性能规则集
- TypeScript ESLint：typescript-eslint.io
- 开源鸿蒙跨平台社区：https://openharmonycrossplatform.csdn.net