《企业实战分享 · SonarQube10.x 代码质量推广手册》

📢 大家好，我是【战神刘玉栋】，有10多年的研发经验，致力于前后端技术栈的知识沉淀和传播。 💗

🌻 CSDN入驻不久，希望大家多多支持，后续会继续提升文章质量，绝不滥竽充数，欢迎多多交流。👍

文章目录

写在前面的话
Sonar 概述
- 背景说明
- 技术简介
- 参考资料
Sonar 开发手册
- Sonar 网站操作
- IDEA 插件操作
- Maven 命令接入
- GitLab CI/CD 接入
- pre-commit 拦截
Sonar 修复实践
- 关于问题类型
- 关于异常级别
- 若干修复建议
Sonar 管理推行
- 团队协作
- 持续改进
- 总结陈词

写在前面的话

本篇文章以企业实战的角度，介绍一下质量管理工具 Sonar 在企业中的实战推广过程，可以覆盖大部分运用场景。

Sonar 概述

背景说明

随着软件开发的复杂性增加，代码质量的管理变得尤为重要。为提升代码质量，降低代码缺陷率，提高代码可维护性和可读性，同时辅助Code Review的工作开展，现引入SonarQube作为代码质量管理工具。

技术简介

【概述】

SonarQube 作为一款开源的代码质量管理工具，能够帮助团队识别和解决代码中的潜在问题，从而提高软件的可维护性和可靠性。本文旨在为团队提供SonarQube的实施指南，确保每位成员了解其重要性、使用方法及最佳实践，从而提升整体代码质量。

SonarQube 是一种自动代码审查工具，用于检测代码中的错误，漏洞和代码味道。它可以与您现有的工作流程集成，以实现跨项目分支和提取请求的连续代码检查。其目的是对代码库的质量进行360°透视。为此，它会定期分析项目的所有源代码行。

【与 Code Review 的关系】

Code Review（代码审查）和 SonarQube（或Sonar）在软件开发中都是提升代码质量的重要工具，但它们的侧重点和工作方式有所不同。

Code Review
侧重于： 人工审查代码，发现逻辑错误、设计缺陷、代码风格问题等。
优点：
  可以发现 Sonar 静态分析工具难以发现的问题，例如代码逻辑错误、设计缺陷等。
  可以促进团队成员之间的知识共享和代码规范的统一。
  可以提高代码的可读性和可维护性。
缺点：
  需要人工参与，效率较低，耗费时间。
  容易受到个人主观因素的影响，导致代码审查结果不一致。

Sonar
侧重于： 自动化代码分析，识别代码中的潜在问题，例如代码复杂度、重复代码、安全漏洞等。
优点：
  自动化程度高，效率高，可以快速识别代码中的问题。
  能够提供详细的代码质量分析报告，帮助开发人员了解代码质量状况。
  可以帮助团队建立统一的代码质量标准。
缺点：
  无法识别所有代码问题，例如逻辑错误、设计缺陷等。
  需要配置和维护，有一定的学习成本。

关系
互补: Code Review 和 Sonar 相互补充，共同提升代码质量。Sonar 可以帮助开发人员快速识别代码中的问题，而 Code Review 可以帮助开发人员发现 Sonar 难以发现的问题。
协同: Code Review 可以帮助开发人员更好地理解 Sonar 的分析结果，并针对性地进行代码改进。Sonar 可以帮助开发人员在 Code Review 之前识别代码中的问题，提高 Code Review 的效率。

总结：Code Review 和 SonarQube 在提升代码质量方面各有优势，结合使用可以最大化地提高代码的可维护性和可靠性。团队可以通过SonarQube进行初步的代码质量检查，再通过Code Review进行深入的审查和讨论，从而形成一个有效的代码质量管理流程。最佳实践是将 Code Review 和 Sonar 结合起来使用，以达到最佳的代码质量管理效果。

Tips：由于公司项目后端环境采用JDK21，Sonar 也搭配了较新版本的10.6。

参考资料

参考：SonarQube 官方文档

参考：SonarQube GitHub Repository

