SonarQube系列-通過配置掃描分析範圍，聚焦關鍵問題

在許多情況下，你可能不希望分析項目中每個源文件的各個方面。例如，項目可能包含生成的代碼、庫中的源代碼或有意複製的代碼。在這種情況下，跳過這些文件分析的部分或全部方面是有意義的，從而消除干擾並將焦點縮小到真正重要的問題上。

如果SonarQube的結果不相關，那麼沒有人會想要使用它。這就是爲什麼精確配置每個項目要分析的內容是非常重要的一步。
爲了幫助縮小焦點，Sonar Qube提供了幾個選項來精確配置將要分析的內容和方式。

• 完全忽略一些文件或目錄
• 從問題中排除文件或目錄，但分析所有其它方面
• 從重複性中排除文件或目錄，但分析所有其它方面
• 從覆蓋率中排除文件或目錄，但分析其它所有方面

你可以在全局或項目級別配置它們。
定義分析範圍的大多數屬性都可以在Sonar Qube UI中定義。其他參數必須在scanner調用中或在適當的配置文件中明確設置，

設置初始分析範圍

分析的初始範圍由以下參數控制：

• sonar.sources定義了項目中非測試代碼的初始分析範圍。
• sonar.tests定義了項目中測試代碼的初始分析範圍。

這些參數定義了分析範圍調整的起點：

• 根本不會分析這些參數定義的範圍之外的文件。
• 除非通過進一步調整（排除、包含等）排除，否則將分析這些參數定義範圍內的文件。

此外，這些參數包括：

• 僅在項目級別設置。這些參數沒有全局的、服務器級別的等效參數。
• 由Sonar Scanner自動設置，在配置文件中顯式設置，或在調用Scanner命令行上設置。這些參數沒有UI設置。sonar-project.properties
• 顯式設置，並且兩者都接受逗號分隔的路徑列表。不支持使用通配符的模式匹配。

測試/非測試代碼的作用域是分開的

測試代碼和非測試代碼是有區別的，因爲

• 對這兩個類別應用了不同的分析規則。
• 這兩個類別具有不同的指標
• 測試代碼不計入許可證定義的代碼行數限制。
• 測試代碼不計入覆蓋率（您不必測試測試代碼）

Maven、Gradle和.NET的自動設置

如果使用 SonarScanner for Maven、SonarScanner for Gradle 或 SonarScanner for .NET 分析代碼，則會根據項目配置中的信息自動確定參數，不必顯式設置參數。
如果您確實顯式設置了參數（例如，在 Maven 的情況下，這將覆蓋自動pom.xml 中的 sonar.sources， sonar.tests

其他場景的默認設置

如果您沒有使用Maven、Gradle或。NET

• 默認情況下，設置爲當前工作目錄（路徑）sonar.sources
• 默認情況下，未設置 sonar.tests

顯式設置

如果默認值不合適（例如_，如果您有測試_代碼），則必須在掃描程序調用或相應的配置文件中顯式設置參數（請參閱分析參數）。
顯式設置時，兩者兼而有之，並採用逗號分隔的目錄或文件列表。sonar.sourcessonar.tests

• 列表中的條目是簡單路徑。不允許使用通配符（、 和 ）***?
• 列表中的目錄意味着包含所有可分析的文件和其下方的目錄遞歸。列表中的單個文件表示包含該文件。
• 路徑是相對於項目基目錄進行解釋的。基目錄由您正在使用的掃描程序定義。在大多數情況下，這是項目的根目錄。如果您使用的是SonarScanner CLI，則基目錄將是調用該工具的當前目錄（儘管可以使用參數將其覆蓋）。sonar.projectBaseDir

示例

假設您的存儲庫看起來像這樣，您的源代碼和測試代碼在頂層明確分離：

在這種情況下，您可以像這樣設置：sonar.sources 和 sonar.tests

如果在文件中配置範圍，它將如下所示：sonar-project.properties, 無需進一步微調

# Define separate root directories for sources and tests
sonar.sources = src/
sonar.tests = test/

通配符模式

SonarQube中可以使用以下通配符， 下面討論的大多數參數都使用通配符模式

