sonarqube用户指南

sonarqube用户指南

雷建锋

一、使用sonarqube的背景

         在传统的方法中，开发人员在发布新版本之前进行代码质量审核。这种方法可能在短期内有效，特别是在强有力的管理支持下，但是它在中长期内始终失败，因为:

l  在这个过程中，代码评审来得太晚了，没有任何干系人热衷于解决问题；每个人都希望新版本能够发布；

l  开发人员通常会倾向于拒绝一个不知道项目背景的外部团队提出的建议；

l  这种方式使得代码质量缺乏ownership。谁是质量的owner？没有人。

l  在部署到生产环境之前，会对整个应用程序进行评审，显然不可能将相同的标准应用于所有应用程序。每个项目都将对质量标准进行协商，这将降低代码质量审核的可信度。

         对管理代码质量来说，修复漏洞意味着将重点放在“新”代码上，即自上次发布以来添加或更改的代码。这将使事情变得容易：

l  质量阀可以每天运行，能通过它就说明代码质量是合格的，在发布的时候没有任何惊喜或意外；

l  对于开发人员来说，不太愿意撤回到一天或几天前引入问题的代码状态，然后进行修复。相反，他们通常很乐意在代码还新鲜的时候修复这些问题；

l  代码质量问题有明确的ownership;

l  Go/no-go的标准在不同的应用程序之间是一致的，并且在团队之间是共享的。实际上，新代码是新代码，不管它是在哪个应用程序中完成的；

l  代码质量审核的成本是微不足道的，因为它是开发过程的一部分；

l  值得注意的是，修改次数最多的代码具有最高的可维护性，而未被更改的代码的可维护性最低，这很有意义。由于软件的性质，以及我们不断地对其进行更改，技术债自然会不断减少。

Sonarqube提供了两种主要工具来帮助我们查找漏洞：

l 泄漏期间度量标准显示当前代码与其历史上选择的一个特定点之间的度量差异，通常是以前的版本 previous_version；

l  新代码主要是基于SCM“指责”数据(从泄漏期间的第一次分析开始)检测的，需要时使用后备机制，质量阀允许您设置用于度量代码的布尔阈值。请将它们与差异度量一起使用，以确保代码质量随着时间的推移朝着正确的方向移动

二、质量阀

        质量阀是执行组织质量方针的最佳途径。这是为了回答一个问题：我今天能不能把我的项目交付生产？为了回答这个问题，您定义了一组布尔度量，这些度量是基于度量项目的度量阈值的。例如：没有新的阻断问题、新代码的代码覆盖率大于80%，等等。

        理想情况下，所有项目都将按照相同的质量标准进行验证，但这并不总是适用的。例如，您可能会发现：

l  技术实现因应用程序的不同而不同(对于Web或java应用程序，您可能不需要在新代码上使用相同的代码覆盖率)。

l  您希望确保对某些应用程序(例如内部框架)提出更强的要求。等等。

        因此，soanrqub允许你可以定义想要的任意数量的质量阀。

        默认的质量阀包括三个指标：可靠性、安全性和可维护性等级。可以自定义自己项目的质量阀，使得更适用于自己的项目。

2.      严重

         要么是影响生产应用行为的低概率的bug，要么是安全缺陷的问题，比如空catch块、SQL注入等，代码必须立即审核。

3.      主要

质量缺陷会严重影响开发人员的生产力，比如未覆盖的代码块、重复的块、未使用的参数等等

4.      次要

质量缺陷可能轻微影响开发人员的生产力：行不应该太长，“开关”语句应该至少有3种情况等等

5.      提示

既不是一个bug，也不是一个质量缺陷，只是一个提示信息。

         理想情况下，团队不会引入任何新的问题(任何新的技术债务)。sonarlin插件可以帮助开发人员，因为他们提供了执行本地分析的能力，以便在将代码再推回scm之前检查代码。但在现实生活中，难免会引入新的问题。

         SONARQUE的问题工作流可以帮助您管理您的问题。对一个问题，有七个不同的事情你可以做（除了在代码中修复它）：注释，分配，确认，改变严重性，解决，不改正，假阳性。

1.      Confirm(确认)---通过确认一个问题，你基本上是在说“是的，这是个问题。”这样做可以将问题从“open”状态移到“confirm”；

2.      False Positive---从上下文的角度看问题，你会意识到，不管出于什么原因，这个问题实际上不是一个问题。所以你把它标记为假阳性，然后继续前进。需要管理员权限来处理。