参考：SonarLint 官网

Sonar 开发手册

Sonar 网站操作

【功能描述】

Sonar 提供的Web界面，开发人员可以进入该网站查看项目漏洞，并根据提示修改。

管理人员可以进入该网站，配置规则、质量门阀、权限等内容。

【基础操作】

Step1、访问 Sonar 网站，如下所示。

Step2、点击具体项目，进入项目仪表盘

Step3、按需查看错误，并进行修正

【其他操作】

没有更多了，很简单的操作，可自行尝试。

IDEA 插件操作

SonarLint 是一个Sonar IDE插件，可以接收和连接 SonrarQube 对代码库扫描的结果从而通知 Developer，本身也可以基于一些规则对代码IDE中的代码进行即时的检测。它的目的是在您键入代码时提供即时反馈。为此，它着重于要添加或更新的代码。

SonarLint 是一个免费的开源IDE 扩展，可识别并帮助您在编写代码时解决质量和安全问题，像拼写检查器一样，会显示缺陷并提供实时反馈和清晰的修复指导，以便从一开始就提供干净的代码。

【功能描述】

搭配 Sonarqube 网站使用，开发人员在 IDEA 本地编码时，可以很方便的提前发现代码问题，而不需要事后从线上地址进入整改。该方式更加灵活，弥补了目前手工扫描 + 定时扫描机制的不及时性，也减轻了服务端频繁构建的压力。

Tips：适合本地发现错误提示和修改，不会影响线上结果。

【安装配置】

Step1、插件安装，IDEA直接搜索 SonarLint 插件并下载，重启IDEA。

Step2、服务端配置

打开 IDEA 的“设置面板 - SonarLint“，添加公司的远程数据源，按下面图示操作。

1、选择新增配置，输入服务地址输入，如下图所示。

2、下拉框选择 Token 或 Login/Passwor 认证方式，输入下方信息。

3、点击Next，即操作完成。

Step3、具体项目配置

配置完服务器之后，需要针对具体工程进行配置，下面以添加某具体项目为例。

绑定 Sonar 服务端上的具体项目，具体参考下图操作。

Step4、关闭实时扫描

下方配置项（图一），建议取消勾选，不然每次修改保存代码，都会进行Sonarlint的检查（如图二）。

【插件使用 - 手动触发扫描】

选择需要进行检查的类或者目录，右键，找到sonarlint的图标，进行sonarlint检查。

结果展示效果如下，这里的错误级别和线上版本是对应的。

【插件使用 - 提交代码时检查】

在commit代码的时候，勾选Perform Sonarlint analysis，会针对你要提交的代码进行Sonarlint检查。

仅仅会给出提示，可以继续提交。

Maven 命令接入

【功能描述】

IDEA 环境中，可以直接使用Maven命令的方式，手动触发代码扫描，如下图所示。

Tips：适合本地修复完问题后，但又未提交代码之前的动作，扫描结果会修改线上漏洞结果。

【接入步骤】

Step1、添加 Maven 插件

Tips：核心框架已统一集成该插件，这步可忽略。

<plugin>
    <groupId>org.sonarsource.scanner.maven</groupId>
    <artifactId>sonar-maven-plugin</artifactId>
    <version>3.10.0.2594</version>
</plugin>

Step2、执行 Maven 命令

