Back to Details

code-quality-management

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Code Quality Management

代码质量管理

You enforce code quality standards through automated checks: Biome for formatting/linting, ESLint for React rules, TypeScript for type safety, Vitest for unit tests, and Playwright for E2E tests.
你可以通过自动化检查来强制执行代码质量标准：使用Biome进行格式化与Lint检查，ESLint用于React规则校验，TypeScript保障类型安全，Vitest执行单元测试，Playwright负责端到端（E2E）测试。

Quality Gates Workflow

质量门禁工作流

Copy this checklist and track your progress:
Quality Gates Sequence:
- [ ] Step 1: Format code (Biome)
- [ ] Step 2: Lint code (ESLint + TypeScript)
- [ ] Step 3: Type check (TypeScript)
- [ ] Step 4: Run unit tests (Vitest)
- [ ] Step 5: Run E2E tests (Playwright)
All-in-one quality check:
bash
npm run lint && npm run type-check && npm run test
复制此检查清单并跟踪进度：
Quality Gates Sequence:
- [ ] Step 1: Format code (Biome)
- [ ] Step 2: Lint code (ESLint + TypeScript)
- [ ] Step 3: Type check (TypeScript)
- [ ] Step 4: Run unit tests (Vitest)
- [ ] Step 5: Run E2E tests (Playwright)
一站式质量检查：
bash
npm run lint && npm run type-check && npm run test

Quick Start

快速开始

Install dependencies

安装依赖

bash
npm install -D @biomejs/biome eslint @typescript-eslint/parser @typescript-eslint/eslint-plugin
npm install -D eslint-plugin-react-hooks eslint-plugin-react-refresh
npm install -D husky lint-staged vitest @playwright/test
bash
npm install -D @biomejs/biome eslint @typescript-eslint/parser @typescript-eslint/eslint-plugin
npm install -D eslint-plugin-react-hooks eslint-plugin-react-refresh
npm install -D husky lint-staged vitest @playwright/test

Configure package.json scripts

配置package.json脚本

json
{
  "scripts": {
    "build": "vite build",
    "lint": "eslint . --ext ts,tsx --report-unused-disable-directives --max-warnings 0",
    "lint:fix": "eslint . --ext ts,tsx --fix",
    "lint:ci": "eslint . --ext ts,tsx --max-warnings 0",
    "format": "biome format --write .",
    "format:check": "biome format --write --dry-run .",
    "type-check": "tsc --noEmit",
    "test": "vitest run",
    "test:coverage": "vitest run --coverage",
    "test:e2e": "playwright test",
    "test:e2e:ui": "playwright test --ui",
    "prepare": "husky"
  }
}
json
{
  "scripts": {
    "build": "vite build",
    "lint": "eslint . --ext ts,tsx --report-unused-disable-directives --max-warnings 0",
    "lint:fix": "eslint . --ext ts,tsx --fix",
    "lint:ci": "eslint . --ext ts,tsx --max-warnings 0",
    "format": "biome format --write .",
    "format:check": "biome format --write --dry-run .",
    "type-check": "tsc --noEmit",
    "test": "vitest run",
    "test:coverage": "vitest run --coverage",
    "test:e2e": "playwright test",
    "test:e2e:ui": "playwright test --ui",
    "prepare": "husky"
  }
}

Setup Biome

配置Biome

Create 
biome.json
:
json
{
  "$schema": "https://biomejs.dev/schemas/1.9.0/schema.json",
  "organizeImports": { "enabled": true },
  "linter": {
    "enabled": true,
    "rules": {
      "recommended": true,
      "style": { "useImportType": "error", "useConst": "error" },
      "suspicious": { "noExplicitAny": "warn" },
      "correctness": {
        "noUnusedVariables": "error",
        "noUnusedImports": "error"
      }
    }
  },
  "formatter": { "enabled": true }
}
See BIOME.md for advanced configuration and import organization.
创建
biome.json
：
json
{
  "$schema": "https://biomejs.dev/schemas/1.9.0/schema.json",
  "organizeImports": { "enabled": true },
  "linter": {
    "enabled": true,
    "rules": {
      "recommended": true,
      "style": { "useImportType": "error", "useConst": "error" },
      "suspicious": { "noExplicitAny": "warn" },
      "correctness": {
        "noUnusedVariables": "error",
        "noUnusedImports": "error"
      }
    }
  },
  "formatter": { "enabled": true }
}
查看BIOME.md了解高级配置与导入组织方法。