3.      Won't Fix---从上下文的角度看问题，你会意识到，虽然这是一个有效的问题，但它并不是一个真正需要解决的问题。换句话说，它代表了已被接受的技术债。所以你标记它不会修复和然后继续前进。需要管理员权限来处理。

4.      Change Severity ---这是一个问题，但它并不像规则默认的严重程度所显示的那样严重。或者可能实际上更糟糕。不管怎样，你调整问题的严重性，使其与你认为应该得到的一致。需要管理项目的问题许可。

5.      Resolve --- 如果你认为你已经修复了一个问题，你可以把问题状态设置为已解决。如果你是对的，下一步把它设置为关闭状态。如果你错了，它的状态会被设置为reopen。

五、代码规则

         在Sonarqube平台上，分析器提供在源代码上执行的规则来生成问题。这些问题被用来计算修复成本和技术债务。规则有三种基本类型：可靠性和可维护性规则，以及安全规则。“代码规则”页面是可所有现有规则或根据提供的模板创建新规则的入口点。

         单击顶部的“代码规则”菜单项进入。默认情况下，您将看到所有可用的规则，可以根据左侧窗格中的搜索条件缩小选择范围：

1.       语言：规则适用的语言

2.       类型：bug、漏洞或坏味道

3.       TAG：可以在规则中添加标记，以便对它们进行分类，并帮助更容易地发现它们。

4.       资源库（Repository）：为Sonarqube提供规则的引擎。

5.       默认严重性：规则的原始严重性-这是由促成此规则的插件定义的。

6.       状态：规则可以有3种不同的状态：1）准备2）废弃3）Beta

7.       有效起始日期：第一次在sonarqube实例中添加规则的日期。这对于列出自插件上次升级以来的所有新规则非常有用。

8.       模板：显示允许创建自定义规则的规则模板

9.       质量配置：包含或排除在特定配置文件中

六、Code Viewer

         代码查看器是sonarqube的核心：它显示文件的源代码(包括源文件和测试文件)，以及它的高级统计数据：

1.       行

2.       问题：由在质量配置文件上激活的规则生成

3.       测试覆盖率：按单元或集成测试

4.       重复：在同一文件或其他文件中

5.       SCM信息：比如谁最后一次提交了一个特定的行，以及何时提交的

        

         代码查看器的主要目的是显示源代码及其可能出现的任何问题。由于这个原因，问题、重复（duplication）总是可见的，但是如果您不从“问题”页面到代码查看器，则可能会折叠问题，并且所有新代码上都会出现黄色高亮显示。

浅黄色背景是指：泄漏期间的新代码；

暗黄色背景的意思是：在未被测试覆盖的泄漏期间出现新代码

七、度量定义

(一)   复杂度

复杂度：它是根据通过代码的路径数计算的复杂度。每当函数的控制流分裂时，复杂度计数器就会增加一个。每个函数的最小复杂度为1。由于关键字和功能的存在，这种计算因语言的不同而略有变化。详细见：

(二)   重复

1.       重复块：

l  对java：指至少有10个连续和重复的语句，无论令牌和行；

l  COBOL:   30行

l  ABAP:20行

l  其他语言：10行

在检测重复时忽略缩进和字符串文字的差异。

2.       重复文件：涉及重复的文件数量

3.       重复行：涉及重复的行数

4.       重复行(%)：重复密度=重复行/总行数 * 100

(三)   问题

1.       新问题：新问题的数量

2.       新XX问题：严重程度为XX的新问题，XX指阻断、严重、主要、次要或信息中的一个

3.       问题：所有问题的个数汇总

4.       XX问题：严重程度为XX的问题的总数

5.       假阳性问题(False positive issues)：假阳性的问题数量

6.       打开的问题：状态为打开的问题的数量

7.       确认的问题：状态为已确认的问题的数量

8.       重新打开的问题：状态为重新打开的问题的数量

(四)   严重性

1.       阻碍：操作/安全风险：此问题可能会使整个应用程序在生产中不稳定。例如：调用垃圾收集器，而不是关闭套接字等等。

2.       严重：操作/安全风险：此问题可能导致生产中的意外行为，而不会影响整个应用程序的完整性。例如：nullpointerException、捕获严重的异常、缺乏单元测试等

3.       主要：这个问题可能会对生产力(productivity)产生重大影响。例如：太复杂的方法、包循环等等。

4.       次要：这个问题可能会对生产力产生潜在和次要的影响。例如：命名约定，终结器（Finalizer）只会调用超类终结器，等等。