mvn sonar:sonar -Psonar -Dmaven.test.skip=true -Dsonar.inclusions=**/*.java -Dsonar.projectKey=xxxxx -Dsonar.host.url=xxxxx -Dsonar.token=squ_c4b705291d74fd1bf9db9b1ea429dab64d9f2b59

Tips：认证信息也可以通过在 pom.xml 或 settings.xml 配置的方式，如下所示，这些都是灵活的。

<!-- SonarQube服务器地址-->
<sonar.host.url>xxxx</sonar.host.url>
<!-- 访问令牌或⽤户名密码 -->
<sonar.token>sqa_21f5d7a5d8a2d155b9d102676281364ee660fcb6</sonar.token>
<!--        <sonar.login>admin</sonar.login>-->
<!--        <sonar.password>sonar</sonar.password>-->

Step3、查看扫描结果，直接登录Sonar网站，查看具体项目的错误即可。

GitLab CI/CD 接入

【功能描述】

将 SonarQube 集成到持续集成/持续部署（CI/CD）流程中，确保每次代码提交或合并请求时都进行代码质量检查。

Tips：适合漏洞已修复完成，对代码相对自信，可以提交合并到主分支的场景，会自动触发 Sonar 扫描。

【操作步骤】

现以demo为例说明，该项目使用的.gitlab-ci.yml为项目根目录的，修改该文件，可以实现提交代码到主分支，自动触发 Sonar 扫描的效果。

Tips：下方仅为示例配置，可按实际需要调整，仅显示代码分析部分脚本

stages:
  - Code Analysis

.tag_def: &tag_def
  tags:
    - sky-lb-docker

Code Analysis:
  <<: *tag_def
  stage: Code Analysis
  rules:
    - if: '$CI_PIPELINE_SOURCE == "sonar"'
    - if: '$CI_COMMIT_BRANCH == "master"'
  script:
    - echo SONAR_HOST_URL=$ZT_SONAR_HOST_URL,  SONAR_LOGIN_TOKEN=$ZT_SONAR_LOGIN_TOKEN
    - mvn clean verify sonar:sonar -Psonar -Dmaven.test.skip=true -Dsonar.inclusions=**/*.java -Dsonar.projectKey=$CI_PROJECT_NAME -Dsonar.host.url=$ZT_SONAR_HOST_URL -Dsonar.login=$ZT_SONAR_LOGIN_TOKEN  -s settings_zoe.xml

注意， $ZT_SONAR_HOST_URL和$ ZT_SONAR_LOGIN_TOKEN是变量方式配置，也可以直接写死，如下。

【效果展示】

可以在该项目的 Gitlab 界面，查看CI/CD的进展，如下所示。

【关于gitlab-ci 配置位置】

目前测试阶段，.gitlab-ci.yml文件采用项目本地的，后续可以调整为通过公用配置文件，统一管控，包括变量信息的维护。

pre-commit 拦截

【功能描述】

使用 pre-commit 钩子来阻止代码提交，直到 SonarQube 检测通过，是一种有效的代码质量管理策略。

Tips：适合想本地提交代码时，先根据 Sonar 扫描检测的场景，前期规则不完善时，不推荐。

【什么是 Pre-commit 钩子】

Pre-commit 钩子是 Git 提供的一种机制，允许在执行 git commit 命令之前运行自定义脚本。通过这个钩子，可以在代码提交之前执行一些检查，比如代码风格、测试覆盖率、静态分析等。

确保代码质量：通过在提交前检查代码质量，确保只有符合标准的代码才能被提交。
减少后期修复成本：在开发过程中及时发现问题，避免在后期发现并修复，降低维护成本。

【效果示例】

【特别注意】

注意，这方案还存在问题：

1、每次提交执行还得先触发sonar动作，然后再查结果，提交效率降低，而且还有时效问题；

2、规则库目前不明确，制度也不明确，还是作为一个辅助功能；

Tips：还可以借助 SonarQube Scanner 的 exitCode 属性，搭配 pre-commit 或 gitlab-ci 完成校验。

Sonar 修复实践

关于问题类型

这些问题分类，可以帮助开发者识别和修复不同类型的问题，从而提高代码质量和安全性。

1、漏洞（Vulnerability）

指代码中存在的安全问题，可能导致安全漏洞或被攻击者利用。

指代码中存在的安全缺陷，可能被恶意攻击者利用，导致系统安全风险。例如，SQL 注入漏洞、跨站脚本攻击漏洞等。

建议优先修复所有漏洞，以确保应用程序的安全性。

2、BUG

指代码中的缺陷或错误，可能导致程序在运行时出现意外行为或崩溃。

指代码中的错误，会导致程序运行错误或异常。例如，逻辑错误、语法错误、数据类型错误等。

建议尽快修复，尤其是那些影响用户体验或功能的 bug。

