代码审查标准Skill code-review-standards

---

name: code-review-standards description: 代码审查框架与标准。引用security-sentinel进行安全检查。在执行代码审查或定义审查标准时使用。 allowed-tools: Read, Grep

代码审查标准

何时使用

• 审查拉取请求
• 执行代码审查
• 定义审查标准
• 建立审查流程

概述

代码审查标准确保一致、彻底的审查，在代码进入生产环境前捕获错误。本技能聚合了来自专业技能的审查标准。

审查框架

4级严重程度分类

1. 严重 🔴 - 合并前必须修复

   • 安全漏洞
   • 数据丢失风险
   • 身份验证绕过
   • SQL注入风险

2. 高 🟠 - 合并前应该修复

   • TypeScript严格模式违规
   • 缺少错误处理
   • 性能问题（N+1查询）
   • 缺少输入验证

3. 中 🟡 - 尽快修复（可合并但需有计划）

   • 代码质量问题
   • 缺少测试
   • 命名不当
   • 缺少文档

4. 低 🟢 - 建议改进

   • 风格建议
   • 优化机会
   • 重构想法

---

审查清单

1. 正确性

→ 参见：correctness-criteria.md

• [ ] 逻辑对所有测试用例都正确
• [ ] 处理边界情况（null、空值、最大值、最小值）
• [ ] 正确处理错误条件
• [ ] 返回类型匹配函数签名
• [ ] 异步操作正确等待
• [ ] 无竞态条件
• [ ] 无差一错误

---

2. 安全性

→ 参见：security-sentinel技能 → 参见：security-checklist.md

严重 - 每次审查必须检查：

• [ ] 无硬编码密钥
• [ ] 使用Zod进行输入验证（所有输入）
• [ ] 受保护路由检查身份验证
• [ ] 强制执行授权（资源所有权）
• [ ] 防止SQL注入（使用Drizzle）
• [ ] 防止XSS（无未经净化的dangerouslySetInnerHTML）
• [ ] 状态变更操作有CSRF保护
• [ ] 日志中无敏感数据
• [ ] 密码哈希（bcrypt，12+轮）
• [ ] JWT正确验证

完整安全标准： → security-sentinel/SKILL.md

---

3. TypeScript质量

→ 参见：typescript-strict-guard技能

• [ ] 无any类型
• [ ] 无无详细注释的@ts-ignore
• [ ] 无无注释的!非空断言
• [ ] 所有函数参数都有显式类型
• [ ] 所有函数都有显式返回类型
• [ ] 对未知类型使用类型守卫
• [ ] 正确使用泛型
• [ ] 无隐式any

---

4. 测试

→ 参见：quality-gates/test-patterns.md

• [ ] 新代码有测试
• [ ] 测试遵循AAA模式
• [ ] 覆盖率满足阈值（75%/90%）
• [ ] UI测试验证DOM状态（不仅仅是模拟）
• [ ] 视觉变化有E2E测试
• [ ] 无无理由跳过的测试
• [ ] 测试独立
• [ ] 测试后清理

---

5. 性能

→ 参见：performance-criteria.md

• [ ] 无N+1查询问题
• [ ] 数据库查询优化
• [ ] 异步操作尽可能并行化
• [ ] 大数据集分页
• [ ] 图片优化
• [ ] 无不必要的重新渲染
• [ ] 昂贵计算已记忆化

---

6. 代码质量

→ 参见：maintainability-rules.md

• [ ] 生产代码中无console.log
• [ ] 无注释掉的代码
• [ ] 无无GitHub问题的TODO
• [ ] 函数具有单一职责
• [ ] 变量名具有描述性
• [ ] 无死代码
• [ ] 无重复逻辑
• [ ] 正确的错误消息

---

7. 架构合规性

→ 参见：architecture-patterns技能

• [ ] 为问题选择了正确的模式
• [ ] 模式正确实现
• [ ] 无模式违规
• [ ] 遵循Next.js最佳实践
• [ ] 服务器与客户端组件正确
• [ ] 状态管理适当

---

审查流程

步骤1：预审查（2分钟）

1. 阅读PR描述
2. 理解更改内容和原因
3. 检查CI/CD状态（测试、构建、覆盖率）
4. 识别高风险区域（身份验证、支付、数据处理）

步骤2：安全审查（5分钟）

对所有PR：

• 检查硬编码密钥
• 验证输入验证
• 检查身份验证/授权

对身份验证/API/数据PR：

• 运行security-sentinel技能
• 审查OWASP Top 10标准
• 检查注入风险

→ security-checklist.md

步骤3：代码审查（10-20分钟）

1. 正确性：是否按预期工作？
2. TypeScript：严格模式合规性？
3. 测试：覆盖率和质量是否足够？
4. 性能：有无明显问题？
5. 质量：代码是否可读、可维护？
6. 架构：是否遵循既定模式？

步骤4：撰写反馈（5分钟）

使用严重程度级别和模板： → review-templates.md

格式：

## 🔴 严重问题