5.       提示：未知或尚未明确定义的安全风险或对生产力的有影响影响的问题。

(五)   可维护性

1.       代码气味（Code Smells）：代码气味的数量。

2.       新的代码气味：新代码气味的数量

3.       可维护性等级（以前的sqale评级）：与技术债务价值相关的项目评级。默认的可维护性评级是：A=0-0.05, B=0.06-0.1, C=0.11-0.20, D=0.21-0.5, E=0.51-1

4.       技术债：解决所有可维护性问题的工作，该度量值以分钟为单位存储在数据库中，假设以天为单位显示值时，一天工作时间为8小时。

5.       新代码的技术债务：新代码的技术债务

6.       技术债务比率：软件开发成本与修复成本之比。技术债务比率=补救（Remediation）成本/开发成本；也即技术债务比率=Remediation cost / (开发1行代码的成本 * 代码行数)；开发一行代码的成本值为0.06天。

7.       新代码的技术债务比率：在泄漏期间更改的代码开发成本与其相关的问题的成本之间的比率

(六)   质量阀

1.       质量阀状态：与您的项目相关联的质量阀的状态。可能的值是：错误（ERROR）、警告(WARN)、确定(OK)。

2.       质量阀细节：关于质量阀的所有情况，你知道哪种情况是失败的，哪种情况不是。

(七)   可靠性

1.       缺陷：缺陷的数量

2.       新缺陷：新缺陷的数量

3.       可靠性等级：A=0个缺陷；B=至少1个次要缺陷；C=至少1个主要缺陷;D=至少1个严重缺陷；E=至少1个阻碍缺陷

4.       可靠性修复努力：解决所有错误问题的努力，该度量值以分钟为单位存储在db中。假设值以天为单位，为8小时一天。

5.       新代码的可靠性修复工作：与在泄漏期间更改代码的可靠性补救工作相同。

(八)   安全性

1.       漏洞（vulnerabilities）：漏洞的数量

2.       新漏洞：新漏洞的数量

3.       安全等级：A=0个漏洞；B=至少1个次要缺陷；C=至少1个主要漏洞;D=至少1个严重漏洞；E=至少1个阻碍漏洞  

4.       安全修复努力：解决所有漏洞问题的努力，该度量值以分钟为单位存储在db中。假设以天为单位显示值时，一天工作时间为8小时。

5.       新代码的安全修复努力：与在泄漏期间更改的代码所做的安全补救工作相同。

(九)   大小

1.       类：类的数量

2.       注释行：包含注释或注释代码的行数；非重要注释行(空注释行、只包含特殊字符的注释行等)不会增加注释行的数量。

3.       注释密度（%）：注释密度=注释行数/（代码行数+注释行数）*100

4.       代码行：包含至少一个字符的物理行数，该字符既不是空白，也不是制表，也不是注释的一部分。

(十)   测试

1.       条件覆盖：在每一行包含布尔表达式的代码中，条件覆盖只回答以下问题：每个布尔表达式是否都被计算为true和false？这是在单元测试执行过程中遵循的流控制结构中可能的条件的密度。条件覆盖= (CT + CF) / (2*B)，其中，CT =已评估为“true”至少一次的条件；CF=已评估为“false”至少一次的条件;B=条件总数

2.       新代码的条件覆盖：与条件覆盖相同，但仅限于新的/更新的源代码。

3.       覆盖：它是行覆盖和条件覆盖的混合体。其目的是更准确地回答以下问题：单元测试涵盖了多少源代码？覆盖=(CT + CF + LC)/(2*B + EL)，其中，CT =已评估为“true”至少一次的条件；CF=已评估为“false”至少一次的条件; LC = covered lines = lines_to_cover - uncovered_lines；B=条件总数；EL = total number of executable lines (lines_to_cover)

4.       行覆盖：在给定的代码行上，行覆盖回答以下问题：这一行代码是否在单元测试的执行过程中被执行过？它是单元测试覆盖行的密度。行覆盖=LC / EL，其中，LC = covered lines (lines_to_cover - uncovered_lines)，EL = total number of executable lines (lines_to_cover)         

5.       单元测试持续时间：执行所有单元测试所需的时间

6.       单元测试成功密度（%）：Test success density = (Unit tests - (Unit test errors + Unit test failures)) / Unit tests * 100

7.       Unit test errors：失败的单元测试数量

8.       Unit test failures：由于意外异常而失败的单元测试数量

说明：关于测试执行的度量不存在于集成测试和整体测试中

八、概念