3、异味（Code Smell）

指代码中的潜在问题，虽然不一定会导致错误或漏洞，但可能影响代码的可读性、可维护性或性能。

指代码中存在的设计缺陷或不良编码习惯，虽然不会导致程序错误，但会降低代码的可读性、可维护性和可扩展性。例如，重复代码、过长函数、过度复杂的设计等。

虽然不一定需要立即修复，但建议定期审查和修复异味，以提高代码质量。

关于异常级别

这些异常级别，用于表示代码质量问题的严重性，帮助开发者优先处理最重要的问题。

在 SonarQube 10.x 版本中，确实对异常级别进行了简化，分为高（High）、中（Medium）和低（Low）三个级别。这种变化旨在简化用户体验，使得问题的优先级更加明确。

【9.x 版本的级别】

【两者对照关系】

若干修复建议

SonarQube 内置的 Java 规则是基于广泛的最佳实践和行业标准设计的，旨在帮助开发者提高代码质量和安全性。

但是，难免有部分规则，不符合公司场景，需要做灵活调整，这个磨合过程可能需要一定时间。

因此，这个过程不建议做强制修复完毕后，才允许提交，主要当作代码审查的辅助手动。

下方是一些 Sonar 的最佳实践，来源 Gpt：

在企业开发中，SonarQube（通常简称为 Sonar）是一个非常有用的工具，用于持续集成和代码质量管理。
以下是一些最佳实践，可以帮助您在企业开发中有效地使用 Sonar。

1. 集成到 CI/CD 流程中
将 SonarQube 集成到持续集成/持续部署（CI/CD）流程中，确保每次代码提交或合并请求时都进行代码质量检查。
使用 Jenkins、GitLab CI、GitHub Actions 等工具自动化 SonarQube 扫描。
2. 定义质量门
设置质量门（Quality Gates），以确保代码在合并之前满足特定的质量标准（如代码覆盖率、漏洞、代码气味等）。
质量门可以帮助团队在代码合并之前识别潜在问题。
3. 定期审查和修复问题
定期审查 SonarQube 报告，关注高风险问题和技术债务。
设定时间周期（如每 sprint 或每月）来修复 SonarQube 报告中的问题。
4. 使用自定义规则
根据团队的需求和项目的特性，创建和使用自定义规则，以确保代码符合企业的编码标准。
定期更新和审查这些规则，以适应项目的变化。
5. 培训团队成员
对团队成员进行 SonarQube 的培训，确保他们理解如何使用工具以及如何解读报告。
鼓励团队成员在开发过程中主动关注代码质量。
6. 监控技术债务
使用 SonarQube 的技术债务指标来监控和管理项目的技术债务。
制定计划逐步减少技术债务，确保项目的可维护性。
7. 关注代码覆盖率
设定代码覆盖率的目标，并确保在 SonarQube 中进行监控。
鼓励团队编写单元测试和集成测试，以提高代码覆盖率。
8. 使用分支分析
利用 SonarQube 的分支分析功能，确保在开发新特性或修复 bug 时，代码质量不会下降。
在合并请求中查看分支的质量报告，以便在合并之前解决问题。
9. 定期更新 SonarQube
定期更新 SonarQube 及其插件，以利用新功能和改进。
关注 SonarQube 的发布说明，了解新版本中的重要变化。
10. 生成报告和可视化
利用 SonarQube 提供的报告和可视化功能，向管理层和利益相关者展示代码质量的变化和改进。
使用这些报告来支持决策和资源分配。
11. 设置警报和通知
配置 SonarQube 的警报和通知功能，以便在代码质量下降时及时通知相关人员。
通过邮件或其他通知方式，确保团队成员能够及时响应问题。
12. 鼓励文化变革
在团队中建立代码质量的文化，鼓励开发人员在编码时关注质量，而不仅仅是在提交代码时。
通过代码审查和团队讨论，促进对代码质量的重视。
通过实施这些最佳实践，您可以在企业开发中有效地利用 SonarQube，提高代码质量，减少技术债务，从而提升团队的整体开发效率和软件质量。