代码质量

极狐GitLab 代码质量在可维护性问题成为技术债务之前识别它们。在代码审查过程中发生的自动反馈可以帮助您的团队编写更好的代码。这些发现直接显示在合并请求中，使问题在最具成本效益的解决时可见。

极狐GitLab 代码质量支持多种编程语言，并与常见的 linter、样式检查器和复杂度分析器集成。您现有的工具可以融入代码质量工作流中，保留团队偏好的同时标准化结果显示方式。

各版本功能#

不同的功能在不同的 极狐GitLab 版本中可用，如下表所示：

扫描代码质量违规#

极狐GitLab 代码质量是一个开放系统，支持从许多扫描工具导入结果。为了发现违规行为并将其显示出来，您可以：

• 直接使用扫描工具并导入其结果。(首选。)
• 使用内置 CI/CD 模板启用扫描。该模板使用 CodeClimate 引擎，封装了常见的开源工具。(已弃用。)

您可以在单个流水线中捕获多个工具的结果。例如，您可以运行代码 linter 来扫描您的代码，同时使用语言 linter 来扫描您的文档，或者您可以使用独立工具与基于 CodeClimate 的扫描结合使用。极狐GitLab 代码质量将所有报告合并，以便您在查看结果时看到所有结果。

从 CI/CD 作业导入代码质量结果#

许多开发团队已经在他们的 CI/CD 流水线中使用 linter、样式检查器或其他工具来自动检测编码标准的违规行为。通过将这些工具与代码质量集成，可以更容易地查看和修复这些发现。

要查看您的工具是否已经有文档化的集成，请参阅将常用工具与代码质量集成。

要将不同的工具与代码质量集成：

1. 将工具添加到您的 CI/CD 流水线中。
2. 配置工具以文件形式输出报告。
   • 该文件必须使用特定的 JSON 格式。
   • 许多工具本身支持这种输出格式。它们可能称其为“CodeClimate 报告”、“极狐GitLab 代码质量报告”或其他类似名称。
   • 其他工具有时可以使用自定义 JSON 格式或模板创建 JSON 输出。由于报告格式只有几个必填字段，您可能能够使用此输出类型为代码质量创建报告。
3. 声明一个 codequality 报告产物，与此文件匹配。

现在，在流水线运行后，质量工具的结果将被处理和显示。

使用内置代码质量 CI/CD 模板（已弃用）#

代码质量还包括一个内置的 CI/CD 模板，Code-Quality.gitlab-ci.yaml。该模板基于开源 CodeClimate 扫描引擎运行扫描。

CodeClimate 引擎运行：

• 对支持语言集的基本可维护性检查。
• 一组可配置的插件，它们封装开源扫描器，以分析您的源代码。

有关详细信息，请参阅配置基于 CodeClimate 的代码质量扫描。

从基于 CodeClimate 的扫描迁移#

CodeClimate 引擎使用一组可自定义的分析插件。有些默认开启；其他必须显式启用。以下集成可用于替换内置插件：

查看代码质量结果#

代码质量结果显示在以下位置：

• 合并请求小部件
• 合并请求更改视图
• 流水线详细信息视图
• 项目质量视图

合并请求小部件#

如果可以提供目标分支的报告进行比较，代码质量分析结果会显示在合并请求小部件区域。合并请求小部件显示在合并请求中引入的代码质量发现和解决方案。多个具有相同指纹的代码质量发现会在合并请求小部件中作为单个条目显示。每个单独的发现可在流水线详细信息视图中查看完整报告。

合并请求更改视图#

代码质量结果显示在合并请求的更改视图中。包含代码质量问题的行旁边会标记一个符号。选择该符号以查看问题列表，然后选择一个问题查看其详细信息。

流水线详细信息视图#

流水线生成的完整代码质量违规列表显示在流水线详细信息页面的代码质量选项卡中。流水线详细信息视图显示在其运行的分支上发现的所有代码质量发现。

项目质量视图#

版本历史

• 在极狐GitLab 14.5 中引入，使用名为 project_quality_summary_page 的功能标志。此功能处于测试版。默认禁用。

项目质量视图显示代码质量发现的概述。可以在分析 > CI/CD 分析下找到该视图，并要求为此特定项目启用 project_quality_summary_page 功能标志。

代码质量报告格式#

您可以从任何能够以以下格式输出报告的工具导入代码质量结果。此格式是CodeClimate 报告格式的一个版本，包含较少的字段。

