代码质量

代码质量可以在可维护性问题变成技术债务之前识别它们。 代码审查过程中发生的自动反馈可以帮助您的团队编写更好的代码。 发现的问题会直接显示在合并请求中，在修复成本最低时让问题变得可见。

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

各版本功能特性

不同的 GitLab 版本 提供不同的功能，如下表所示：

扫描代码质量违规

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

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

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

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

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

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

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

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 引擎使用一组可自定义的分析插件。 有些默认启用；其他必须明确启用。 以下集成可用于替换内置插件：

查看代码质量结果

代码质量结果显示在：

• 合并请求组件
• 合并请求变更视图
• 流水线详情视图
• 项目质量视图

合并请求组件

如果有来自目标分支的报告可用于比较，代码质量分析结果会显示在合并请求组件区域。 合并请求组件显示由合并请求中的变更引入的代码质量发现的问题和解决方案。 具有相同指纹的多个代码质量发现在合并请求组件中显示为单个条目。 每个单独的发现在流水线详情视图的完整报告中可用。

合并请求变更视图

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

流水线详情视图

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

项目质量视图

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

代码质量报告格式

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

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

该格式与 CodeClimate 报告格式在以下方面不同：

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

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

[
  {
    "description": "'unused' 被赋值但从未使用。",
    "check_name": "no-unused-vars",
    "fingerprint": "7815696ecbf1c96e6894b779456d330e",
    "severity": "minor",
    "location": {
      "path": "lib/index.js",
      "lines": {
        "begin": 42
      }
    }
  }
]

集成常用工具与代码质量

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

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

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

如果您尚未使用工具，您可以从头开始编写 CI/CD 作业，或使用CI/CD 目录中的组件采用该工具。

代码扫描工具

ESLint

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

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

更多详情和示例 CI/CD 作业定义，请参阅 @studiometa/stylelint-formatter-gitlab 的文档。

MyPy

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

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

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

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

   - 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. 将参数 --format gl-codeclimate --output-file gl-code-quality-report.json 添加到您用于运行 Flake8 的命令中。
3. 声明一个指向报告文件位置的codequality 报告产物。

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

Pylint

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

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

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

Ruff

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

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

您也可以使用或调整文档化的 Ruff GitLab CI/CD 集成 来运行扫描并将其输出与代码质量集成。

golangci-lint

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

1. 将参数添加到您用于运行 golangci-lint 的命令中。

   对于 v1 添加 --out-format code-climate:gl-code-quality-report.json,line-number。

   对于 v2 添加 --output.code-climate.path=gl-code-quality-report.json。

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. 将参数 --output="$VALE_TEMPLATE_PATH" --no-exit 添加到您用于运行 Vale 的命令中。
3. 更改您的 vale 命令以将其输出发送到文件。
4. 声明一个指向报告文件位置的codequality 报告产物。

您也可以使用或调整开源作业定义来运行扫描并将其输出与代码质量集成，例如：

• 用于检查 GitLab 文档的 Vale 检查步骤。
• 社区 gitlab-ci-utils Vale 项目。

markdownlint-cli2

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

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

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

3. 将 outputFormatters 指令添加到 .markdownlint-cli2.jsonc：

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

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

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

更多详情和示例 CI/CD 作业定义，请参阅 markdownlint-cli2-formatter-codequality 的文档。