code-review

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Code Review Workflow

代码审查工作流

Systematic validation of code against all guardrails before committing. Supports both automated checking and interactive review modes.

在提交前对代码进行全面的规范校验。支持自动检查和交互式审查两种模式。

When to Use

适用场景

Trigger	Mode	Description
Pre-Commit	Automated	Before any commit
PR Review	Interactive	During pull request review
Feature Complete	Both	After FEATURE/COMPLEX mode completion
Code Handoff	Interactive	Before transferring ownership
Quality Gate	Automated	CI/CD pipeline integration

触发时机	模式	描述
提交前（Pre-Commit）	自动模式	任何代码提交之前
拉取请求审查（PR Review）	交互式模式	拉取请求审查过程中
功能开发完成	两种模式均支持	完成FEATURE/COMPLEX模式开发后
代码移交	交互式模式	代码所有权转移之前
质量门禁	自动模式	CI/CD流水线集成环节

Review Modes

审查模式

Automated Mode

自动模式

Quick validation against all guardrails. Returns pass/fail/warning status.

Best for: Pre-commit checks, CI/CD integration, quick validation.

快速完成所有规范校验，返回通过/失败/警告状态。

最佳适用场景：提交前检查、CI/CD集成、快速验证。

Interactive Mode

交互式模式

Guided review with questions and confirmations. Deeper analysis.

Best for: PR reviews, complex changes, code handoffs.

通过引导式的问题与确认进行深度审查，分析更全面。

最佳适用场景：拉取请求审查、复杂变更、代码移交。

Prerequisites

前置条件

Before starting review:

Code is in a reviewable state (compiles, runs)
All files to review are identified
Access to test results (if available)
Access to coverage reports (if available)

开始审查前需确认：

代码处于可审查状态（可编译、可运行）
已明确所有需要审查的文件
可访问测试结果（若有）
可访问覆盖率报告（若有）

Review Process

审查流程

Phase 1: Code Quality Guardrails
    ↓
Phase 2: Security Guardrails
    ↓
Phase 3: Testing Guardrails
    ↓
Phase 4: Git Hygiene
    ↓
Phase 5: Report Generation

第一阶段：代码质量规范校验
    ↓
第二阶段：安全规范校验
    ↓
第三阶段：测试规范校验
    ↓
第四阶段：Git规范检查
    ↓
第五阶段：报告生成

Phase 1: Code Quality Guardrails

第一阶段：代码质量规范校验

1.1 Function Length Check

1.1 函数长度检查

Guardrail: No function exceeds 50 lines

Check: Count lines in each function/method
Pass: All functions ≤ 50 lines
Warn: Functions 40-50 lines (approaching limit)
Fail: Any function > 50 lines

If Failed:

Identify functions exceeding limit
Suggest extraction points for helper functions
Recommend refactoring approach

校验规则：函数长度不得超过50行

检查：统计每个函数/方法的行数
通过：所有函数行数≤50行
警告：函数行数在40-50行（接近限制）
失败：存在函数行数>50行

若失败：

找出超出长度限制的函数
建议提取辅助函数的拆分点
推荐重构方案

1.2 File Length Check

1.2 文件长度检查

Guardrail: No file exceeds 300 lines (components: 200, tests: 300, utils: 150)

Check: Count lines in each file
Pass: Files within limits
Warn: Files at 80%+ of limit
Fail: Files exceeding limits

File Type Limits:

Type	Limit	80% Warning
Components	200	160
Tests	300	240
Utilities	150	120
Other	300	240

校验规则：文件长度不得超过300行（组件文件：200行，测试文件：300行，工具类文件：150行）

检查：统计每个文件的行数
通过：所有文件符合行数限制
警告：文件行数达到限制的80%及以上
失败：文件行数超出限制

不同类型文件的行数限制：

文件类型	行数限制	警告阈值（80%）
组件文件	200	160
测试文件	300	240
工具类文件	150	120
其他文件	300	240

1.3 Cyclomatic Complexity

1.3 圈复杂度

Guardrail: Complexity ≤ 10 per function

Check: Analyze control flow (if, for, while, switch, &&, ||)
Pass: All functions ≤ 10
Warn: Functions 8-10
Fail: Any function > 10

Complexity Calculation:

Start with 1
+1 for each: if, elif, for, while, case, catch, &&, ||, ?:

校验规则：每个函数的圈复杂度≤10

检查：分析控制流（if、for、while、switch、&&、||等）
通过：所有函数的圈复杂度≤10
警告：函数圈复杂度在8-10之间
失败：存在函数圈复杂度>10