Setup ESLint

配置ESLint

Create 
.eslintrc.cjs
:
javascript
module.exports = {
  root: true,
  env: { browser: true, es2020: true },
  extends: [
    'eslint:recommended',
    'plugin:@typescript-eslint/recommended',
    'plugin:react-hooks/recommended',
  ],
  ignorePatterns: ['dist', '.eslintrc.cjs'],
  parser: '@typescript-eslint/parser',
  plugins: ['react-refresh'],
  rules: {
    'react-refresh/only-export-components': [
      'warn',
      { allowConstantExport: true },
    ],
    '@typescript-eslint/no-unused-vars': ['error', { argsIgnorePattern: '^_' }],
    '@typescript-eslint/no-explicit-any': 'warn',
    'react-hooks/rules-of-hook': 'error',
    'react-hooks/exhaustive-deps': 'warn',
  },
};
See ESLINT.md for React-specific rules and customization.
创建
.eslintrc.cjs
：
javascript
module.exports = {
  root: true,
  env: { browser: true, es2020: true },
  extends: [
    'eslint:recommended',
    'plugin:@typescript-eslint/recommended',
    'plugin:react-hooks/recommended',
  ],
  ignorePatterns: ['dist', '.eslintrc.cjs'],
  parser: '@typescript-eslint/parser',
  plugins: ['react-refresh'],
  rules: {
    'react-refresh/only-export-components': [
      'warn',
      { allowConstantExport: true },
    ],
    '@typescript-eslint/no-unused-vars': ['error', { argsIgnorePattern: '^_' }],
    '@typescript-eslint/no-explicit-any': 'warn',
    'react-hooks/rules-of-hook': 'error',
    'react-hooks/exhaustive-deps': 'warn',
  },
};
查看ESLINT.md了解React专属规则与自定义配置。

Setup TypeScript

配置TypeScript

Use strict mode in 
tsconfig.json
:
json
{
  "compilerOptions": {
    "target": "ES2022",
    "lib": ["ES2022", "DOM", "DOM.Iterable"],
    "module": "ESNext",
    "skipLibCheck": true,
    "moduleResolution": "bundler",
    "allowImportingTsExtensions": true,
    "resolveJsonModule": true,
    "isolatedModules": true,
    "noEmit": true,
    "jsx": "react-jsx",
    "strict": true,
    "noUncheckedIndexedAccess": true,
    "noImplicitOverride": true,
    "noImplicitReturns": true,
    "noFallthroughCasesInSwitch": true,
    "forceConsistentCasingInFileNames": true,
    "types": ["vite/client"]
  },
  "include": ["src"]
}
See TYPESCRIPT.md for advanced configuration and optimization.
在
tsconfig.json
中启用严格模式：
json
{
  "compilerOptions": {
    "target": "ES2022",
    "lib": ["ES2022", "DOM", "DOM.Iterable"],
    "module": "ESNext",
    "skipLibCheck": true,
    "moduleResolution": "bundler",
    "allowImportingTsExtensions": true,
    "resolveJsonModule": true,
    "isolatedModules": true,
    "noEmit": true,
    "jsx": "react-jsx",
    "strict": true,
    "noUncheckedIndexedAccess": true,
    "noImplicitOverride": true,
    "noImplicitReturns": true,
    "noFallthroughCasesInSwitch": true,
    "forceConsistentCasingInFileNames": true,
    "types": ["vite/client"]
  },
  "include": ["src"]
}
查看TYPESCRIPT.md了解高级配置与优化方案。

Setup Pre-commit Hooks

配置预提交钩子

