dxheroes/dx-scanner

DX Scanner

镜像概述和主要用途

DX Scanner 是一款开源 CLI 工具，能够直接基于源代码“测量”开发者体验（DX）。它会推荐有助于改进产品开发的实践，并支持通过单个命令自动修复部分问题。

核心功能和特性

支持的编程语言

支持的版本控制系统

支持 GitHub、GitLab 和 Bitbucket（无论公共或私有仓库）：

bash
# GitHub 示例
dx-scanner run https://github.com/DXHeroes/dx-scanner

# GitLab 示例
dx-scanner run https://gitlab.com/ubon-refer/smart-refer-api

# Bitbucket 示例
dx-scanner run https://bitbucket.org/maras333/node-api-with-ts

使用场景和适用范围

• 开发团队评估和改进项目的开发者体验
• 在 CI/CD 流程中集成，自动化检查项目质量
• 多语言项目的标准化和最佳实践落地
• 快速识别并修复影响开发效率的问题

详细的使用方法和配置说明

依赖项

• npm（https://www.npmjs.com/get-npm%EF%BC%89
• git（https://git-scm.com/book/en/v2/Getting-Started-Installing-Git%EF%BC%89
• （可选）yarn（https://yarnpkg.com/getting-started/install%EF%BC%89

安装

使用 NPM

bash
npm install -g dx-scanner

使用 Yarn

bash
yarn global add dx-scanner

基本使用

bash
dx-scanner run [路径] [选项]

示例：

bash
dx-scanner run https://github.com/DXHeroes/dx-scanner

命令说明

bash
Usage: dx-scanner [command] [options]

Options:
  -V, --version         输出版本号
  -l --log              将调试日志和输出写入 ./dxscanner.log
  -h, --help            显示命令帮助

Commands:
  run [options] [path]  扫描项目以获取可能的 DX 建议
  init                  初始化 DX Scanner 配置
  practices [options]   列出所有实践的 ID、名称和影响级别
  help [command]        显示命令帮助

别名:
  dxs
  dxscanner

dx-scanner run 选项

bash
Usage: dx-scanner run [path] [options]

扫描项目以获取可能的 DX 建议

Options:
  -a --authorization <authorization>  仓库凭据（格式为 "token" 或 "username:token"；可通过环境变量 DXSCANNER_GIT_SERVICE_TOKEN 设置）
  -t --apiToken <apiToken>            DX Scanner API 凭据，可通过环境变量 DXSCANNER_API_TOKEN 设置
  --apiUrl <apiUrl>                   DX Scanner API 地址，可通过环境变量 DXSCANNER_API_URL 设置（默认：https://provider.dxscanner.io/api/v1）
  --ci                                CI 模式（默认：false）
  -d --details                        在报告中打印详细信息
  --fail <impact>                     当检测到指定影响级别的未实践项时，进程以代码 1 退出（high|medium|small|hint|off|all）（默认："off"）
  --fix                               尝试自动修复问题（默认：false）
  --fixPattern <pattern>              仅修复 ID 匹配正则表达式的规则
  -j --json                           以 JSON 格式打印报告（默认：false）
  --html [path]                       将报告保存为 HTML 文件（默认：false，默认路径：./report.html）
  -r --recursive                      递归扫描所有子文件夹中的组件（默认：false）
  --no-recursive                      在 CI 模式下禁用递归扫描
  -h, --help                          输出使用信息

示例:
  dx-scanner run
  dx-scanner run ./ --fail=high
  dx-scanner run github.com/DXHeroes/dx-scanner

自动修复功能

自动修复 DX Scanner 检测到的问题：

bash
dx-scanner run [路径] --fix

此命令会尝试修复所有尚未实践的“可修复”实践。如需排除特定实践的自动修复，可通过配置文件设置（见下文）。

也可使用 fixPattern 标志仅修复部分可修复实践：

bash
dx-scanner run [路径] --fix --fixPattern=lint

注意：fixPattern 标志会覆盖配置文件中的 fix 设置，因此即使配置文件中排除的实践，若匹配 fixPattern 也会被修复。

配置说明

添加 dxscannerrc.* 配置文件可修改默认设置，支持 .json、.yml 或点文件格式。也可运行 dx-scanner init 自动初始化配置。

实践配置

可关闭不需要扫描的实践、修改影响级别或覆盖默认值，需通过实践 ID 进行配置。

所有实践列表

可能的影响级别

high（高）
medium（中）
small（低）
hint（提示）
off（关闭）

配置文件示例

JSON 格式（dxscannerrc.json）：

json
{
    "practices": {
        "JavaScript.GitignoreCorrectlySet": "medium",
        "JavaScript.LoggerUsed": "off",
        "LanguageIndependent.DoesPullRequests": {
          "impact": "small"
        },
        "JavaScript.ESLintWithoutErrorsPractice": {
          "fix": true,
          "override": {
            "lintFilesPatterns": [".internal/**/*.js", "*.js"],
            "ignorePatterns": []
          }
        },
        "LanguageIndependent.ThinPullRequestsPractice": {
          "impact": "high",
          "override": {
            "measurePullRequestCount": 500
          }
        }
    }
}

YAML 格式（dxscannerrc.yaml）：

yaml
---
practices:
  JavaScript.GitignoreCorrectlySet: medium
  JavaScript.LoggerUsed: 'off'
  LanguageIndependent.DoesPullRequests:
    impact: small
  JavaScript.ESLintWithoutErrorsPractice:
    fix: true
    override:
      lintFilesPatterns: ['.internal/**/*.js', '*.js']
      ignorePatterns: []
  LanguageIndependent.ThinPullRequestsPractice:
    impact: high
    override:
      measurePullRequestCount: 500

CI 模式

使用 --ci 标志运行时，DX Scanner 进入 CI 模式。在此模式下，使用 CIReporter 输出结果，且默认启用递归扫描（即 --recursive 标志自动开启）。

如需在 CI 模式下禁用递归扫描，使用 --no-recursive 标志。

GitHub CI Action 集成

基本示例：在每次推送到仓库时运行 DX Scanner

创建 .github/workflows/main.yml：

yaml
name: DX Scanner
on: push
jobs:
  dx-scanner:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v1
      - name: 在代码上运行 DX Scanner
        uses: DXHeroes/dx-scanner@master
        with:
          github_token: ${{ secrets.GITHUB_TOKEN }}

https://github.com/settings/tokens/new 并https://help.github.com/en/actions/automating-your-workflow-with-github-actions/creating-and-using-encrypted-secrets%E3%80%82

分数计算

每个实践的影响级别对应特定分值，DX Scanner 使用这些分值计算总体 DX 分数：

high = 100 分
medium = 75 分
small = 50 分
hint = 25 分

已关闭的实践不纳入计算（0 分）。

支持

如未找到所需信息，可通过公共 Slack 联系我们。

贡献

欢迎为 DX Scanner 贡献代码，请遵循 贡献指南。

路线图

查看我们的 公开路线图。

许可证

DX Scanner 开源项目基于 MIT 许可证。