复杂度计算方式：

初始值为1
每出现以下语句加1：if、elif、for、while、case、catch、&&、||、?:

1.4 Type Signatures

1.4 类型签名

Guardrail: All exported functions have type signatures

Check: Verify exported functions have types
Pass: All exports typed
Warn: Internal functions missing types
Fail: Exported functions missing types

校验规则：所有导出函数必须包含类型签名

检查：验证导出函数是否带有类型定义
通过：所有导出函数均有类型定义
警告：内部函数缺少类型定义
失败：导出函数缺少类型定义

1.5 Documentation

1.5 文档注释

Guardrail: All exported functions have documentation

Check: Verify docstrings/JSDoc on exports
Pass: All exports documented
Warn: Documentation exists but incomplete
Fail: Exported functions undocumented

校验规则：所有导出函数必须包含文档注释

检查：验证导出函数是否带有文档字符串/JSDoc
通过：所有导出函数均有文档注释
警告：存在文档注释但内容不完整
失败：导出函数未添加文档注释

1.6 Code Hygiene

1.6 代码整洁度

Guardrails:

No magic numbers (use named constants)
No commented-out code
No TODO without issue reference
No dead code (unused imports, variables, functions)

Check: Scan for violations
Pass: None found
Warn: Minor violations (1-2 magic numbers)
Fail: Multiple violations

校验规则：

禁止使用魔法数字（需使用命名常量替代）
禁止存在注释掉的代码
禁止无问题引用的TODO注释
禁止存在死代码（未使用的导入、变量、函数）

检查：扫描是否存在违反规则的情况
通过：未发现任何违规
警告：存在轻微违规（1-2个魔法数字）
失败：存在多处违规

Phase 2: Security Guardrails

第二阶段：安全规范校验

2.1 Input Validation

2.1 输入验证

Guardrail: All user inputs validated before processing

Check: Identify input sources (API params, form data, URL params)
Pass: All inputs validated with schema or type checks
Warn: Validation exists but not comprehensive
Fail: Raw user input used directly

Input Sources to Check:

Request body/params
Query strings
Headers
File uploads
Environment variables from user

校验规则：所有用户输入在处理前必须经过验证

检查：识别输入来源（API参数、表单数据、URL参数等）
通过：所有输入均通过 schema 或类型检查进行验证
警告：存在验证逻辑但不够全面
失败：直接使用未处理的原始用户输入

需要检查的输入来源：

请求体/参数
查询字符串
请求头
文件上传
用户提供的环境变量

2.2 Database Queries

2.2 数据库查询

Guardrail: All queries use parameterized statements

Check: Scan for SQL/query construction
Pass: All queries parameterized
Fail: String concatenation in queries

Red Flags:

javascript

// FAIL: String concatenation
`SELECT * FROM users WHERE id = ${id}`

// PASS: Parameterized
db.query('SELECT * FROM users WHERE id = $1', [id])

校验规则：所有查询必须使用参数化语句

检查：扫描SQL/查询语句的构建方式
通过：所有查询均使用参数化语句
失败：存在通过字符串拼接构建查询的情况

危险示例与正确示例：

javascript

// 失败：使用字符串拼接
`SELECT * FROM users WHERE id = ${id}`

// 通过：使用参数化语句
db.query('SELECT * FROM users WHERE id = $1', [id])

2.3 Secrets Detection

2.3 敏感信息检测

Guardrail: No secrets in code

Check: Scan for secret patterns
Pass: No secrets detected
Fail: Hardcoded secrets found

Patterns to Detect:

API keys (
```
sk_live_
```
,
```
pk_live_
```
,
```
api_key=
```
)
Passwords (
```
password=
```
,
```
passwd=
```
)
Tokens (
```
token=
```
,
```
bearer
```
)
Connection strings with credentials
Private keys (
```
-----BEGIN RSA PRIVATE KEY-----
```
)

校验规则：代码中不得包含敏感信息

检查：扫描是否存在敏感信息的特征模式
通过：未检测到敏感信息
失败：发现硬编码的敏感信息

需要检测的敏感信息模式：

API密钥（
```
sk_live_
```
、
```
pk_live_
```
、
```
api_key=
```
）
密码（
```
password=
```
、
```
passwd=
```
）
令牌（
```
token=
```
、
```
bearer
```
）
包含凭证的连接字符串
私钥（
```
-----BEGIN RSA PRIVATE KEY-----
```
）

2.4 File Path Validation