bash
npx husky init
Update 
.husky/pre-commit
:
bash
#!/usr/bin/env sh
. "$(dirname -- "$0")/_/husky.sh"
npm run lint:ci
Create 
.lintstagedrc.json
:
json
{
  "*.{ts,tsx}": [
    "biome check --write --no-errors-on-unmatched",
    "eslint --ext .ts,.tsx --fix --no-error-on-unmatched"
  ],
  "*.{js,jsx}": [
    "biome check --write --no-errors-on-unmatched",
    "eslint --fix --no-error-on-unmatched"
  ],
  "*.json": ["biome check --write"],
  "package.json": ["prettier --write"]
}
See PRE-COMMIT.md for advanced hook configuration and commit message linting.
bash
npx husky init
更新
.husky/pre-commit
：
bash
#!/usr/bin/env sh
. "$(dirname -- "$0")/_/husky.sh"
npm run lint:ci
创建
.lintstagedrc.json
：
json
{
  "*.{ts,tsx}": [
    "biome check --write --no-errors-on-unmatched",
    "eslint --ext .ts,.tsx --fix --no-error-on-unmatched"
  ],
  "*.{js,jsx}": [
    "biome check --write --no-errors-on-unmatched",
    "eslint --fix --no-error-on-unmatched"
  ],
  "*.json": ["biome check --write"],
  "package.json": ["prettier --write"]
}
查看PRE-COMMIT.md了解高级钩子配置与提交信息校验。

Setup Testing

配置测试

Vitest (
vitest.config.ts
):
typescript
import { defineConfig } from 'vitest/config';
import path from 'path';
export default defineConfig({
  test: {
    globals: true,
    environment: 'jsdom',
    coverage: { provider: 'v8', reporter: ['text', 'html', 'lcov'] },
  },
  resolve: { alias: { '@': path.resolve(__dirname, './src') } },
});
Playwright (
playwright.config.ts
):
typescript
import { defineConfig, devices } from '@playwright/test';
export default defineConfig({
  testDir: './tests',
  fullyParallel: true,
  reporter: 'html',
  use: { baseURL: 'http://localhost:4173', trace: 'on-first-retry' },
  projects: [{ name: 'chromium', use: { ...devices['Desktop Chrome'] } }],
  webServer: {
    command: 'npm run dev',
    url: 'http://localhost:4173',
    timeout: 120000,
  },
});
See TESTING.md for comprehensive test setup, coverage configuration, and E2E best practices.
Vitest（
vitest.config.ts
）：
typescript
import { defineConfig } from 'vitest/config';
import path from 'path';
export default defineConfig({
  test: {
    globals: true,
    environment: 'jsdom',
    coverage: { provider: 'v8', reporter: ['text', 'html', 'lcov'] },
  },
  resolve: { alias: { '@': path.resolve(__dirname, './src') } },
});
Playwright（
playwright.config.ts
）：
typescript
import { defineConfig, devices } from '@playwright/test';
export default defineConfig({
  testDir: './tests',
  fullyParallel: true,
  reporter: 'html',
  use: { baseURL: 'http://localhost:4173', trace: 'on-first-retry' },
  projects: [{ name: 'chromium', use: { ...devices['Desktop Chrome'] } }],
  webServer: {
    command: 'npm run dev',
    url: 'http://localhost:4173',
    timeout: 120000,
  },
});
查看TESTING.md了解全面的测试搭建、覆盖率配置与E2E最佳实践。

Daily Workflow

日常工作流

Copy and track this checklist:
Daily Development:
- [ ] Format during development: npm run format
- [ ] Fix lint issues: npm run lint:fix
- [ ] Run unit tests: npm run test:watch
- [ ] Before committing: npm run lint:ci && npm run type-check && npm run test
- [ ] Run E2E tests: npm run test:e2e
复制并跟踪此检查清单：
Daily Development:
- [ ] Format during development: npm run format
- [ ] Fix lint issues: npm run lint:fix
- [ ] Run unit tests: npm run test:watch
- [ ] Before committing: npm run lint:ci && npm run type-check && npm run test
- [ ] Run E2E tests: npm run test:e2e

Fixing Issues

问题修复

Quick fixes:
bash
npm run format          # Fix formatting
npm run lint:fix        # Fix linting
npm run type-check      # Check types
npm run test            # Run unit tests
npm run test:e2e        # Run E2E tests
Full quality check:
bash
npm run lint && npm run type-check && npm run test
See TROUBLESHOOTING.md for common issues and solutions.
快速修复命令：
bash
npm run format          # 修复格式问题
npm run lint:fix        # 修复Lint问题
npm run type-check      # 检查类型
npm run test            # 运行单元测试
npm run test:e2e        # 运行E2E测试
完整质量检查：
bash
npm run lint && npm run type-check && npm run test
查看TROUBLESHOOTING.md了解常见问题与解决方案。

