代码质量检查工具集成

在Koa2项目中，集成代码质量检查工具能有效提升代码规范性和可维护性。通过自动化检查，团队可以快速发现潜在问题，减少低级错误，同时统一代码风格。下面从工具选择、配置到实际应用逐步展开。

代码质量检查工具的选择

Koa2作为Node.js框架，常用的代码检查工具包括ESLint、Prettier和Husky。ESLint负责语法检查，Prettier处理代码格式化，Husky在Git提交时触发检查。例如：

// package.json中典型依赖
{
  "devDependencies": {
    "eslint": "^8.56.0",
    "prettier": "^3.2.5",
    "husky": "^9.0.11",
    "lint-staged": "^15.2.2"
  }
}

针对TypeScript项目还需添加@typescript-eslint/parser和@typescript-eslint/eslint-plugin。团队可根据项目技术栈组合工具，如Airbnb规范或Standard规范。

ESLint的详细配置

在项目根目录创建.eslintrc.js配置文件，Koa2推荐使用以下规则：

module.exports = {
  env: {
    node: true,
    es2021: true
  },
  extends: ['eslint:recommended', 'plugin:@typescript-eslint/recommended'],
  parser: '@typescript-eslint/parser',
  parserOptions: {
    ecmaVersion: 'latest',
    sourceType: 'module'
  },
  rules: {
    'no-console': process.env.NODE_ENV === 'production' ? 'error' : 'warn',
    'no-unused-vars': ['error', { argsIgnorePattern: '^_' }],
    '@typescript-eslint/explicit-function-return-type': 'off',
    'indent': ['error', 2, { SwitchCase: 1 }]
  }
};

通过--fix参数可自动修复部分问题：

npx eslint src --ext .ts,.js --fix

Prettier与ESLint的协同工作

当同时使用Prettier和ESLint时，需要安装eslint-config-prettier避免规则冲突。配置示例：

// .prettierrc
{
  "semi": true,
  "singleQuote": true,
  "printWidth": 100,
  "trailingComma": "all"
}

在ESLint配置中扩展Prettier：

// .eslintrc.js
extends: [
  'eslint:recommended',
  'plugin:@typescript-eslint/recommended',
  'prettier'
]

Git提交时的自动化检查

通过Husky和lint-staged实现提交前检查：

// package.json
{
  "scripts": {
    "prepare": "husky install",
    "lint-staged": "lint-staged"
  },
  "lint-staged": {
    "*.{js,ts}": ["eslint --fix", "prettier --write"]
  }
}

初始化Husky钩子：

npx husky add .husky/pre-commit "npm run lint-staged"

自定义规则的实践案例

针对Koa2中间件的特殊检查需求，可添加自定义规则。例如强制中间件返回Promise：

// eslint-plugin-koa2-rules.js
module.exports = {
  rules: {
    'require-async-middleware': {
      create(context) {
        return {
          CallExpression(node) {
            if (node.callee.name === 'use') {
              const arg = node.arguments[0];
              if (arg && arg.async !== true) {
                context.report({
                  node,
                  message: 'Koa2中间件应该使用async函数'
                });
              }
            }
          }
        };
      }
    }
  }
};

在配置中启用：

// .eslintrc.js
plugins: ['koa2-rules'],
rules: {
  'koa2-rules/require-async-middleware': 'error'
}

持续集成中的质量检查

在GitHub Actions中配置自动化检查：

# .github/workflows/lint.yml
name: Lint
on: [push, pull_request]
jobs:
  lint:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
      - run: npm ci
      - run: npm run lint
      - run: npm test

性能优化检查

针对Koa2性能关键路径添加特殊检查规则：

// 检测未释放的数据库连接
rules: {
  'no-unclosed-connection': {
    create(context) {
      return {
        'CallExpression[callee.property.name="getConnection"]'(node) {
          if (!findMatchingRelease(node)) {
            context.report({
              node,
              message: '数据库连接未释放'
            });
          }
        }
      };
    }
  }
}

错误处理规范

强制Koa2项目使用统一错误处理中间件：

rules: {
  'error-handler-middleware': {
    create(context) {
      let hasErrorHandler = false;
      return {
        'CallExpression[callee.property.name="use"]'(node) {
          if (isErrorHandler(node.arguments[0])) {
            hasErrorHandler = true;
          }
        },
        'Program:exit'() {
          if (!hasErrorHandler) {
            context.report({
              loc: { line: 1, column: 1 },
              message: '未发现错误处理中间件'
            });
          }
        }
      };
    }
  }
}

与测试框架的集成

在Jest测试中添加代码质量检查：

// jest.config.js
module.exports = {
  // ...
  setupFilesAfterEnv: ['./test/setup.js']
};

// test/setup.js
beforeAll(() => {
  if (process.env.CI === 'true') {
    const { execSync } = require('child_process');
    try {
      execSync('npm run lint', { stdio: 'inherit' });
    } catch {
      process.exit(1);
    }
  }
});

可视化报告生成

使用ESLint的HTML报告插件：

npm install eslint-html-reporter --save-dev

配置输出HTML报告：

// .eslintrc.js
settings: {
  'html-reporter': {
    outputPath: 'reports/eslint-report.html'
  }
}

运行命令：

npx eslint src --format html --output-file reports/eslint-report.html

自定义格式化规则

针对Koa2路由定义的特殊格式化需求：

// .prettierrc
{
  "koaRouteIndent": 2,
  "overrides": [
    {
      "files": ["**/routes/*.ts"],
      "options": {
        "printWidth": 120,
        "arrowParens": "avoid"
      }
    }
  ]
}

历史代码的渐进式改造

对于已有项目，可配置只检查新增代码：

// .eslintrc.js
rules: {
  'no-var': 'error',
  'prefer-const': ['error', { ignoreReadBeforeAssign: true }]
}

配合Git修改检查：

npx eslint $(git diff --name-only HEAD..origin/main --diff-filter=ACM | grep '\.ts$')