符號	匹配
*	匹配一個或多個字符 (不包括目錄分隔符 )
**	匹配一個或多個目錄
?	匹配一個字符 (不包括目錄分隔符 )

:::info

• The pattern **/*.css
  • matches anyDirectory/anyFile.css
  • doesn't match org/sonar.api/MyBean.java
• The pattern **/*Bean.java
  • matches org/sonar.api/MyBean.java
  • doesn't match org/sonar/util/MyDTO.java
• The pattern **/*Bean?.java
  • matches org/sonar/util/MyOtherBean1.java
  • doesn't match org/sonar/util/MyOtherBean.java
• The pattern org/sonar/*
  • matches org/sonar/MyClass.java
  • doesn't match org/sonar/util/MyClassUtil.java
• The pattern org/sonar/**/*
  • matches org/sonar/MyClass.java
  • doesn't match org/radar/MyClass.java
    :::

通過UI設置分析過濾範圍

除非另有說明，否則以下所有參數均可在全局和項目級別設置。設置的 UI 位置位於：（新舊版本位置會有細微差異）

• 管理>配置>常規設置（用於全局設置）
• 項目設置>常規設置（適用於項目級設置）

在全局級別進行的任何設置都將應用於所有項目，除非在項目級別被覆蓋（唯一的例外是上面討論的全局排除參數）

特定文件的排除和包含

如果項目的目錄結構沒有在頂層將源代碼與測試代碼完全分開，則可能需要使用排除項和包含項來調整範圍。
:::warning
包含項和排除項不應是初始分析配置的一部分。建議僅設置它們以解決問題。例如，當您注意到某個分析選取了您不想分析的文件時。
:::

全局級別設置

Administration > Configuration > General Settings > Analysis Scope > A. File Exclusions

項目級別設置

Project Settings > General Settings > Analysis Scope > A. File Exclusions

針對項目級配置，要進行如下參數配置：

• 在配置文件中設置它們<YOUR_PROJECT>/sonar-project.properties

<properties>
  <!-- 找到pom文件的properties標籤，在裏面新增如下配置 -->
  <!-- Sonar掃描需要排除的包、類 多個用英文 , 隔開 -->
  <sonar.exclusions>
    <!-- 指定需要排除的包 -->
    src/main/java/com/zhibo/**/model/**,
    src/main/java/com/zhibo/**/vo/**,
    <!-- 排除以Enum結尾的類 -->
    src/main/java/com/zhibo/**/*Enum.*
  </sonar.exclusions>
</properties>

• 調用掃描程序時，在命令行上設置它們。
• 對於 Maven、Gradle 或 .NET 項目，請在相應的特定於框架的配置文件中設置它們。

# 排除所有Bean結尾的類
# 匹配org/sonar.api/MyBean.java, org/sonar/util/MyOtherBean.java, org/sonar/util/MyDTO.java等
sonar.exclusions=**/*Bean.java,**/*DTO.java

# 排除src/main/java/org/sonar目錄下所有文件
# 但不包括其子目錄下的文件
sonar.exclusions=src/main/java/org/sonar/*

# 排除bank目錄及其子目錄下的所有文件
sonar.exclusions=bank/**/*

# 排除bank目錄及其子目錄下的所有.cs文件
sonar.exclusions=bank/**/*.cs

注意：通配符模式是相對於項目基目錄（**sonar.sources sonar.tests**）進行解釋的。
排除項 和 包含項 建立在上述範圍基礎上，僅僅充當篩選器得作用。它們只會減少可分析集中的文件數量，從不添加到分析集合範圍中。

示例

假設您的代碼庫看起來像這樣，您的測試代碼與源代碼混合在一起：

你可以這樣定義你的，包括整個目錄：sonar.sources = src/

然後將“源文件排除項（鍵）”設置爲sonar.exclusions``=src/**/test/**/*
結果是要掃描的源文件集是減去每個子目錄下的所有內容：src test

要定義測試文件，首先設置爲整個目錄：sonar.tests= src/

然後將“測試文件包含（鍵）”設置爲sonar.test.inclusions =src/**/test/**/*
結果是要掃描的源文件集是下的所有內容_減去所有不是_子目錄的內容：src test