CI/CD Integration

CI/CD集成

GitHub Actions workflow (
.github/workflows/quality.yml
):
yaml
name: Quality Checks
on: [push, pull_request]
jobs:
  quality:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with: { node-version: '20', cache: 'npm' }
      - run: npm ci
      - run: npm run format:check
      - run: npm run lint:ci
      - run: npm run type-check
      - run: npm run test:coverage
      - run: npx playwright install --with-deps
      - run: npm run test:e2e
        env: { CI: true }
GitHub Actions工作流（
.github/workflows/quality.yml
）：
yaml
name: Quality Checks
on: [push, pull_request]
jobs:
  quality:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with: { node-version: '20', cache: 'npm' }
      - run: npm ci
      - run: npm run format:check
      - run: npm run lint:ci
      - run: npm run type-check
      - run: npm run test:coverage
      - run: npx playwright install --with-deps
      - run: npm run test:e2e
        env: { CI: true }

Quality Standards

质量标准

ALWAYS enforce:
  • No 
    any
    types (use 
    unknown
    with type guards)
  • Strict TypeScript configuration
  • Test coverage > 70%
  • Pre-commit validation
  • E2E testing for critical flows
NEVER:
  • Skip quality gates before committing
  • Commit with TypeScript/lint errors
  • Use 
    any
    type without justification
  • Run Prettier on TS/JS files (use Biome instead)
必须强制执行：
  • 禁止使用
    any
    类型（使用
    unknown
    配合类型守卫）
  • 启用严格TypeScript配置
  • 测试覆盖率>70%
  • 预提交校验
  • 关键流程需进行E2E测试
绝对禁止：
  • 提交前跳过质量门禁
  • 带着TypeScript/Lint错误提交代码
  • 无正当理由使用
    any
    类型
  • 对TS/JS文件使用Prettier（改用Biome）

Reference Files

参考文档

For detailed configuration, see:
  • BIOME.md - Advanced Biome configuration, import organization, rules
  • ESLINT.md - ESLint setup, React rules, customization
  • TYPESCRIPT.md - TypeScript strict mode, advanced options
  • PRE-COMMIT.md - Husky setup, lint-staged, commit hooks
  • TESTING.md - Vitest and Playwright configuration
  • TROUBLESHOOTING.md - Common issues and solutions
如需详细配置，请查看：
  • BIOME.md - Biome高级配置、导入组织与规则
  • ESLINT.md - ESLint搭建、React规则与自定义配置
  • TYPESCRIPT.md - TypeScript严格模式与高级选项
  • PRE-COMMIT.md - Husky搭建、lint-staged与提交钩子
  • TESTING.md - Vitest与Playwright配置
  • TROUBLESHOOTING.md - 常见问题与解决方案

Common Patterns

常用操作示例

Running Tests

运行测试

bash
npm run test              # Unit tests
npm run test:watch        # Watch mode
npm run test:coverage     # Coverage report
npm run test:e2e          # E2E tests
npx playwright show-report # View test report
bash
npm run test              # 单元测试
npm run test:watch        # 监听模式
npm run test:coverage     # 覆盖率报告
npm run test:e2e          # E2E测试
npx playwright show-report # 查看测试报告

Quality Gate Sequence

质量门禁执行顺序

bash
undefined
bash
undefined

During development

开发过程中

npm run format && npm run lint:fix
npm run format && npm run lint:fix

Before commit

提交前

npm run lint:ci && npm run type-check && npm run test
npm run lint:ci && npm run type-check && npm run test

Full check (includes E2E)

完整检查（包含E2E）

npm run lint && npm run type-check && npm run test && npm run test:e2e

Remember: Code quality is not optional. Automated quality gates ensure
consistency and catch errors early.
npm run lint && npm run type-check && npm run test && npm run test:e2e

请记住：代码质量并非可选项。自动化质量门禁可确保代码一致性，并提前发现错误。