1.       Analyzer分析器：分析源代码以计算快照的客户端应用程序

2.       Database：存储配置和快照

3.       Server：用于浏览快照数据和进行配置更改的Web接口

4.       Bug：表示代码中某些错误的问题。这个问题需要修复

5.       Check：Check = Coding Rule.编码规则

6.       Code Smell：代码中与可维护性相关的问题。最坏的情况是，维护人员会被代码的状态弄糊涂，在进行更改时会引入额外的错误。

7.       Coding Rule：一个很好的编码实践。不遵守编码规则会导致质量缺陷并在SONAR中产生问题。编码规则可以检查文件、单元测试或包的质量。

8.       Issue：当组件不符合编码规则时，问题被记录在快照上；可以在源文件或单元测试文件上记录问题。有三种类型的问题：1）Code Smell：影响您的可维护性等级的问题，防止您像从头开始时那样快速地注入更改。2）Bug: 突出软件中真正或潜在的故障点的问题。3）漏洞：突出显示可用于攻击您的软件的安全漏洞的问题。

9.       Leak Period：您正在密切关注代码中新问题的引入的时间段。通常情况下，这是从上一个版本开始的，但是如果您不使用类似maven的版本控制方案，您可能需要设置一个相对任意的时间段，比如21天或某个特定的日期。

10.    Non-functional requirement：非功能性需求=编码规则

11.    Quality Profile：质量配置文件，一组编码规则。每个快照都基于单个质量配置文件。

12.    Remediation Cost：估计的、用于修复漏洞和可靠性问题所需的时间。

13.    Snapshot：快照。给定时间内对给定组件的一组度量和问题。每个分析生成一个快照。

14.    Technical Debt：修复所有可维护性问题/代码气味所需的估计时间。

15.    Vulnerability：漏洞。一个与安全相关的问题，对攻击者来说是一个用于攻击系统的潜在的后门

九、活动与历史（Activity and History）

项目活动页面提供了一个项目分析的全面列表，以及随时查看项目度量的能力。活动页面上的图表帮助您了解您所选择的最多三种度量方法的演变情况。

四种事件类型：

1.       质量阀：质量阀的状态发生了变化

2.       配置文件：用于分析项目的质量配置文件发生了更改-要么是编辑了配置文件，要么是使用了不同的配置文件来分析项目。

3.       项目版本：项目版本变化了

4.       其他：事件是在快照上手动创建的。

5.      

十、可视化

         可视化可以帮助您更深入地了解项目的当前状态和历史。

         如何比较多个项目或项目组件的当前状态？项目空间允许您通过多个基于度量的标准过滤实例中的项目。一旦您选择了您的集合，您就不必盯着原始数字来确定其项目所面临的风险。相反，可以使用几个可视化(项目>透视图)来帮助您了解每个项目在每一个主要轴上的相对位置：

1.       风险-可靠性和安全性评级、测试覆盖率、技术债务和代码行。

2.       可靠性-可靠性等级、可靠性补救工作、代码行和Bug数量

3.       安全性-安全等级、安全补救工作、代码行和漏洞计数

4.       可维护性-可维护性等级、技术债务、代码行和代码嗅觉（code smell）计数

5.       覆盖率-覆盖范围、复杂性和未覆盖的行

6.       重复-重复行百分比、代码行和重复块

十一、项目组合

         项目组合主页是管理人员和技术领导关注其监督下的项目的可发布性的中心位置。可发布性是基于项目的质量大门：绿色或橙色(通过或警告)是可发布的，而红色(错误)不能发布。每个组合主页提供了一个组合中所有项目的可发布性的汇总视图。

         在页面的顶部，您可以很容易地看到总体组合目前是否被评为可发布的，以及组合中的项目是否没有达到其质量标准。可靠性、安全性和可维护性评级显示了这三个领域的组合的总体健康状况，以及每个领域中表现最差的项目的指标。

可发布性评级告诉您，组合中没有失败质量门(QG being PASSED or WARNING)的项目的比例：

l  A: > 80%

l  B: > 60%

l  C: > 40%

l  D: > 20%

l  E: <= 20%

可靠性、安全性和可维护性评级

每个组合的可靠性、安全性和可维护性评级都计算为项目组合中包含的所有项目的平均评级。Sonarqube将每个项目的评级转换为一个数字，计算组合的平均值，并将该平均值转换为评级，平均值采用四舍五入法（比如2.6，结果计为3）。等级与得分的关系如下：

E：  5

D：  4

C：  3

B：  2

A：  1