Code Linter代碼檢查

Code Linter針對ArkTS/TS代碼進行最佳實踐/編程規范方面的檢查。檢查規則支持配置，配置方式請參考配置代碼檢查規則。

開發者可根據掃描結果中告警提示手工修復代碼缺陷，或者執行一鍵式自動修復，在代碼開發階段，確保代碼質量。

檢查方法：

在已打開的代碼編輯器窗口單擊右鍵點擊Code Linter，或在工程管理窗口中鼠標選中單個或多個工程文件/目錄，右鍵選擇Code Linter?> Full Linter執行代碼全量檢查。

如只需對Git工程中增量文件（包含新增/修改/重命名）進行檢查，可在commit界面右下角點擊齒輪圖標，選擇Incremental Linter執行增量檢查。

說明

• 若未配置代碼檢查規則文件，直接執行Code Linter，將按照默認的編程規范規則對.ets文件進行檢查。
• Code Linter不對如下文件及目錄進行檢查：
  • src/ohosTest文件夾
  • src/test文件夾
  • node_modules文件夾
  • oh_modules文件夾
  • build文件夾
  • .preview文件夾
  • hvigorfile.ts文件
  • hvigorfile.js文件

配置代碼檢查規則

在工程根目錄下創建code-linter.json5配置文件，可對于代碼檢查的范圍及對應生效的檢查規則進行配置，其中files和ignore配置項共同確定了代碼檢查范圍，ruleSet和rules配置項共同確定了生效的規則范圍。具體配置項功能如下：

files：配置待檢查的文件名單，如未指定目錄，將檢查當前被選中的文件或文件夾中所有的.ets文件。

ignore：配置無需檢查的文件目錄，其指定的目錄或文件需使用相對路徑格式，相對于code-linter.json5所在工程根目錄，例如：build/**/*。

ruleSet：配置檢查使用的規則集，規則集支持一次導入多條規則。規則詳情請參見Code Linter代碼檢查規則。目前支持的規則集包括：

• 通用規則@typescript-eslint
• 一次開發多端部署規則@cross-device-app-dev
• ArkTS代碼風格規則@hw-stylistic
• 安全規則@security
• 性能規則@performance
• 預覽規則@previewer

  說明

  • 以上規則集均分為all和recommended兩種規則集。all規則集是規則全集，包含所有規則；recommended規則集是推薦使用的規則集合。all規則集包含recommended規則集。
  • 不在工程根目錄新建code-linter.json5文件的情況下，Code Linter默認會檢查@performance/recommended和@typescript-eslint/recommended規則集包含的規則。

rules：可以基于ruleSet配置的規則集，新增額外規則項，或修改ruleSet中規則默認配置，例如：將規則集中某條規則告警級別由warn改為error。

overrides：針對工程根目錄下部分特定目錄或文件，可配置定制化檢查的規則。

{
"files": //用于表示配置適用的文件范圍的 glob 模式數組。在沒有指定的情況下，應用默認配置
[
"**/*.js", //字符串類型
"**/*.ts"
],
"ignore": //一個表示配置對象不應適用的文件的 glob 模式數組。如果沒有指定，配置對象將適用于所有由 files 匹配的文件
[
"build/**/*", //字符串類型
"node_modules/**/*"
],
"ruleSet": //設置檢查待應用的規則集
[
"plugin:@typescript-eslint/recommended" //快捷批量引入的規則集, 枚舉類型：plugin:@typescript-eslint/all, plugin:@typescript-eslint/recommended, plugin:@cross-device-app-dev/all, plugin:@cross-device-app-dev/recommended等
],
"rules": //可以對ruleSet配置的規則集中特定的某些規則進行修改、去使能, 或者新增規則集以外的規則；ruleSet和rules共同確定了代碼檢查所應用的規則
{
"@typescript-eslint/no-explicit-any": // ruleId后面跟數組時, 第一個元素為告警級別, 后面的對象元素為規則特定開關配置
[
"error", //告警級別: 枚舉類型, 支持配置為suggestion, error, warn, off
{
"ignoreRestArgs": true //規則特定的開關配置, 為可選項, 不同規則其下層的配置項不同
}
],
"@typescript-eslint/explicit-function-return-type": 2, // ruleId后面跟單獨一個數字時, 表示僅設置告警級別, 枚舉值為: 3(suggestion), 2(error), 1(warn), 0(off)
"@typescript-eslint/no-unsafe-return": "warn" // ruleId后面跟單獨一個字符串時, 表示僅設置告警級別, 枚舉值為: suggestion, error, warn, off
},
"overrides": //針對特定的目錄或文件采用定制化的規則配置
[
{
"files": //指定需要定制化配置規則的文件或目錄
[
"entry/**/*.ts" //字符串類型
],
"excluded":
[
"entry/**/*.test.js" //指定需要排除的目錄或文件, 被排除的目錄或文件不會按照定制化的規則配置被檢查; 字符串類型
],
"rules": //支持對overrides外公共配置的規則進行修改、去使能, 或者新增公共配置以外的規則; 該配置將覆蓋公共配置
{
"@typescript-eslint/explicit-function-return-type": // ruleId: 枚舉類型
[
"warn", //告警級別: 枚舉類型, 支持配置為error, warn, off; 覆蓋公共配置, explicit-function-return-type告警級別為warn
{
allowExpressions: true //規則特定的開關配置, 為可選項, 不同規則其下層的配置項不同
}
],
"@typescript-eslint/no-unsafe-return": "off" // 覆蓋公共配置, 不檢查no-unsafe-return規則
}
}
]
}