2.4 文件路径验证

Guardrail: All file operations validate paths

Check: Identify file operations
Pass: Path validation/sanitization present
Fail: Direct user input in file paths

Red Flags:

javascript

// FAIL: Directory traversal possible
fs.readFile(userInput)

// PASS: Validated
const safePath = path.join(baseDir, path.basename(userInput))

校验规则：所有文件操作必须验证路径的合法性

检查：识别文件操作逻辑
通过：存在路径验证/清理逻辑
失败：直接使用用户输入作为文件路径

危险示例与正确示例：

javascript

// 失败：存在目录遍历风险
fs.readFile(userInput)

// 通过：已进行路径验证
const safePath = path.join(baseDir, path.basename(userInput))

2.5 Async Operations

2.5 异步操作处理

Guardrail: All async operations have timeout/cancellation

Check: Identify async calls (fetch, DB queries, external APIs)
Pass: Timeouts configured
Warn: Some operations without timeout
Fail: No timeout handling

校验规则：所有异步操作必须设置超时/取消机制

检查：识别异步调用（fetch、数据库查询、外部API调用等）
通过：已配置超时机制
警告：部分异步操作未设置超时
失败：未处理超时逻辑

Phase 3: Testing Guardrails

第三阶段：测试规范校验

3.1 Coverage Thresholds

3.1 覆盖率阈值

Guardrail: >80% business logic, >60% overall

Check: Review coverage report
Pass: Meets thresholds
Warn: 70-80% business / 50-60% overall
Fail: Below thresholds

校验规则：业务逻辑覆盖率>80%，整体覆盖率>60%

检查：查看覆盖率报告
通过：达到覆盖率阈值
警告：业务逻辑覆盖率70-80% / 整体覆盖率50-60%
失败：未达到覆盖率阈值

3.2 Test Existence

3.2 测试用例存在性

Guardrail: All public APIs have unit tests

Check: Map public functions to test files
Pass: All public APIs tested
Warn: Most tested (>80%)
Fail: Significant gaps (<80%)

校验规则：所有公开API必须包含单元测试

检查：映射公开函数与对应测试文件
通过：所有公开API均有测试用例
警告：大部分公开API已测试（>80%）
失败：存在大量测试缺口（<80%）

3.3 Regression Tests

3.3 回归测试

Guardrail: Bug fixes include regression tests

Check: If fix, verify test added
Pass: Regression test present
Fail: No regression test for bug fix

校验规则：Bug修复必须包含回归测试用例

检查：若为Bug修复，确认是否添加了测试用例
通过：已添加回归测试用例
失败：Bug修复未添加回归测试用例

3.4 Edge Cases

3.4 边界场景测试

Guardrail: Edge cases explicitly tested

Check: Review test cases for boundaries
Pass: Null, empty, boundary values tested
Warn: Some edge cases missing
Fail: No edge case testing

Required Edge Cases:

Null/undefined inputs
Empty strings/arrays
Boundary values (0, -1, MAX_INT)
Invalid types
Concurrent access (if applicable)

校验规则：必须明确测试边界场景

检查：查看测试用例是否覆盖边界情况
通过：已测试空值、空内容、边界值等场景
警告：部分边界场景未覆盖
失败：未进行边界场景测试

必须覆盖的边界场景：

Null/undefined输入
空字符串/空数组
边界值（0、-1、MAX_INT）
无效类型
并发访问（若适用）

3.5 Test Independence

3.5 测试独立性

Guardrail: No test interdependencies

Check: Tests can run in any order
Pass: Tests isolated
Fail: Tests depend on execution order

校验规则：测试用例之间不得存在依赖关系

检查：测试用例可按任意顺序执行
通过：测试用例相互独立
失败：测试用例依赖执行顺序

Phase 4: Git Hygiene

第四阶段：Git规范检查

4.1 Commit Message Format

4.1 提交信息格式

Guardrail:

type(scope): description

(conventional commits)

Check: Verify commit message format
Pass: Follows convention
Fail: Non-conventional format

Valid Types: feat, fix, docs, refactor, test, chore, perf, ci

校验规则：遵循

type(scope): description

格式（约定式提交规范）

检查：验证提交信息格式
通过：符合约定式提交规范
失败：未使用约定式提交格式

合法的提交类型：feat、fix、docs、refactor、test、chore、perf、ci

4.2 Atomic Commits

4.2 原子提交

Guardrail: One logical change per commit

Check: Review commit scope
Pass: Single logical change
Warn: Related changes (acceptable)
Fail: Unrelated changes bundled

