---
name: quality-rules
type: review_rule
when: '代码审查, review, 质量检查, 代码质量'
scope:
  - backend
  - frontend
products:
  - '*'
id: ka-review-rule-质量审查规则
asset_kind: review_rule
lifecycle_status: active
owner_mechanism_id: mc-generic-review
authority: supporting
routes:
  - code_change
primary_triggers:
  - 质量审查规则
secondary_triggers: []
negative_triggers: []
priority: P1
specificity: 5
version: 1.1.0
last_reviewed: '2026-06-01'
stages: ["编码与单元测试"]
---

## QUA-01: 生产代码包含 console.log 调试输出
pattern: /console\.log\s*\(/
severity: warning
scope: "!test"
description: 生产代码禁止保留 console.log，应使用正式日志框架并按级别输出

## QUA-02: TypeScript 使用 any 类型
pattern: /:\s*any\b|as\s+any\b|<any>/
severity: info
scope: frontend
description: 禁止使用 any 类型，应定义具体的 TypeScript 接口

## QUA-03: 魔法数字未定义为常量
pattern: /(?:if|while|return)\s*\(.*[^\w>!=]\d{2,}[^\w.]/
severity: info
scope: [backend, frontend]
description: 代码中的数字常量应提取为命名常量，提高可读性和可维护性

## QUA-04: 硬编码的 URL 或 IP 地址
pattern: /https?:\/\/(?:localhost|127\.0\.0\.1|192\.168|10\.\d+\.\d+)\b/
severity: warning
scope: [backend, frontend]
description: 服务地址禁止硬编码，必须使用环境变量或配置文件管理

## QUA-05: catch 块吞掉异常不处理
pattern: /catch\s*\([^)]*\)\s*\{\s*\}/
severity: critical
scope: [backend, frontend]
description: 空的 catch 块会隐藏错误，至少需要记录日志或明确注释忽略原因

## QUA-06: 注释掉的代码块（超过 3 行）
pattern: /^\s*\/\/\s*(?:import|export|const|let|var|function|class|public|private)\b/
severity: info
scope: [backend, frontend]
description: 注释掉的代码应删除，需要时从版本控制中恢复

## QUA-07: System.out.println 替代日志框架
pattern: /System\.out\.print/
severity: warning
scope: backend
description: 禁止使用 System.out.println，必须使用 SLF4J/Log4j 等日志框架

## QUA-08: 空 catch 块中无日志记录
pattern: /catch\s*\([^)]*\)\s*\{[^}]*\}/
severity: warning
scope: [backend, frontend]
description: catch 块中必须至少包含日志记录，不允许静默忽略异常

## QUA-09: 待办/修复占位注释未跟踪
pattern: /(?:T[O]DO|F[I]XME|H[A]CK|X{3})\s*[:\(]/
severity: info
scope: [backend, frontend]
description: 待办/修复占位注释必须关联 issue 编号，禁止无跟踪的技术债标记

## QUA-10: 单元测试缺少断言
pattern: /@Test[\s\S]*?(?:expect|assert|verify|should)/
severity: warning
scope: [backend, frontend]
description: 测试方法必须包含至少一个断言，空测试等于没有测试

## QUA-11: 过深的嵌套层级
pattern: //
severity: info
scope: [backend, frontend]
check: nesting_depth
description: 代码嵌套层级超过 4 层时应重构（卫语句、提前返回、策略模式）

## QUA-12: 未处理可空返回值
pattern: /\.get\(\s*\)\s*\.|\.findFirst\(\s*\)\s*\./
severity: warning
scope: backend
description: Optional/List.get() 返回值必须判空，禁止直接链式调用导致 NPE
