代码质量与规范

// 圈复杂度 ≈ 11，难以维护
function getDiscount(user, order) {
  let discount = 0;
  if (user.level === 'gold') {
    if (order.amount > 1000) {
      discount = 0.2;
    } else if (order.amount > 500) {
      discount = 0.15;
    } else {
      discount = 0.1;
    }
  } else if (user.level === 'silver') {
    if (order.amount > 1000) {
      discount = 0.15;
    } else {
      discount = 0.08;
    }
  } else {
    if (order.amount > 1000) {
      discount = 0.05;
    } else {
      discount = 0;
    }
  }
  return discount;
}

// 圈复杂度 ≈ 3，规则可读、易扩展
const DISCOUNT_RULES = {
  gold: [
    { min: 1000, rate: 0.2 },
    { min: 500, rate: 0.15 },
    { min: 0, rate: 0.1 },
  ],
  silver: [
    { min: 1000, rate: 0.15 },
    { min: 0, rate: 0.08 },
  ],
  normal: [
    { min: 1000, rate: 0.05 },
    { min: 0, rate: 0 },
  ],
};

function getDiscount(user, order) {
  const rules = DISCOUNT_RULES[user.level] ?? DISCOUNT_RULES.normal;
  const matched = rules.find((rule) => order.amount >= rule.min);
  return matched ? matched.rate : 0;
}

{
  "root": true,
  "env": {
    "browser": true,
    "es2022": true,
    "node": true
  },
  "parser": "@typescript-eslint/parser",
  "parserOptions": {
    "ecmaVersion": "latest",
    "sourceType": "module",
    "ecmaFeatures": { "jsx": true },
    "project": "./tsconfig.json"
  },
  "plugins": ["@typescript-eslint", "react", "react-hooks", "import"],
  "extends": [
    "eslint:recommended",
    "plugin:@typescript-eslint/recommended",
    "plugin:react/recommended",
    "plugin:react-hooks/recommended",
    "plugin:import/recommended",
    "plugin:import/typescript",
    "prettier"
  ],
  "settings": {
    "react": { "version": "detect" }
  },
  "rules": {
    "no-console": ["warn", { "allow": ["warn", "error"] }],
    "no-debugger": "error",
    "no-unused-vars": "off",
    "@typescript-eslint/no-unused-vars": [
      "error",
      { "argsIgnorePattern": "^_", "varsIgnorePattern": "^_" }
    ],
    "@typescript-eslint/no-explicit-any": "warn",
    "@typescript-eslint/explicit-function-return-type": "off",
    "complexity": ["warn", 10],
    "max-lines-per-function": ["warn", { "max": 50, "skipComments": true }],
    "max-depth": ["warn", 4],
    "react/react-in-jsx-scope": "off",
    "react-hooks/rules-of-hooks": "error",
    "react-hooks/exhaustive-deps": "warn",
    "import/order": [
      "error",
      {
        "groups": ["builtin", "external", "internal", "parent", "sibling", "index"],
        "newlines-between": "always",
        "alphabetize": { "order": "asc", "caseInsensitive": true }
      }
    ]
  }
}

node_modules
dist
build
coverage
*.min.js
public
next-env.d.ts

// eslint.config.js
import js from '@eslint/js';
import tseslint from 'typescript-eslint';
import react from 'eslint-plugin-react';
import reactHooks from 'eslint-plugin-react-hooks';
import prettier from 'eslint-config-prettier';

export default [
  js.configs.recommended,
  ...tseslint.configs.recommended,
  {
    files: ['**/*.{ts,tsx}'],
    plugins: {
      react,
      'react-hooks': reactHooks,
    },
    languageOptions: {
      parserOptions: {
        ecmaFeatures: { jsx: true },
        project: './tsconfig.json',
      },
    },
    settings: {
      react: { version: 'detect' },
    },
    rules: {
      'no-console': ['warn', { allow: ['warn', 'error'] }],
      '@typescript-eslint/no-explicit-any': 'warn',
      '@typescript-eslint/no-unused-vars': [
        'error',
        { argsIgnorePattern: '^_' },
      ],
      complexity: ['warn', 10],
      'react-hooks/rules-of-hooks': 'error',
      'react-hooks/exhaustive-deps': 'warn',
    },
  },
  {
    ignores: ['dist/**', 'build/**', 'coverage/**', '**/*.min.js'],
  },
  prettier,
];

// ❌ ESLint 会警告：缺少依赖 userId，导致闭包捕获旧值
function UserProfile({ userId }) {
  const [data, setData] = useState(null);
  useEffect(() => {
    fetchUser(userId).then(setData);
  }, []); // 依赖数组为空，userId 变化时不会重新请求
  return <div>{data?.name}</div>;
}