校验规则：每个提交仅包含一个逻辑变更

检查：审查提交的范围
通过：仅包含单个逻辑变更
警告：包含相关变更（可接受）
失败：包含不相关的变更内容

4.3 Sensitive Data

4.3 敏感数据检查

Guardrail: No sensitive data in commits

Check: Scan staged files
Pass: No sensitive data
Fail: Secrets, credentials, or PII found

校验规则：提交内容中不得包含敏感数据

检查：扫描暂存文件
通过：未发现敏感数据
失败：提交内容中包含密钥、凭证或个人身份信息（PII）

Phase 5: Report Generation

第五阶段：报告生成

5.1 Automated Report Format

5.1 自动模式报告格式

markdown

undefined

markdown

undefined

Code Review Report

代码审查报告

Date: 2025-01-15 Files Reviewed: 12 Status: ⚠️ WARNINGS (3 issues)

日期：2025-01-15 审查文件数：12 状态：⚠️ 警告（3个问题）

Summary

摘要

Category	Status	Issues
Code Quality	✅ Pass	0
Security	⚠️ Warn	2
Testing	✅ Pass	0
Git Hygiene	⚠️ Warn	1

分类	状态	问题数
代码质量	✅ 通过	0
安全性	⚠️ 警告	2
测试	✅ 通过	0
Git规范	⚠️ 警告	1

Issues Found

发现的问题

Security Warnings

安全警告

Missing timeout in
```
src/api/fetch.ts:42
```
- External API call without timeout
- Recommendation: Add 30s timeout
Input validation in
```
src/routes/users.ts:15
```
- Query parameter used without validation
- Recommendation: Add Zod schema

缺少超时机制 -
```
src/api/fetch.ts:42
```
- 外部API调用未设置超时
- 建议：添加30秒超时限制
输入验证缺失 -
```
src/routes/users.ts:15
```
- 查询参数未经过验证直接使用
- 建议：添加Zod schema验证

Git Hygiene Warnings

Git规范警告

Large commit scope
- 8 files changed across 3 features
- Recommendation: Split into separate commits

提交范围过大
- 一次提交修改了8个文件，涉及3个功能
- 建议：拆分为多个独立提交

Passed Checks

通过的检查项

✅ All functions ≤ 50 lines
✅ All files within size limits
✅ No secrets detected
✅ Coverage at 82%
✅ Commit message format correct

undefined

✅ 所有函数行数≤50行
✅ 所有文件符合行数限制
✅ 未检测到敏感信息
✅ 测试覆盖率达82%
✅ 提交信息格式符合规范

undefined

5.2 Interactive Report Format

5.2 交互式模式报告格式

Interactive mode includes prompts:

markdown

undefined

交互式模式包含引导式提问：

markdown

undefined

Interactive Review: src/api/users.ts

交互式审查：src/api/users.ts

Function: createUser (lines 15-45)

函数：createUser（第15-45行）

Observations:

30 lines (within limit)
Complexity: 6 (acceptable)
Missing error handling for database failure

Questions:

Should we add explicit error handling for DB failures?
Should the validation schema be extracted to a separate file?

Your Response: [awaiting input]


---

---

观察结果：

函数长度30行（符合限制）
圈复杂度：6（符合要求）
缺少数据库失败的错误处理逻辑

问题：

是否需要为数据库失败添加明确的错误处理？
是否应将验证schema提取到单独文件中？

你的回复：[等待输入]


---

---

Integration with CI/CD

与CI/CD集成

GitHub Actions Example

GitHub Actions 示例

yaml

undefined

yaml

undefined

.github/workflows/code-review.yml

name: Code Review Checks

on: [pull_request]

jobs: review: runs-on: ubuntu-latest steps: - uses: actions/checkout@v4

  - name: Function Length Check
    run: |
      # Check no function > 50 lines
      # Implementation depends on language

  - name: Security Scan
    run: |
      # Run secret detection
      # Run input validation check

  - name: Coverage Check
    run: |
      npm test -- --coverage
      # Verify thresholds

---

name: Code Review Checks

on: [pull_request]

jobs: review: runs-on: ubuntu-latest steps: - uses: actions/checkout@v4

  - name: Function Length Check
    run: |
      # Check no function > 50 lines
      # Implementation depends on language

  - name: Security Scan
    run: |
      # Run secret detection
      # Run input validation check

  - name: Coverage Check
    run: |
      npm test -- --coverage
      # Verify thresholds

---