查看/處理代碼檢查結果

掃描完成后，在底部工具面板查看檢查結果。勾選Defects中不同告警等級，可分別查看對應告警級別的信息。雙擊某條告警結果，可以跳轉到對應代碼缺陷位置；選中告警結果時，可以在右側Defect Description窗口查看告警對應的規則詳細說明，其中包含正向和反向示例，并根據其中的建議修改代碼；搜索規則時，可設定是否全詞匹配和大小寫敏感。

單擊

圖標，查看可修復的代碼規則，點擊

代碼修復圖標，可以一鍵式批量修復告警，并刷新檢查結果。

屏蔽告警信息：

• 在某些特殊場景下，若掃描結果中出現誤報，點擊單條告警結果后的

  

  Ignore圖標，可以忽略對告警所在行的code linter檢查；或勾選文件名稱或多條待屏蔽的告警，點擊左側工具面板Ingore圖標批量執行操作；
• 在文件頂部添加注釋/* eslint-disable */可以屏蔽整個文件執行code linter檢查，在eslint-disable 后加入一個或多個以逗號分隔的規則Id，可以屏蔽具體檢查規則；
• 在需要忽略檢查的代碼塊前后分別添加/* eslint-disable */和/* eslint-enable */添加注釋信息，再執行Code Linter，將不再顯示該代碼塊掃描結果；在待屏蔽的代碼行前一行添加/* eslint-disable-next-line */，也可屏蔽對該代碼行的codelinter檢查。

如需恢復忽略的報錯信息，可以直接刪除該行上方的注釋，重新執行Code Linter檢查。

導出檢查結果：點擊工具面板左側

導出按鈕，即可導出檢查結果到excel文件，包含告警所在行，告警明細，告警級別等信息。

實踐說明

以@typescript-eslint/no-restricted-syntax（使用某類語法時，codelinter告警）、@typescript-eslint/naming-convention（命名風格校驗）和@hw-stylistic/file-naming-convention（檢查代碼文件的命名風格）三個規則為例，介紹codelinter配置文件的使用方法。

示例1：調用類Foo下bar方法時，Code Linter告警

在配置文件中定義規則

在ArkTS工程中，pages/Index.ets文件下增加以下用例：

class Foo {
static bar() {}
}Foo.bar();

在工程根目錄下新建code-linter.json5文件（文件名不可修改），新增以下配置：

{
"rules": {
"@typescript-eslint/no-restricted-syntax": [
// 告警級別: 枚舉類型, 支持配置為error, warn, off
"error",
{
// selector屬性必選，配置要禁用的語法
// 可通過特定DSL篩選待限制的語句，CallExpression表示方法調用表達式，后面的中括號里面是篩選條件（根據語法樹Node節點來確定）
// 其中callee.object.name根據指定的名稱篩選調用方法的對象（class，namespace或module），以上示例中為"Foo"
// callee.property.name則根據指定的名稱篩選被調用的方法，以上示例中為"bar"
"selector": "CallExpression[callee.object.name='Foo'][callee.property.name='bar']",
// message屬性可選，配置要展示的報錯信息
"message": "Foo.bar() is not allowed"
}
]
},
}

說明

如需在code-linter.json5文件中配置其他字段，請參見配置代碼檢查規則。

執行代碼檢查

對pages/Index.ets文件執行代碼檢查，檢查結果如下：

示例2：對類名Foo的命名風格校驗

在配置文件中定義規則

在ArkTS工程中，pages/Index.ets文件下增加以下用例：

class foo { //此處構造一個命名風格錯誤的示例，foo為錯誤使用類名，正確類名應為Foo
bar() {}
}

在工程根目錄下新建code-linter.json5文件，新增以下配置：

{
"rules": {
"@typescript-eslint/naming-convention": [
"error",
{
// selector屬性必選，配置要檢查的語法，這里配置的class表示檢查自定義組件名
"selector": "class",
// format屬性必選，配置期望的命名風格，支持枚舉值，這里配置的PascalCase表示大駝峰風格
"format": ["PascalCase"],
// custom屬性可選，配置用戶自定義的命名風格
"custom": {
// regex屬性必選，配置具體的正則
"regex": "^[a-zA-Z]+$",
// match屬性必選，配置為true表示正則未命中時報錯；配置為false表示正則命中時報錯
"match": true
}
}
]
},
}

表1?字段說明