如果在文件中配置範圍，它將如下所示：sonar-project.properties

# Define the same root directory for sources and tests
sonar.sources = src/
sonar.tests = src/

# Include test subdirectories in test scope
sonar.test.inclusions = src/**/test/**/*

# Exclude test subdirectories from source scope
sonar.exclusions = src/**/test/**/*

代碼覆蓋率的排除

配置不應該檢測代碼覆蓋率的文件。參數的值是相對於當前工作目錄的路徑匹配模式的逗號分隔列表
Administration > General Settings > Analysis Scope > Code Coverage > Coverage Exclusions。

按文件類型設置範圍

大多數語言都提供了一種將分析範圍限制爲與一組擴展名匹配的文件的方法。您可以爲每種語言指定一個或多個後綴（文件擴展名）。
例如，對於 C 語言，.c 和 .h是默認設置
通過參數key設置時，可使用相應參數sonar.<LANGUAGE>.file.suffixes

重複的排除

Administration > General Settings > Analysis Scope > Duplications
用於從重複檢測機制中排除某些源文件的模式。該值是相對於當前工作目錄的路徑匹配模式的逗號分隔列表。

忽略問題

可使用SonarQube忽略某些組件和某些編碼規則的問題。Administration > General Settings > Analysis Scope > Issues。
請注意，以下屬性只能通過Web界面設置，因爲它們是多值的。

• Ignore Issues on Files
• Ignore Issues in Blocks
• Ignore Issues on Multiple Criteria
• Restrict Scope of Coding Rules

根據內容忽略文件中的問題

Analysis Scope > D. Issue Exclusions > Ignore Issues on Files
可以忽略包含與給定正則表達式匹配的代碼塊的文件。這些文件中的所有問題以及安全熱點都將被忽略。在此設置中，可以輸入一個或多個正則表達式模式。任何至少包含一種指定模式的文件都將被忽略。
例如，假設您在 Java 項目中生成了希望排除的類文件。這些文件看起來像這樣：

@Generated("com.example.generated")
public class GeneratedClass extends AnotherClass {
    // Some generated code
}

要排除所有此類文件，您可以將此參數設置爲：

@Generated\(".*"\)
#如果在文件中找到此正則表達式，則會忽略整個文件

請注意，由於該值是正則表達式，因此您需要轉義(和)括號字符並使用表達式 .* 匹配這些括號之間的字符串。
然而，該參數的關鍵是 sonar.issue.ignore.allfile，因爲它是一個多值屬性，所以我們建議僅通過 UI 設置它。

忽略文件中的塊

Analysis Scope > D. Issue Exclusions > Ignore Issues on Blocks
您可以忽略文件中的特定代碼塊，同時繼續掃描文件的其餘部分。要忽略的塊在文件內由開始和結束字符串分隔。您可以通過正則表達式指定這些開始和結束字符串。這些塊內的所有問題以及安全熱點都將被忽略。您可以輸入一對或多對正則表達式模式。任何文件中位於起始模式與其相應的結束模式之間的任何代碼都將被忽略
注意：

• 如果找到第一個正則表達式但未找到第二個正則表達式，則文件末尾被視爲塊的末尾。
• 正則表達式不匹配多行。

例如，假設想忽略方法 doSomethingElse 中使用塊分隔符的代碼，如下所示：

public class MyClass {
    public MyClass() {
        ...
    }

    public void doSomething() {
        ...
    }

    // BEGIN-NOSCAN
    public void doSomethingElse()
    {
        ...
    }
    // END-NOSCAN
}

您可以指定以下正則表達式：
塊的開始： \s*//\s*START-NOSCAN
塊結束：** **\s*//\s*END-NOSCAN
這些正則表達式可確保無論行註釋字符 ( ) 周圍的空格數量如何，都可以識別起始塊分隔符和結束塊分隔符//。
該參數的關鍵是 sonar.issue.ignore.block. 但是，由於它是一個多值屬性，因此我們建議僅通過 UI 設置它。

從特定文件中排除特定規則

您可以通過組合由規則鍵模式** **和_文件路徑模式_組成的一對或多對字符串來防止將特定規則應用於特定文件。
然而，該參數的關鍵是 sonar.issue.ignore.multicriteria,，因爲它是一個多值屬性，所以我們建議僅通過 UI 設置。