您提供的作为代码质量报告产物的文件必须包含一个单一的 JSON 数组。该数组中的每个对象必须至少具有以下属性：

该格式与CodeClimate 报告格式不同，具体如下：

• 尽管CodeClimate 报告格式支持更多属性，但代码质量仅处理上面列出的字段。
• 极狐GitLab 解析器不允许在文件开头有字节顺序标记。

例如，这是一个合规的报告：

json
复制
1[
2  {
3    "description": "'unused' is assigned a value but never used.",
4    "check_name": "no-unused-vars",
5    "fingerprint": "7815696ecbf1c96e6894b779456d330e",
6    "severity": "minor",
7    "location": {
8      "path": "lib/index.js",
9      "lines": {
10        "begin": 42
11      }
12    }
13  }
14]

将常用工具与代码质量集成#

许多工具本身支持所需的报告格式，以将其结果与代码质量集成。它们可能称其为“CodeClimate 报告”、“极狐GitLab 代码质量报告”或其他类似名称。

其他工具可以通过提供自定义模板或格式规范来创建 JSON 输出。由于报告格式只有几个必填字段，您可能能够使用此输出类型为代码质量创建报告。

如果您已经在 CI/CD 流水线中使用工具，您应调整现有作业以添加代码质量报告。调整现有作业可以防止您运行一个可能让开发人员感到困惑并使流水线运行时间更长的单独作业。

如果您还没有使用工具，可以从头编写 CI/CD 作业，或者使用 CI/CD 目录中的组件来采用工具。

代码扫描工具#

ESLint#

如果您已经在 CI/CD 流水线中有一个 ESLint 作业，您应添加一个报告以将其输出发送到代码质量。要集成其输出：

1. 在您的项目中将 eslint-formatter-gitlab 添加为开发依赖项。
2. 在运行 ESLint 的命令中添加 --format gitlab 选项。
3. 声明一个 codequality 报告产物，指向报告文件的位置。
   • 默认情况下，格式化程序会读取您的 CI/CD 配置并推断保存报告的文件名。如果格式化程序无法推断出您在产物声明中使用的文件名，请将 CI/CD 变量 ESLINT_CODE_QUALITY_REPORT 设置为您为产物指定的文件名，例如 gl-code-quality-report.json。

您还可以使用或调整 ESLint CI/CD 组件来运行扫描并将其输出与代码质量集成。

Stylelint#

如果您已经在 CI/CD 流水线中有一个 Stylelint 作业，您应添加一个报告以将其输出发送到代码质量。要集成其输出：

1. 在您的项目中将 @studiometa/stylelint-formatter-gitlab 添加为开发依赖项。
2. 在运行 Stylelint 的命令中添加 --custom-formatter=@studiometa/stylelint-formatter-gitlab 选项。
3. 声明一个 codequality 报告产物，指向报告文件的位置。
   • 默认情况下，格式化程序会读取您的 CI/CD 配置并推断保存报告的文件名。如果格式化程序无法推断出您在产物声明中使用的文件名，请将 CI/CD 变量 STYLELINT_CODE_QUALITY_REPORT 设置为您为产物指定的文件名，例如 gl-code-quality-report.json。

MyPy#

如果您已经在 CI/CD 流水线中有一个 MyPy 作业，您应添加一个报告以将其输出发送到代码质量。要集成其输出：

1. 在您的项目中安装 mypy-gitlab-code-quality 作为依赖项。

2. 更改您的 mypy 命令以将其输出发送到文件。

3. 在作业 script 中添加一个步骤，使用 mypy-gitlab-code-quality 重新处理文件为所需格式。例如：

   yaml
   复制
   - mypy $(find -type f -name "*.py" ! -path "**/.venv/**") --no-error-summary > mypy-out.txt || true  # "|| true" 用于防止 mypy 找到错误时作业失败
   - mypy-gitlab-code-quality < mypy-out.txt > gl-code-quality-report.json

4. 声明一个 codequality 报告产物，指向报告文件的位置。

您还可以使用或调整 MyPy CI/CD 组件 来运行扫描并将其输出与代码质量集成。

Flake8#

如果您已经在 CI/CD 流水线中有一个 Flake8 作业，您应添加一个报告以将其输出发送到代码质量。要集成其输出：

1. 在您的项目中安装 flake8-gl-codeclimate 作为依赖项。
2. 在运行 Flake8 的命令中添加参数 --format gl-codeclimate --output-file gl-code-quality-report.json。
3. 声明一个 codequality 报告产物，指向报告文件的位置。