// ✅ 补全依赖后，userId 变化会正确触发重新请求
function UserProfile({ userId }) {
  const [data, setData] = useState(null);
  useEffect(() => {
    fetchUser(userId).then(setData);
  }, [userId]);
  return <div>{data?.name}</div>;
}

{
  "printWidth": 100,
  "tabWidth": 2,
  "useTabs": false,
  "semi": true,
  "singleQuote": true,
  "quoteProps": "as-needed",
  "jsxSingleQuote": false,
  "trailingComma": "all",
  "bracketSpacing": true,
  "arrowParens": "always",
  "endOfLine": "lf"
}

// stylelint.config.js
export default {
  extends: [
    'stylelint-config-standard',
    'stylelint-config-standard-scss',
    'stylelint-config-recess-order',
  ],
  plugins: ['stylelint-order'],
  rules: {
    'color-hex-length': 'short',
    'color-no-invalid-hex': true,
    'declaration-block-no-duplicate-properties': true,
    'no-duplicate-selectors': true,
    'selector-max-id': 0,
    'selector-class-pattern': '^[a-z][a-zA-Z0-9]+$',
    'unit-allowed-list': ['px', 'rem', 'em', '%', 'vh', 'vw', 's', 'ms', 'deg', 'fr'],
    'max-nesting-depth': 3,
  },
};

/* ❌ 无效颜色、重复属性、过深嵌套 */
.card {
  color: #ff;
  color: red;
  .header .title .icon .badge { font-size: 12px; }
}

/* ✅ 合法颜色、无重复、扁平结构 */
.card {
  color: #f00;
}
.card__badge {
  font-size: 12px;
}

// commitlint.config.js
export default {
  extends: ['@commitlint/config-conventional'],
  rules: {
    'type-enum': [
      2,
      'always',
      ['feat', 'fix', 'docs', 'style', 'refactor', 'perf', 'test', 'build', 'ci', 'chore', 'revert'],
    ],
    'subject-max-length': [2, 'always', 72],
    'subject-empty': [2, 'never'],
    'type-empty': [2, 'never'],
  },
};

❌ 不规范
  update
  fix bug
  改了点东西
  修复登录问题以及顺便调整了首页样式还加了个埋点

✅ 规范
  feat(auth): 支持手机号验证码登录
  fix(cart): 修复优惠券叠加计算错误
  perf(list): 虚拟滚动优化长列表首屏渲染

{
  "compilerOptions": {
    "target": "ES2022",
    "module": "ESNext",
    "strict": true,
    "noImplicitAny": true,
    "strictNullChecks": true,
    "strictFunctionTypes": true,
    "noUnusedLocals": true,
    "noUnusedParameters": true,
    "noImplicitReturns": true,
    "noFallthroughCasesInSwitch": true,
    "noUncheckedIndexedAccess": true,
    "exactOptionalPropertyTypes": true,
    "forceConsistentCasingInFileNames": true,
    "skipLibCheck": true
  }
}

interface User {
  id: string;
  profile?: { avatar: string };
}

function getAvatar(user: User): string {
  // ❌ 未开启严格模式时能编译，运行时可能抛 "Cannot read properties of undefined"
  // return user.profile.avatar;

  // ✅ 严格模式强制处理可空分支
  return user.profile?.avatar ?? '/default-avatar.png';
}

// 请求状态用联合类型精确建模，避免 isLoading + error 同时为真的非法组合
type RequestState<T> =
  | { status: 'idle' }
  | { status: 'loading' }
  | { status: 'success'; data: T }
  | { status: 'error'; message: string };

function render(state: RequestState<string[]>): string {
  switch (state.status) {
    case 'idle':
      return '等待中';
    case 'loading':
      return '加载中...';
    case 'success':
      return state.data.join(', '); // 此分支才能访问 data，类型安全
    case 'error':
      return state.message;
  }
}

# .editorconfig
root = true

[*]
charset = utf-8
end_of_line = lf
insert_final_newline = true
trim_trailing_whitespace = true
indent_style = space
indent_size = 2

[*.md]
trim_trailing_whitespace = false

[Makefile]
indent_style = tab

npm install -D husky lint-staged @commitlint/cli @commitlint/config-conventional
npx husky init

# .husky/pre-commit
npx lint-staged

# .husky/commit-msg
npx --no-install commitlint --edit "${1}"

{
  "lint-staged": {
    "*.{js,jsx,ts,tsx}": [
      "eslint --fix",
      "prettier --write"
    ],
    "*.{css,scss,less}": [
      "stylelint --fix",
      "prettier --write"
    ],
    "*.{json,md,yml,yaml}": [
      "prettier --write"
    ]
  }
}