規則鍵模式

規則鍵模式由規則存儲庫名稱、後跟冒號、規則鍵或規則名稱通配模式組成。
例如：

• java:S195與java規則庫中的規則 rule S1195完全匹配。
• java:Naming匹配java存儲庫中規則名稱中包含字符串Naming的所有規則。

您可以在規則定義中找到規則定義的完全限定規則 ID 和規則名稱。
例如，對於 此規則：

• 規則ID： css:S4655
• 規則名稱： "!important" should not be used on "keyframes"

文件路徑模式

文件路徑模式使用上述路徑匹配格式來指定一組目錄或文件。

示例

如下圖所示，這個配置將忽略所有文件的 針對規則 java:S2259 進行檢查

:::success

• 忽略所有文件中的所有問題：
  • 規則關鍵模式： *
  • 文件路徑模式： */
• 忽略文件中的所有問題 bank/ZTR00021.cbl：
  • 規則關鍵模式： *
  • 文件路徑模式： bank/ZTR00021.cbl
• 忽略直接位於 Java 包中 com.foo但不位於其子包中的文件中的所有問題：
  • 規則關鍵模式： *
  • 文件路徑模式： com/foo/*
• cpp:Union 忽略目錄 object 及其子目錄 中文件中所有違反編碼規則的問題 ：
  • 規則關鍵模式： cpp:Union
  • 文件路徑模式： object/**/*
    :::

將特定規則應用於特定文件

• Global level: Administration > Configuration > General Settings > Analysis Scope > D. Issue Exclusions > Restrict Scope of Coding Rules
• Project level: Project Settings > General Settings > Analysis Scope > D. Issue Exclusions > Restrict Scope of Coding Rules

設置這些參數的機制與上面的 sonar.issue.**ignore**.multicriteria相同：每個條目都包含一個規則鍵模式和一個文件路徑模式。
不同的是，在這種情況下，這意味着指定的規則將僅應用於指定的文件集。
該參數的關鍵是 sonar.issue.**enforce**.multicriteria. 但是，由於它是一個多值屬性，因此我們建議僅通過 UI 設置它。

示例

:::success

• 只檢查“Bean”對象上的“Magic Number”規則，而不檢查其他任何東西：
  • 規則鍵模式：checkstyle:com.puppycrawl.tools.checkstyle.checks.coding.MagicNumberCheck
  • 文件路徑模式：**/*Bean.java
• 僅檢查規則_Prevent GO TO statement from transferring control outside current module on COBOL programs_ in the directories：bank/creditcardbank/bankcard
  • 規則鍵模式 1：cobol:COBOL.GotoTransferControlOutsideCurrentModuleCheck
  • 文件路徑模式 1：bank/creditcard/**/*
  • 規則鍵模式 2：cobol:COBOL.GotoTransferControlOutsideCurrentModuleCheck
  • 文件路徑模式 2：bank/bankcard/**/*
    :::

總結

有以下幾種方式來縮小要分析源碼的範圍，如下：

1. 首先設置初始化分析範圍：設置_sonar.sources_參數指定源代碼目錄的範圍
2. 文件後綴：許多語言都提供了限制文件後綴名的的參數，’配置’–>’通用’–>’[語言]’，設置File suffixes屬性
3. 再從上述範圍內選擇指定文件，縮小關注的文件範圍
   • _sonar.exclusions/sonar.test.exclusions_ 設置分析除指定文件以外的所有文件
   • _sonar.inclusions/sonar.test.inclusions_ 設置僅僅分析指定的文件
4. 針對具體的問題，再通過排除重複，忽略錯誤，實現更細粒度的控制

如下圖所示，通過四種不同的方法可將分析範圍縮小到與開發團隊相關的源代碼。
:::warning

• 源目錄(Source Directories)
• 文件後綴(File Suffixes)
• 選擇文件(Choosing Files)
  • 源文件排除(Source File Exclusions)
  • 測試文件排除(Test File Exclusions)
  • 源文件包含(Source File Inclusions)
  • 測試文件包含(Test File Inclusions)
    :::