Code Linter 与代码质量 — 使用 code-linter.json5 保障工程规范文章简介在团队协作开发中统一的代码风格和质量标准是保障工程可维护性的基石。HarmonyOS 提供了 Code Linter 工具通过code-linter.json5配置文件定义代码风格和安全规则。MoneyTrack 项目配置了包括 typescript-eslint 规则、安全规则和性能规则在内的完整 Linter 体系。本文从 Linter 在开发流程中的定位出发详细解析配置语法、规则体系、命名规范以及 CI/CD 集成方案。Linter 在开发流程中的位置Code Linter 应嵌入到从编码到发布的整个流程中形成自动化的质量门禁是否是否无有编码阶段本地 Lint 检查是否通过代码提交Pre-commit Hook再次通过推送到远程CI 流水线全量 Lint 扫描质量问题代码合并自动部署核心知识点1. code-linter.json5 完整配置code-linter.json5是 Code Linter 的核心配置文件位于项目根目录下。MoneyTrack 项目的完整配置如下{ // 指定要扫描的文件匹配模式 files: [**/*.ets, **/*.ts], // 排除不需要扫描的目录 ignore: [ **/ohosTest/**/*, **/test/**/*, **/build/**/*, **/oh_modules/**/* ], // 启用规则集plugin 前缀表示来自插件 ruleSet: [ plugin:performance/recommended, plugin:typescript-eslint/recommended, plugin:hw-stylistic/recommended, plugin:security/recommended ], // 细粒度规则配置覆盖 ruleSet 中的默认行为 rules: { // 安全规则 security/no-unsafe-aes: error, security/no-hardcoded-credentials: error, // TypeScript 类型规则 typescript-eslint/await-thenable: error, typescript-eslint/no-floating-promises: error, typescript-eslint/explicit-member-accessibility: [error, { accessibility: explicit, overrides: { constructors: no-public } }], typescript-eslint/consistent-type-definitions: [error, interface], typescript-eslint/prefer-readonly: warn, // 命名规范 typescript-eslint/naming-convention: [error, { selector: default, format: [camelCase, UPPER_CASE] }, { selector: variable, format: [camelCase, UPPER_CASE] }, { selector: function, format: [camelCase] }, { selector: class, format: [PascalCase] }, { selector: interface, format: [PascalCase] }, { selector: enum, format: [PascalCase] }, { selector: enumMember, format: [UPPER_CASE] }, { selector: memberLike, modifiers: [private], format: [camelCase], leadingUnderscore: require }], // 风格规则 hw-stylistic/quotes: [error, single], hw-stylistic/semi: [error, always], hw-stylistic/comma-dangle: [error, always-multiline], hw-stylistic/indent: [error, 2], hw-stylistic/max-len: [warn, { code: 120 }], // 变量声明规则 init-declarations: [error, always] } }配置字段说明字段类型说明filesstring[]文件匹配模式决定哪些文件被扫描ignorestring[]排除模式跳过不需要检查的目录ruleSetstring[]引用的预定义规则集支持plugin:前缀rulesobject单个规则的启用/禁用/配置值可为off、warn、error或配置数组2. typescript-eslint 常用规则详解规则名级别作用违反示例正确示例await-thenableerror禁止 await 非 Promise 值await someStringawait somePromiseno-floating-promiseserror禁止未处理的 PromiseasyncFunc()await asyncFunc()explicit-member-accessibilityerror要求显式成员访问修饰符name: stringpublic name: stringconsistent-type-definitionserror强制使用 interfacetype User { id: number }interface User { id: number }prefer-readonlywarn建议只读成员加 readonlyprivate id: numberprivate readonly id: numbernaming-conventionerror强制统一命名规范class user_serviceclass UserServiceno-unused-varserror禁止声明未使用的变量const x 1未使用删除或使用_x前缀prefer-optional-chainwarn建议使用可选链a a.ba?.b3. 命名规范完整要求MoneyTrack 项目遵循以下命名规范由naming-convention规则强制执行代码元素规范示例说明变量普通camelCaseuserName、billList、totalAmount普通变量统一小驼峰变量常量UPPER_CASEMAX_RETRY_COUNT、API_BASE_URL全局常量全大写下划线函数/方法camelCaseinitData()、refreshBill()、getTotalIncome()动宾结构小驼峰类PascalCaseHomeVM、StatisticsVM、BillRepository名词或名词短语接口PascalCaseIBill、IUserInfo、PageState可以是I前缀或无前缀枚举PascalCaseBillType、Category、TransactionStatus名词形式枚举成员UPPER_CASEEXPENSE、INCOME、PENDING、COMPLETED全大写下划线私有成员camelCase _前缀_instance、_cacheData、_subscription下划线开头表示私有类型参数PascalCase 单字母T、K、V、R泛型统一单大写字母项目中的实际应用// ✅ 符合规范constMAX_PAGE_SIZE:number50;letuserName:string;classHomeVM{privatereadonly_instance:HomeVM;private_billList:Bill[][];publicasyncinitData():Promisevoid{// 初始化逻辑}publicgetTotalIncome():number{returnthis._billList.reduce((sum,bill)sumbill.amount,0);}}interfaceIBill{id:string;amount:number;category:Category;}enumCategory{FOODFOOD,TRANSPORTTRANSPORT,ENTERTAINMENTENTERTAINMENT,}// ❌ 违反规范classhome_vm{}// 类必须 PascalCasefunctionGet_Data(){}// 函数必须 camelCaseletUser_Nametest;// 变量必须 camelCaseconstmax_count10;// 常量必须 UPPER_CASE4. CI/CD 集成Pre-commit Hook 配置在.husky/pre-commit中配置提交前自动运行 Linter#!/bin/sh.$(dirname$0)/_/husky.sh# 对暂存的文件运行 Linternpx code-linter--files$(gitdiff--cached--name-only --diff-filterd|grep-E\.(ets|ts)$|tr\n,)if[$?-ne0];thenecho❌ Lint 检查未通过请修复后重新提交exit1fiCI 流水线集成oh-pipeline.json5{ stages: [{ name: quality-gate, jobs: [{ name: code-lint, steps: [ { name: 安装依赖, command: ohpm install }, { name: 运行 Linter, command: code-linter --config code-linter.json5 }, { name: 运行单元测试, command: ohos test --build-type local } ] }] }] }最佳实践渐进式启用不要一次性开启所有规则。先启用核心规则如命名规范、安全规则等团队适应后再逐步增加风格类规则避免大量报错打乱开发节奏。规则覆盖优先级rules中的单个规则配置优先级高于ruleSet中的默认配置。在ruleSet基础上通过rules微调而不需要删除整个规则集。Lint 即文档将命名规范、代码风格等约定通过 Linter 规则强制执行而不是写在团队规范文档中。这样新的团队成员不需要记忆大量规则Linter 会实时提示。CI 门禁在 CI 流水线中设置 Lint 检查为门禁卡点Lint 未通过的代码不能合并到主分支。这比依赖开发人员自觉性更可靠。阶段区分在本地开发和 pre-commit 阶段只对变更文件进行检查速度快在 CI 阶段对全量文件扫描确保全面两者配合使用。定期审查每个迭代结束后审查 Linter 报错统计如果某些规则频繁被违反考虑是否规则过于严格或不合理及时调整配置。推荐参考文档HarmonyOS Code Linter 工具文档typescript-eslint 规则参考code-linter.json5 配置语法代码审查最佳实践指南
HarmonyOS掌上记账APP开发实践第80篇：Code Linter 与代码质量 — 使用 code-linter.json5 保障工程规范
Code Linter 与代码质量 — 使用 code-linter.json5 保障工程规范文章简介在团队协作开发中统一的代码风格和质量标准是保障工程可维护性的基石。HarmonyOS 提供了 Code Linter 工具通过code-linter.json5配置文件定义代码风格和安全规则。MoneyTrack 项目配置了包括 typescript-eslint 规则、安全规则和性能规则在内的完整 Linter 体系。本文从 Linter 在开发流程中的定位出发详细解析配置语法、规则体系、命名规范以及 CI/CD 集成方案。Linter 在开发流程中的位置Code Linter 应嵌入到从编码到发布的整个流程中形成自动化的质量门禁是否是否无有编码阶段本地 Lint 检查是否通过代码提交Pre-commit Hook再次通过推送到远程CI 流水线全量 Lint 扫描质量问题代码合并自动部署核心知识点1. code-linter.json5 完整配置code-linter.json5是 Code Linter 的核心配置文件位于项目根目录下。MoneyTrack 项目的完整配置如下{ // 指定要扫描的文件匹配模式 files: [**/*.ets, **/*.ts], // 排除不需要扫描的目录 ignore: [ **/ohosTest/**/*, **/test/**/*, **/build/**/*, **/oh_modules/**/* ], // 启用规则集plugin 前缀表示来自插件 ruleSet: [ plugin:performance/recommended, plugin:typescript-eslint/recommended, plugin:hw-stylistic/recommended, plugin:security/recommended ], // 细粒度规则配置覆盖 ruleSet 中的默认行为 rules: { // 安全规则 security/no-unsafe-aes: error, security/no-hardcoded-credentials: error, // TypeScript 类型规则 typescript-eslint/await-thenable: error, typescript-eslint/no-floating-promises: error, typescript-eslint/explicit-member-accessibility: [error, { accessibility: explicit, overrides: { constructors: no-public } }], typescript-eslint/consistent-type-definitions: [error, interface], typescript-eslint/prefer-readonly: warn, // 命名规范 typescript-eslint/naming-convention: [error, { selector: default, format: [camelCase, UPPER_CASE] }, { selector: variable, format: [camelCase, UPPER_CASE] }, { selector: function, format: [camelCase] }, { selector: class, format: [PascalCase] }, { selector: interface, format: [PascalCase] }, { selector: enum, format: [PascalCase] }, { selector: enumMember, format: [UPPER_CASE] }, { selector: memberLike, modifiers: [private], format: [camelCase], leadingUnderscore: require }], // 风格规则 hw-stylistic/quotes: [error, single], hw-stylistic/semi: [error, always], hw-stylistic/comma-dangle: [error, always-multiline], hw-stylistic/indent: [error, 2], hw-stylistic/max-len: [warn, { code: 120 }], // 变量声明规则 init-declarations: [error, always] } }配置字段说明字段类型说明filesstring[]文件匹配模式决定哪些文件被扫描ignorestring[]排除模式跳过不需要检查的目录ruleSetstring[]引用的预定义规则集支持plugin:前缀rulesobject单个规则的启用/禁用/配置值可为off、warn、error或配置数组2. typescript-eslint 常用规则详解规则名级别作用违反示例正确示例await-thenableerror禁止 await 非 Promise 值await someStringawait somePromiseno-floating-promiseserror禁止未处理的 PromiseasyncFunc()await asyncFunc()explicit-member-accessibilityerror要求显式成员访问修饰符name: stringpublic name: stringconsistent-type-definitionserror强制使用 interfacetype User { id: number }interface User { id: number }prefer-readonlywarn建议只读成员加 readonlyprivate id: numberprivate readonly id: numbernaming-conventionerror强制统一命名规范class user_serviceclass UserServiceno-unused-varserror禁止声明未使用的变量const x 1未使用删除或使用_x前缀prefer-optional-chainwarn建议使用可选链a a.ba?.b3. 命名规范完整要求MoneyTrack 项目遵循以下命名规范由naming-convention规则强制执行代码元素规范示例说明变量普通camelCaseuserName、billList、totalAmount普通变量统一小驼峰变量常量UPPER_CASEMAX_RETRY_COUNT、API_BASE_URL全局常量全大写下划线函数/方法camelCaseinitData()、refreshBill()、getTotalIncome()动宾结构小驼峰类PascalCaseHomeVM、StatisticsVM、BillRepository名词或名词短语接口PascalCaseIBill、IUserInfo、PageState可以是I前缀或无前缀枚举PascalCaseBillType、Category、TransactionStatus名词形式枚举成员UPPER_CASEEXPENSE、INCOME、PENDING、COMPLETED全大写下划线私有成员camelCase _前缀_instance、_cacheData、_subscription下划线开头表示私有类型参数PascalCase 单字母T、K、V、R泛型统一单大写字母项目中的实际应用// ✅ 符合规范constMAX_PAGE_SIZE:number50;letuserName:string;classHomeVM{privatereadonly_instance:HomeVM;private_billList:Bill[][];publicasyncinitData():Promisevoid{// 初始化逻辑}publicgetTotalIncome():number{returnthis._billList.reduce((sum,bill)sumbill.amount,0);}}interfaceIBill{id:string;amount:number;category:Category;}enumCategory{FOODFOOD,TRANSPORTTRANSPORT,ENTERTAINMENTENTERTAINMENT,}// ❌ 违反规范classhome_vm{}// 类必须 PascalCasefunctionGet_Data(){}// 函数必须 camelCaseletUser_Nametest;// 变量必须 camelCaseconstmax_count10;// 常量必须 UPPER_CASE4. CI/CD 集成Pre-commit Hook 配置在.husky/pre-commit中配置提交前自动运行 Linter#!/bin/sh.$(dirname$0)/_/husky.sh# 对暂存的文件运行 Linternpx code-linter--files$(gitdiff--cached--name-only --diff-filterd|grep-E\.(ets|ts)$|tr\n,)if[$?-ne0];thenecho❌ Lint 检查未通过请修复后重新提交exit1fiCI 流水线集成oh-pipeline.json5{ stages: [{ name: quality-gate, jobs: [{ name: code-lint, steps: [ { name: 安装依赖, command: ohpm install }, { name: 运行 Linter, command: code-linter --config code-linter.json5 }, { name: 运行单元测试, command: ohos test --build-type local } ] }] }] }最佳实践渐进式启用不要一次性开启所有规则。先启用核心规则如命名规范、安全规则等团队适应后再逐步增加风格类规则避免大量报错打乱开发节奏。规则覆盖优先级rules中的单个规则配置优先级高于ruleSet中的默认配置。在ruleSet基础上通过rules微调而不需要删除整个规则集。Lint 即文档将命名规范、代码风格等约定通过 Linter 规则强制执行而不是写在团队规范文档中。这样新的团队成员不需要记忆大量规则Linter 会实时提示。CI 门禁在 CI 流水线中设置 Lint 检查为门禁卡点Lint 未通过的代码不能合并到主分支。这比依赖开发人员自觉性更可靠。阶段区分在本地开发和 pre-commit 阶段只对变更文件进行检查速度快在 CI 阶段对全量文件扫描确保全面两者配合使用。定期审查每个迭代结束后审查 Linter 报错统计如果某些规则频繁被违反考虑是否规则过于严格或不合理及时调整配置。推荐参考文档HarmonyOS Code Linter 工具文档typescript-eslint 规则参考code-linter.json5 配置语法代码审查最佳实践指南