{
  "scripts": {
    "lint": "eslint . --ext .js,.jsx,.ts,.tsx",
    "lint:fix": "eslint . --ext .js,.jsx,.ts,.tsx --fix",
    "lint:style": "stylelint \"src/**/*.{css,scss}\"",
    "format": "prettier --write \"src/**/*.{js,jsx,ts,tsx,css,scss,json,md}\"",
    "format:check": "prettier --check \"src/**/*.{js,jsx,ts,tsx,css,scss,json,md}\"",
    "typecheck": "tsc --noEmit",
    "test": "jest --coverage",
    "quality": "npm run typecheck && npm run lint && npm run format:check && npm run test",
    "prepare": "husky"
  }
}

# sonar-project.properties
sonar.projectKey=my-frontend-app
sonar.projectName=My Frontend App
sonar.sources=src
sonar.tests=src
sonar.test.inclusions=**/*.test.ts,**/*.test.tsx,**/*.spec.ts
sonar.exclusions=**/node_modules/**,**/dist/**,**/*.d.ts
sonar.javascript.lcov.reportPaths=coverage/lcov.info
sonar.typescript.tsconfigPath=tsconfig.json
sonar.qualitygate.wait=true

// ❌ 含义不明的命名
const d = new Date();
const list = users.filter((u) => u.a > 18);
function calc(x, y) { return x * 0.9 + y; }

// ✅ 语义化命名，代码即文档
const currentDate = new Date();
const adultUsers = users.filter((user) => user.age > 18);
function calcPriceWithDiscount(basePrice, shippingFee) {
  return basePrice * 0.9 + shippingFee;
}

// ❌ 一个函数承担了太多职责
function processOrder(order) {
  if (!order.items || order.items.length === 0) {
    console.log('订单为空');
    return null;
  }
  let total = 0;
  for (const item of order.items) {
    total += item.price * item.quantity;
  }
  if (total > 1000) total *= 0.9;
  const formatted = '¥' + total.toFixed(2);
  saveToDatabase(order, total);
  sendEmail(order.userEmail, formatted);
  return formatted;
}

// ✅ 职责拆分，纯函数与副作用分离
function validateOrder(order) {
  return Array.isArray(order.items) && order.items.length > 0;
}

function calcTotal(items) {
  return items.reduce((sum, item) => sum + item.price * item.quantity, 0);
}

function applyBulkDiscount(total) {
  return total > 1000 ? total * 0.9 : total;
}

function formatPrice(amount) {
  return `¥${amount.toFixed(2)}`;
}

async function processOrder(order) {
  if (!validateOrder(order)) {
    throw new EmptyOrderError('订单不能为空');
  }
  const total = applyBulkDiscount(calcTotal(order.items));
  await saveToDatabase(order, total);
  await sendEmail(order.userEmail, formatPrice(total));
  return formatPrice(total);
}

// ❌ 静默吞掉错误，问题被隐藏，排查无从下手
async function loadConfig() {
  try {
    return await fetch('/api/config').then((r) => r.json());
  } catch (e) {
    return {}; // 出错了却当作正常，返回空对象
  }
}

// ✅ 分类处理、保留上下文、向上传播
class ConfigLoadError extends Error {
  constructor(message, cause) {
    super(message);
    this.name = 'ConfigLoadError';
    this.cause = cause;
  }
}

async function loadConfig() {
  try {
    const res = await fetch('/api/config');
    if (!res.ok) {
      throw new ConfigLoadError(`配置接口返回 ${res.status}`);
    }
    return await res.json();
  } catch (err) {
    // 记录日志并上报监控，再抛出让调用方决定降级策略
    logger.error('加载配置失败', err);
    throw new ConfigLoadError('无法加载应用配置', err);
  }
}

开发者提交代码 → 创建 Pull Request
      ↓
CI 自动检查（lint / typecheck / test / SonarQube 门禁）
      ↓
自动检查通过 → 指派 Reviewer 人工审查
      ↓
Reviewer 评论 / 提问 → 开发者回应或修改
      ↓
审查通过（Approve）→ 合并（Squash / Merge）→ 触发部署

# .github/workflows/quality.yml
name: Code Quality

on:
  pull_request:
    branches: [main, develop]
  push:
    branches: [main]

jobs:
  quality:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout
        uses: actions/checkout@v4
        with:
          fetch-depth: 0

      - name: Setup Node
        uses: actions/setup-node@v4
        with:
          node-version: 20
          cache: npm

      - name: Install dependencies
        run: npm ci

      - name: Type check
        run: npm run typecheck

      - name: Lint
        run: npm run lint

      - name: Format check
        run: npm run format:check

      - name: Test with coverage
        run: npm run test -- --coverage

      - name: Upload coverage
        uses: actions/upload-artifact@v4
        with:
          name: coverage-report
          path: coverage/

      - name: SonarQube Scan
        uses: sonarsource/sonarqube-scan-action@v3
        env:
          SONAR_TOKEN: ${{ secrets.SONAR_TOKEN }}
          SONAR_HOST_URL: ${{ secrets.SONAR_HOST_URL }}