- [ ] [安全] auth.ts:45中的硬编码API密钥
  - **风险**：API密钥在版本控制中暴露
  - **修复**：移至环境变量
  - **文件**：src/lib/auth.ts:45

## 🟠 高优先级问题

- [ ] [TypeScript] processData()中使用`any`类型
  - **问题**：无类型安全
  - **修复**：定义显式接口
  - **文件**：src/utils/process.ts:12

## 🟡 中优先级问题

- [ ] [测试] 缺少错误用例测试
  - **覆盖率**：仅测试了正常路径
  - **需要**：测试null输入、无效格式
  - **文件**：tests/unit/process.test.ts

## 🟢 低优先级问题 / 建议

- 考虑提取辅助函数以提高可读性

步骤5：裁决

选择一项：

• ✅ 批准 - 无严重/高优先级问题
• 🔄 请求更改 - 存在严重或多个高优先级问题
• 💬 评论 - 仅存在问题或中/低优先级问题

---

审查模板

安全问题模板

🔴 **[安全] [漏洞类型]**

**位置**：`src/path/file.ts:123`

**问题**：[漏洞描述]

**风险**：[可能出错的情况]

**修复**：
```typescript
// 建议的修复

参考：[OWASP链接或技能参考]

### TypeScript问题模板

```markdown
🟠 **[TypeScript] [问题类型]**

**位置**：`src/path/file.ts:45`

**问题**：[错误描述]

**修复**：
```typescript
// 当前（不良）
function process(data: any) { }

// 建议（良好）
function process(data: ProcessData): ProcessedResult { }

参考：typescript-strict-guard技能

### 性能问题模板

```markdown
🟡 **[性能] [问题类型]**

**位置**：`src/path/file.ts:78`

**问题**：getUserProjects()中的N+1查询问题

**影响**：线性时间复杂度，大数据集下速度慢

**修复**：
```typescript
// 使用连接而不是单独查询
const projects = await db
  .select()
  .from(projectsTable)
  .leftJoin(usersTable, eq(projectsTable.userId, usersTable.id))

---

## 常见审查模式

### 代码异味

**长函数**
```typescript
// 🔴 不良：100+行函数
function processEverything() {
  // ... 100行
}

// ✅ 良好：提取辅助函数
function processEverything() {
  const validated = validateInput()
  const processed = processData(validated)
  const saved = saveToDatabase(processed)
  return saved
}

深度嵌套逻辑

// 🔴 不良：4+层嵌套
if (user) {
  if (user.projects) {
    if (user.projects.length > 0) {
      if (user.projects[0].status === 'active') {
        // ...
      }
    }
  }
}

// ✅ 良好：提前返回
if (!user) return
if (!user.projects || user.projects.length === 0) return
if (user.projects[0].status !== 'active') return
// ...

魔法数字

// 🔴 不良：未解释的数字
setTimeout(callback, 3600000)

// ✅ 良好：命名常量
const ONE_HOUR_MS = 60 * 60 * 1000
setTimeout(callback, ONE_HOUR_MS)

---

渐进式披露

1. SKILL.md（本文件）- 审查框架概述
2. security-checklist.md - OWASP Top 10清单
3. performance-criteria.md - 性能审查标准
4. maintainability-rules.md - 代码质量规则
5. review-templates.md - 反馈模板

---

与其他技能的集成

代码审查聚合了以下技能的标准：

• security-sentinel - 安全漏洞检查
• typescript-strict-guard - 类型安全验证
• quality-gates - 质量检查点框架
• architecture-patterns - 模式合规性
• nextjs-15-specialist - Next.js最佳实践

---

审查示例

# 代码审查：添加用户身份验证

## 摘要
添加基于JWT的身份验证，包含登录/注销端点。

## 🔴 严重问题

### 1. 硬编码JWT密钥
**文件**：`src/lib/auth.ts:12`
**问题**：JWT密钥硬编码为"secret123"
**风险**：任何人都可以伪造JWT
**修复**：
```typescript
- const secret = "secret123"
+ const secret = process.env.JWT_SECRET
+ if (!secret) throw new Error('JWT_SECRET未设置')

🟠 高优先级问题

2. 缺少输入验证

文件：src/app/api/auth/login/route.ts:15 问题：用户输入在使用前未验证 修复：添加Zod模式验证

const loginSchema = z.object({
  email: z.string().email(),
  password: z.string().min(8),
})

const validated = loginSchema.parse(body)

🟡 中优先级问题

3. 缺少测试

文件：tests/integration/auth.test.ts 问题：无错误用例测试 需要：

• 测试无效邮箱格式
• 测试错误密码
• 测试过期JWT

裁决

🔄 请求更改 - 在合并前修复严重和高优先级问题。

修复后，这将是一个可靠的身份验证实现。

---

## 另请参阅

- security-checklist.md - OWASP Top 10清单
- performance-criteria.md - 性能审查指南
- maintainability-rules.md - 代码质量规则
- review-templates.md - 反馈模板
- ../security-sentinel/SKILL.md - 安全模式
- ../quality-gates/SKILL.md - 质量框架