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@default

6.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 构建链路剖析》，将带您深入玄象项目的构建配置与构建工具链。