jscpd統計專案中的程式碼重複度使用詳解

2023-03-29 06:01:38

前言

當一個專案開發時間較長以後，總會存在一些重複的程式碼，這就給維護和擴充套件帶來障礙。

特別是我們的前端專案，多個專案中都存在一些較相似的功能，這部分之前不少採用複製貼上的方式處理。於是為了優化前端專案的程式碼，最近我們考慮使用程式碼重複度來作為衡量指標，對單個或多個專案進行重複程式碼的統計，並著手重構可優化的重複程式碼。

而為了統計專案中是否有程式碼重複，我們使用了 jscpd 工具庫，本文將詳細介紹該工具的使用方法。

jscpd是什麼

jscpd是一個開源的js工具庫，用於檢測專案的程式碼重複率，針對複製貼上的程式碼尤其有效，支援超過150種的原始碼檔案格式。

我們在前端專案中，無論是原生的javascript、css、html程式碼，還是使用typescript、less、vue、react等程式碼，都能較好的識別出專案中的重複程式碼。

當然，這裡的重複，更多的指程式碼完全重複，即程式碼行與程式碼字串，都相同。

如何使用它

下面，先看下如何使用它。

安裝

我們先以全域性方式，安裝該工具庫：

npm install jscpd -g

安裝成功後，系統就有一個全域性命令 jscpd，可以檢視版本號，當前最新版本是 3.5.3，如下所示：

$ jscpd -V
3.5.3

安裝成功後，我們就可以很方便的使用它。

範例

例如，我們需要統計一個檔案 app.js，只需要在檔案目錄執行以下命令：

jscpd ./app.js

執行成功後，在命令列介面會顯示結果，如下圖所示：

圖中的內容，我們下面一一做個說明說明：

Clone found (javascript)顯示找到的拷貝的重複程式碼塊，這裡是javascript檔案。
並且會顯示重複程式碼在檔案中具體的行數，便於查詢。
HTML report saved to reporthtml這句話的意思是，會在檔案目錄下輸出對應報告的html頁面，一般預設是 reporthtml 目錄下，用於在頁面中展示結果。
Format檔案格式，這裡是 javascript，還可以是 typescript、tsx 等。
Files analyzed已分析的檔案數量，統計專案中的程式碼檔案數。
Total lines所有檔案的總行數。
這裡只有一個檔案，總行數是105行。
Total tokens所有的token數量。
這裡一般以 識別符號/變數等、數位、字串、空格 或 符號 等等作為一個 token 來統計數量。
一行程式碼一般包含幾個到幾十個不等的token數量。
Clones found找到拷貝的重複塊數量。
Duplicated lines重複的程式碼行數，以及佔比。
在表格的 Total 行裡，重複程式碼的佔比就是程式碼行的重複度了，這裡是18.1%。
Duplicated tokens重複的token數量，以及佔比。
Found 0 clones找到了1個重複塊。
Detection time檢測耗時。

由此可知，./app.js 檢測1個檔案，發現了1個重複快，在總行數為105行的程式碼中，共有19行程式碼完全重複，重複度為 18.1%。

設定選項

以上範例是比較簡單的，直接檢測單個檔案，通過命令列檢測單個檔案，列印結果，並預設生成report報告的頁面。
如果是在當前主流的前端專案中，由於很多檔案是輔助工具如依賴包、構建、檔案等，並不是有效的程式碼，需要排除。這種情況下，我們一般使用組態檔的方式，通過選項設定規範 jscpd 的使用場景。

jscpd 的設定選項可以通過以下兩種方式建立：

在專案根目錄下建立組態檔 .jscpd.json，然後在該檔案中增加具體的設定選項；
也可以直接在 package.json 檔案中新增

如果專案根目錄下沒有 package.json 檔案，可以自行新增一個，然後在該件中個增加對應的設定。

無論是Vue還是React專案，使用大致都一樣，如下，在 package.json 中增加 jscpd 設定屬性：

"jscpd": {
  "threshold": 1,
  "reporters": [
    "html",
    "console"
  ],
  "ignore": [
    ".git",
    "node_modules",
    "public",
    ".husky"
  ],
  "format": ["javascript", "typescript"],
  "absolute": true
}

