code-quality

代码质量

面向常见技术栈的结构化代码审查与质量保障。通过检查清单、代码检查策略和指标，保持代码库健康。

快速开始

执行代码质量检查

1. 运行静态分析： 代码检查工具、类型检查器、格式化工具
2. 按检查清单审查： 查看下方针对特定语言的条目
3. 检查复杂度指标： 圈复杂度 < 25，数据流复杂度 < 25
4. 报告发现： 以结构化格式输出，并注明严重程度和建议

---

代码检查配置

Rust — Clippy 配置

标准 Clippy 配置（在 Cargo.toml 或 .clippy.toml 中）：

[lints.clippy]
cognitive_complexity = "warn"
pedantic = { level = "deny", priority = -1 }
nursery = { level = "deny", priority = -1 }
unwrap_used = "deny"

标准命令：

cargo fmt
cargo clippy --all-targets --all-features -- -D warnings
cargo check
cargo test -- --test-threads=1

需要执行的关键规则：

• 非测试代码中禁止使用 .unwrap()（改用 ? 或 .expect("reason")）
• 所有公开项都必须有 rustdoc（#[warn(missing_docs)]）
• 对返回值需要检查的函数使用 #[must_use]
• 使用 #[allow(...)] 时，始终添加注释说明原因
• 如果无法为 #[allow(...)] 提供充分的说明，就修复问题

TypeScript — ESLint + 严格模式

推荐的 tsconfig.json 严格性设置：

{
  "compilerOptions": {
    "strict": true,
    "noUncheckedIndexedAccess": true,
    "noImplicitReturns": true,
    "noFallthroughCasesInSwitch": true,
    "exactOptionalPropertyTypes": true
  }
}

需要执行的关键规则：

• 禁止使用 any —— 改用 unknown 和类型守卫
• 禁止使用 // @ts-ignore —— 修复类型问题，或使用附有说明的 // @ts-expect-error
• 优先使用 const 而非 let，绝不使用 var
• 使用可辨识联合对状态进行建模
• 导出的函数要显式声明返回类型

Python — Ruff + Mypy

推荐的 pyproject.toml：

[tool.ruff]
target-version = "py312"
line-length = 88

[tool.ruff.lint]
select = ["E", "F", "W", "I", "N", "UP", "ANN", "B", "A", "C4", "DTZ", "ISC", "PIE", "PT", "RET", "SIM", "TCH", "ARG", "PTH", "ERA"]

[tool.mypy]
strict = true
warn_return_any = true
warn_unreachable = true

需要执行的关键规则：

• 所有公开函数和方法都必须有类型提示
• 所有公开类、函数和方法都必须有文档字符串
• 使用 pathlib.Path 而非 os.path
• 使用 uv 作为包管理器
• 禁止裸用 except: —— 始终捕获特定异常

---

代码审查检查清单

通用检查清单（所有语言）

正确性：

• 代码是否实现了其声称的功能？
• 是否处理了边界情况（空集合、null/None、零、负数）？
• 是否妥善处理了错误路径？
• 是否存在差一错误？

清晰度：

• 不看 PR 描述，能否理解代码？
• 变量和函数名称是否清晰且一致？
• 复杂部分是否注释了“为什么”（而不是“是什么”）？
• 在可能的情况下，代码是否能够自我说明？

架构：

• 此更改是否遵循现有模块边界？
• 更改的抽象层级是否恰当？
• 依赖是否合理（是否为了一个函数引入了庞大的库）？

测试：

• 新函数/方法是否有测试覆盖？
• 测试是否覆盖边界情况和错误路径？
• 测试是否易于阅读和维护？

安全性（如发现问题，请标记以便后续进行安全审查）：

• 未硬编码密钥或凭据
• 使用前已验证用户输入
• 不存在 SQL 注入、XSS 或路径遍历漏洞

Rust 专用检查清单

• 已运行 cargo fmt
• cargo clippy 检查通过（pedantic + nursery）
• 测试之外未使用 .unwrap()
• 错误处理使用 ?，并采用恰当的错误类型
• 公开项有 rustdoc 注释
• #[allow(...)] 附有说明性注释
• 新函数有单元测试
• 每个函数的圈复杂度 < 25
• 每个函数的数据流复杂度 < 25

TypeScript/React 专用检查清单

• 不使用 any 类型
• 符合严格模式要求
• 组件有明确的 prop 类型
• Hooks 遵循 Hooks 规则
• 没有不必要的重复渲染（检查 memo/callback 的使用）
• 已考虑新增依赖对打包体积的影响

Django/Python 专用检查清单

• 公开接口有类型提示
• Ruff + mypy 检查通过
• 没有 N+1 查询（使用 select_related/prefetch_related）
• 已审查迁移，且迁移可逆
• 视图中没有业务逻辑（使用服务层）

---

复杂度指标

圈复杂度

衡量代码中的独立路径数量。建议阈值：< 25。

复杂度	风险级别	操作
1-10	低	代码简单、结构良好
11-20	中等	如果复杂度持续上升，请考虑简化
21-24	高	建议重构
25+	违规	合并前必须重构

降低复杂度的方法：

• 为每个分支提取辅助函数
• 使用提前返回 / 守卫子句
• 使用查找表或模式匹配替代复杂条件判断
• 使用策略模式处理依赖不同变体的行为

数据流复杂度

衡量一个函数中有多少变量相互作用。建议阈值：< 25。

降低复杂度的方法：

• 提取接受较少参数的纯函数
• 将相关参数组合到结构体 / 对象中
• 拆分分多个阶段转换数据的函数

测量工具

语言	工具	命令
Rust	cargo clippy (cognitive_complexity)	内置于 clippy 配置中
TypeScript	eslint-plugin-sonarjs	配置 complexity 规则
Python	radon	radon cc <file> -s -a
Python	ruff	规则 C901（mccabe 复杂度）

---

审查输出格式

提交代码审查时：

## Code Review: [PR/File/Module]

**Date:** YYYY-MM-DD

### Summary
[1-2 sentences: overall quality assessment]

### Findings

| # | Severity | File | Line(s) | Finding | Suggestion |
|---|---|---|---|---|---|
| 1 | High | src/app.rs | 45-67 | Cyclomatic complexity 28 (limit: 25) | Extract match arms into helper functions |
| 2 | Medium | src/ui.rs | 120 | Unwrap without context | Use `.expect("reason")` or `?` |

### Positive Observations
[What's well-written — acknowledge good code]

### Metrics
- Linter: [clean / N warnings]
- Tests: [pass / fail]
- Complexity: [within limits / violations noted above]

### Security Notes
[Items to flag for follow-up, if any]

---

集成

• 根据项目的 AGENTS.md/CLAUDE.md 执行策略，可直接运行代码检查工具、格式化工具和类型检查工具，无需事先询问。
• 交叉参考：此工具包的 code-reviewer 技能，用于对特定变更集进行对抗性审查；以及 design-patterns，用于通过改进结构来修复复杂度违规。