字段名稱	參數說明	是否必選	類型	支持配置的參數
selector	配置要檢查的語法	是	字符串、字符串數組	variable：變量 function：函數 parameter：參數 parameterProperty：參數屬性 accessor：get/set方法 enumMember：枚舉成員 classMethod：類方法 structMethod：自定義組件中的方法 objectLiteralMethod：對象方法 typeMethod：接口方法 classProperty：類屬性 structProperty：自定義組件中的屬性 objectLiteralProperty：對象屬性 typeProperty：接口屬性 class：類 struct：自定義組件 interface：接口 typeAlias：類型別名 enum：枚舉 typeParameter：泛型參數 default：包含以上所有的類型 variableLike：包含variable，function，parameter memberLike：包含classProperty，structProperty，objectLiteralProperty，typeProperty，parameterProperty ，enumMember，classMethod，objectLiteralMethod，typeMethod，accessor typeLike：包含class，struct，interface，typeAlias，enum，typeParameter method：包含classMethod，structMethod，objectLiteralMethod，typeMethod property：包含classProperty，objectLiteralProperty，typeProperty
format	配置期望的命名風格	是	字符串數組	camelCase：小駝峰命名風格，比如getName，getID（支持連續大寫字母），不支持下劃線 strictCamelCase：嚴格小駝峰命名風格，除了不支持連續大寫字母（getID），其他的和camelCase相同 PascalCase：大駝峰命名風格，比如Foo，CC，除了要求第一個字母大寫，其他的和camelCase相同 StrictPascalCase：大駝峰命名風格，除了不支持連續大寫字母（CC），其他的和PascalCase相同 snake_case：小寫字母+下劃線+小寫字母的命名風格，比如a_a，不支持_a，a_a_ UPPER_CASE：大寫字母+下劃線+大寫字母的命名風格，比如A_A，不支持_A，A_A_
custom	配置用戶自定義的命名風格	否	對象	regex：屬性必選，配置具體的正則 match：屬性必選，配置為true表示正則未命中時報錯，配置為false表示正則命中時報錯
leadingUnderscore/trailingUnderscore	配置是否允許以下劃線開頭/以下劃線結尾的命名風格	否	字符串	allow：允許以一個下劃線開頭/結尾的命名風格，比如_name allowDouble：允許以兩個下劃線開頭/結尾的命名風格，比如__name allowSingleOrDouble：允許以一個或者兩個下劃線開頭/結尾的命名風格（allow+allowDouble） forbid：禁止以下劃線開頭/結尾的命名風格，比如_name，__name require：必須是以下劃線開頭/結尾的命名風格，比如_name，__name requireDouble：必須是以兩個下劃線開頭/結尾的命名風格，比如__name
prefix/suffix	配置固定前綴/后綴的命名風格。如果前綴/后綴未匹配則報錯	否	字符串數組	用戶自定義前綴/后綴
filter	過濾特定的命名風格，檢查或者不檢查正則命中的命名	否	對象	配置格式與custom相似 match：設置為true表示只檢查正則命中的名字，設置為false表示不檢查正則命中的名字 regex：設置過濾的正則 說明 支持直接配置一個字符串，這個字符串配置的是regex，此時match相當于配置的是true。
modifiers	匹配修飾符，只有包含特定修飾符的命名才會檢查	否	字符串數組	abstract：匹配abstract關鍵字 override：匹配override關鍵字 private：匹配private關鍵字 protected：匹配protected關鍵字 static：匹配static關鍵字 async：匹配async關鍵字 const：匹配const關鍵字 destructured：匹配解構語法 exported：匹配export關鍵字 global：匹配全局聲明 #private：匹配私有符號# public：匹配public級別的訪問修飾符 requiresQuotes：匹配字符串類型的命名，并且 字符串中包含特殊字符 unused：匹配未使用的聲明
types	匹配類型，只有特定類型的名字才會檢查	否	字符串數組	array：數組類型 boolean：布爾類型 function：函數類型 number：數字類型 string：字符串類型

說明

以上配置的參數有校驗優先級：filter > types > modifiers > validate leading underscore > validate trailing underscore > validate prefix > validate suffix > validate custom > validate format。

執行代碼檢查

對pages/Index.ets文件執行代碼檢查，檢查結果如下：

示例3：檢查代碼文件的命名風格

在配置文件中定義規則

在ArkTS工程中，pages目錄下新建test.ets文件；

在工程根目錄下新建code-linter.json5文件，新增以下配置：

{
"rules": {
"@hw-stylistic/file-naming-convention": [
// 告警級別：枚舉類型，支持配置為error，warn，off
"error",
{
// selector屬性可選，支持配置為code或者resources
// code表示檢查代碼文件的命名風格
// resources表示檢查資源文件的命名風格
"selector": "code"
}
]
},
}

說明

如果selector屬性不配置，默認檢查代碼文件和資源文件的命名風格。

執行代碼檢查

對pages/test.ets文件執行代碼檢查，檢查結果如下：