以上是一個常用的設定，具體說明：

threshold 表示重複度的閾值，超過這個值，就會列印錯誤報警。

如閾值設為 1，當重複度為18.1%時，會報錯：ERROR: jscpd found too many duplicates (18.1%) over threshold (1%)。
雖然報錯，但程式碼的檢測仍然會正常完成。

reporters 表示生成結果檢測報告的方式，一般有以下幾種：

console：控制檯列印
html：建立可存取的 html 頁面
json：輸出 json 格式的檔案報告
xml：輸出 xml 格式的檔案報告
csv：輸出 csv 格式的檔案報告
markdown：輸出 md 格式的檔案報告
consoleFull：控制檯完整列印重複程式碼塊
verbose：控制檯輸出 debug 資訊

ignore

檢測時會忽略的檔案目錄或檔案，用於過濾一些非業務程式碼，如依賴包、構建或靜態檔案等

format

需要進行重複度檢測的原始碼格式，目前支援150多種，我們常用的如 javascript、typescript、css 等

absolute

在檢測報告中使用絕對路徑

除此以外，還有很多設定屬性，我們這裡不在一一介紹。

輸出報告

上面介紹會輸出重複度檢測報告，我們在專案中設定好組態檔以後，執行以下命令：

jscpd ./src -o 'report'

專案中的業務程式碼，通常會選擇放在 ./src 目錄下，所以我們可以直接檢測該目錄。
-o 'report' 通過命令列引數，輸出檢測報告到專案根目錄下的 report 資料夾中——當然也可以自定義目錄，這時候就會生成對應的頁面檔案：

如上所示，本質上是一個本地網頁，而且是基於 VUE 框架建立的網頁，可以在瀏覽器存取檢視，介面長這樣：

從上圖可知，檢測了149個檔案，其中存在8塊拷貝複製的程式碼，程式碼行計算的重複度是 1.18%，非常直觀。

通過生成本地網頁直接展示所有的檢測報告，並且還能檢視到重複的程式碼在哪：

上圖可以看到，在兩個 tsx 元件檔案中，存在一段重複的程式碼，也標識除了這兩段程式碼在檔案中具體行數。

多個專案

上面介紹的是單個專案的重複度檢測，如果有多個專案，且存在程式碼的複製貼上現象，也可以通過jscpd工具進行檢測處理。
我們只需要在多個專案的上層目錄下新建一個 package.json 檔案，設定相應的設定選項，就能根據設定檢測這些專案間的重複程式碼。這裡需要注意的是，一般只需要檢測業務程式碼 src，在組態檔中 ignore 屬性的忽略目錄，需要帶上各專案的專案名稱。

"ignore": [
  "project1/.git",
  "project1/node_modules",
  "project2/.git",
  "project2/node_modules"
  // ...
]

這樣，就能快速檢測出多個專案中的重複程式碼，仍然可在命令列輸出基本資訊，以及對應的report頁面報告。

規避程式碼檢測

當我們使用jscpd執行專案的重複度檢測時，由於一些重複程式碼可能是必要的，不想檢測，可以使用程式碼註釋標識的方式，讓這部分程式碼不用檢測。
在程式碼的首尾位置新增相應註釋，jscpd:ignore-start 和 jscpd:ignore-end，包裹程式碼即可。

如在js程式碼中，可以這樣使用：

/* jscpd:ignore-start */
import { provide, computed, watch, onMounted, defineComponent } from 'vue'
import { useStore } from 'vuex'
/* jscpd:ignore-end */

在css及各種預處理中，也是與js中的用法一樣：

/* jscpd:ignore-start */
.content {
  height: 100vh;
  width: 100vw;
  display: flex;
  justify-content: center;
  align-items: center;
  overflow: hidden;
}
/* jscpd:ignore-end */

如下在html中的使用：

<!--
// jscpd:ignore-start
-->
<meta charset="utf-8">
<meta http-equiv="X-UA-Compatible" content="IE=edge">
<meta name="viewport" content="width=device-width,, user-scalable=no, initial-scale=1.0, maximum-scale=1.0, minimum-scale=1.0">
<!--
// jscpd:ignore-end
-->

通過以上註釋標識以後，這部分的程式碼就不會再被統計為重複程式碼了。