您还可以使用或调整 Flake8 CI/CD 组件 来运行扫描并将其输出与代码质量集成。

Pylint#

如果您已经在 CI/CD 流水线中有一个 Pylint 作业，您应添加一个报告以将其输出发送到代码质量。要集成其输出：

1. 在您的项目中安装 pylint-gitlab 作为依赖项。
2. 在运行 Pylint 的命令中添加参数 --output-format=pylint_gitlab.GitlabCodeClimateReporter。
3. 更改您的 pylint 命令以将其输出发送到文件。
4. 声明一个 codequality 报告产物，指向报告文件的位置。

您还可以使用或调整 Pylint CI/CD 组件 来运行扫描并将其输出与代码质量集成。

Ruff#

如果您已经在 CI/CD 流水线中有一个 Ruff 作业，您应添加一个报告以将其输出发送到代码质量。要集成其输出：

1. 在运行 Ruff 的命令中添加参数 --output-format=gitlab。
2. 更改您的 ruff check 命令以将其输出发送到文件。
3. 声明一个 codequality 报告产物，指向报告文件的位置。

您还可以使用或调整已记录的 Ruff 极狐GitLab CI/CD 集成来运行扫描并将其输出与代码质量集成。

golangci-lint#

如果您已经在 CI/CD 流水线中有一个 golangci-lint 作业，您应添加一个报告以将其输出发送到代码质量。要集成其输出：

1. 在运行 golangci-lint 的命令中添加参数 --out-format code-climate:gl-code-quality-report.json,line-number。
2. 声明一个 codequality 报告产物，指向报告文件的位置。

您还可以使用或调整 golangci-lint CI/CD 组件来运行扫描并将其输出与代码质量集成。

PMD 复制/粘贴检测器#

PMD 复制/粘贴检测器 (CPD) 需要额外的配置，因为其默认输出不符合所需格式。

您可以使用或调整 PMD CI/CD 组件来运行扫描并将其输出与代码质量集成。

SwiftLint#

使用 SwiftLint 需要额外的配置，因为其默认输出不符合所需格式。

您可以使用或调整 SwiftLint CI/CD 组件来运行扫描并将其输出与代码质量集成。

RuboCop#

使用 RuboCop 需要额外的配置，因为其默认输出不符合所需格式。

您可以使用或调整 RuboCop CI/CD 组件来运行扫描并将其输出与代码质量集成。

Roslynator#

使用 Roslynator 需要额外的配置，因为其默认输出不符合所需格式。

您可以使用或调整 Roslynator CI/CD 组件来运行扫描并将其输出与代码质量集成。

文档扫描工具#

您可以使用代码质量扫描存储库中存储的任何文件，即使它不是代码。

Vale#

如果您已经在 CI/CD 流水线中有一个 Vale 作业，您应添加一个报告以将其输出发送到代码质量。要集成其输出：

1. 在您的存储库中创建一个 Vale 模板文件，定义所需格式。
   • 您可以复制用于检查极狐GitLab 文档的开源模板。
   • 您还可以使用其他开源变体，例如社区 gitlab-ci-utils Vale 项目中使用的变体。此社区项目还提供了一个预制容器镜像，您可以直接在流水线中使用它。
2. 在运行 Vale 的命令中添加参数 --output="$VALE_TEMPLATE_PATH" --no-exit。
3. 更改您的 vale 命令以将其输出发送到文件。
4. 声明一个 codequality 报告产物，指向报告文件的位置。

markdownlint-cli2#

如果您已经在 CI/CD 流水线中有一个 markdownlint-cli2 作业，您应添加一个报告以将其输出发送到代码质量。要集成其输出：

1. 在您的项目中将 markdownlint-cli2-formatter-codequality 添加为开发依赖项。

2. 如果您还没有，请在存储库的顶层创建一个 .markdownlint-cli2.jsonc 文件。

3. 向 .markdownlint-cli2.jsonc 添加一个 outputFormatters 指令：

   json
   复制
   {
     "outputFormatters": [
       [ "markdownlint-cli2-formatter-codequality" ]
     ]
   }

4. 声明一个 codequality 报告产物，指向报告文件的位置。默认情况下，报告文件名为 markdownlint-cli2-codequality.json。

   1. 建议。将报告的文件名添加到存储库的 .gitignore 文件中。