user-system/docs/code-review/CODE_REVIEW_STANDARD_V2.md

# 代码审查标准与质量评级规范 v2.0

**文档版本**: v2.0
**生成日期**: 2026-04-08
**适用范围**: User Management System (UMS) 项目
**审查专家**: 代码审查专家

---

## 一、审查目标与原则

### 1.1 核心目标

建立**可量化、可执行、可追踪**的代码审查机制，确保：
- 代码质量持续达标
- 安全漏洞零容忍
- 技术债可控增长
- 团队能力持续提升

### 1.2 审查原则

| 原则 | 说明 |
|------|------|
| **事实优先** | 审查结论必须有代码证据，不基于猜测 |
| **分级治理** | 不同严重程度的问题差异化处理 |
| **教育导向** | 每条审查意见都应教会开发者一些东西 |
| **持续改进** | 每次审查沉淀经验，完善规范 |

---

## 二、质量评级体系

### 2.1 代码评分维度

| 维度 | 权重 | 评分标准 | 工具支持 |
|------|------|----------|----------|
| **安全性** | 30% | 0-10 | 人工审查 + gosec |
| **正确性** | 25% | 0-10 | go vet + 单元测试 |
| **可维护性** | 20% | 0-10 | 人工审查 |
| **性能** | 15% | 0-10 | 人工审查 + 基准测试 |
| **测试覆盖** | 10% | 0-10 | go test coverage |

### 2.2 综合评分公式

```
综合评分 = 安全性×0.30 + 正确性×0.25 + 可维护性×0.20 + 性能×0.15 + 测试覆盖×0.10
```

### 2.3 评级标准

| 评分区间 | 评级 | 行动 |
|----------|------|------|
| **9.0-10.0** | 🏆 卓越 | 可合并，记录亮点 |
| **8.0-8.9** | ✅ 优秀 | 可合并，有改进空间 |
| **7.0-7.9** | ⚠️ 良好 | 建议修复后合并 |
| **6.0-6.9** | 🔶 需要改进 | 必须修复🟡问题后合并 |
| **< 6.0** | 🔴 不合格 | 必须修复所有🟡问题，审查员确认后合并 |

---

## 三、问题分级标准

### 3.1 分级定义

| 级别 | 标识 | 定义 | 合并影响 |
|------|------|------|----------|
| **阻塞** | 🔴 | 安全漏洞、数据丢失风险、编译失败 | **必须修复**，否则禁止合并 |
| **严重** | 🟠 | 功能错误、严重性能问题、错误处理缺失 | **必须修复**，否则禁止合并 |
| **建议** | 🟡 | 代码重复、轻微性能问题、可维护性改进 | 建议修复，🟡≤3可合并 |
| **挑剔** | 💭 | 代码风格、命名优化、注释改进 | 鼓励修复，不阻塞合并 |

### 3.2 阻塞级问题清单（必须修复）

#### 安全类 🔴

| ID | 规则 | 检查方法 |
|----|------|----------|
| SEC-B01 | SQL 注入 | 参数化查询验证 |
| SEC-B02 | XSS 漏洞 | 输出编码验证 |
| SEC-B03 | 认证绕过 | 权限中间件验证 |
| SEC-B04 | 敏感数据泄露 | 日志/响应审查 |
| SEC-B05 | 不安全随机数 | crypto/rand 使用验证 |
| SEC-B06 | 硬编码密钥 | 密钥扫描 |
| SEC-B07 | 密码明文存储 | 哈希算法验证 |

#### 正确性类 🔴

| ID | 规则 | 检查方法 |
|----|------|----------|
| CORR-B01 | 编译失败 | `go build` 验证 |
| CORR-B02 | 单元测试失败 | `go test` 验证 |
| CORR-B03 | 竞态条件 | 并发代码审查 |
| CORR-B04 | 资源泄漏 | defer/cleanup 审查 |
| CORR-B05 | 错误被忽略 | `_ = err` 扫描 |

### 3.3 严重级问题清单（必须修复）

| ID | 规则 | 检查方法 |
|----|------|----------|
| SEV-01 | N+1 查询 | Repository 调用链审查 |
| SEV-02 | Goroutine 泄漏 | context 使用审查 |
| SEV-03 | 无超时控制 | HTTP/DB 超时审查 |
| SEV-04 | 错误处理不当 | 错误传播审查 |
| SEV-05 | 事务边界错误 | 事务代码审查 |

---

## 四、模块化审查清单

### 4.1 认证模块审查

```
□ 密码哈希使用 Argon2id 或 bcrypt
□ 密码哈希使用 crypto/rand 生成盐
□ Token 使用 crypto/rand 生成
□ JTI 支持黑名单/轮换
□ 刷新令牌有滚动机制
□ 登录尝试有速率限制
□ 错误信息不泄露用户存在性
□ 会话超时配置合理
□ 退出登录正确清理状态
□ 敏感操作需要二次验证
```

### 4.2 API 路由审查

```
□ 所有受保护路由有权限中间件
□ 输入验证使用 binding:"required"
□ 参数化查询防 SQL 注入
□ 响应不包含敏感字段
□ 错误响应不泄露内部信息
□ CSRF 保护配置正确
□ CORS 配置非 wildcard
□ 限流中间件覆盖
```

### 4.3 数据库操作审查

```
□ 使用 GORM 参数化查询
□ 索引覆盖常用查询条件
□ 无 N+1 查询模式
□ 事务边界正确
□ 连接池配置合理
□ 批量操作有分页限制
□ LIKE 查询有转义处理
□ 软删除/硬删除策略明确
```

### 4.4 并发安全审查

```
□ 共享 map 使用 RWMutex
□ goroutine 有 context 控制
□ 无 context.Background() 滥用
□ 资源在 defer 释放
□ 无数据竞争（go test -race）
□ 原子操作使用 sync/atomic
```

### 4.5 前端安全审查

```
□ access_token 仅存内存
□ refresh_token 用 HttpOnly Cookie
□ XSS 防护：用户输入转义
□ CSRF：状态变更请求带 token
□ 敏感数据不存 localStorage
□ API 错误不直接展示给用户
□ 路由守卫正确配置
□ 退出清理完整（内存+Cookie）
```

---

## 五、自动化检查配置

### 5.1 Go 后端配置

```yaml
# .golangci.yml
linters:
  enable:
    - gosec       # 安全扫描
    - govet       # 代码诊断
    - gocyclo     # 圈复杂度（>15 报警）
    - revive      # 代码风格
    - unused      # 未使用代码
    - staticcheck # 静态分析
    - structcheck # 结构体检查
    - errcheck    # 错误检查

linters-settings:
  gosec:
    excludes:
      - G104  # Audit errors not checked
  gocyclo:
    min-complexity: 15
  revive:
    rules:
      - name: blank-imports
      - name: context-as-argument
      - name: context-keys-type
      - name: dot-imports
      - name: error-return
      - name: error-strings
      - name: error-naming
      - name: exported
      - name: increment-decrement
      - name: var-naming
      - name: var-declaration
      - name: package-comments
      - name: range
      - name: receiver-naming
      - name: time-naming
```

### 5.2 前端配置

```javascript
// .eslintrc.js (关键规则)
rules: {
  // 安全
  'no-eval': 'error',
  'no-implied-eval': 'error',
  'no-new-func': 'error',
  
  // 最佳实践
  'no-console': process.env.NODE_ENV === 'production' ? 'warn' : 'off',
  'no-debugger': process.env.NODE_ENV === 'production' ? 'error' : 'off',
  
  // TypeScript
  '@typescript-eslint/no-explicit-any': 'warn',
  '@typescript-eslint/no-unused-vars': ['error', { argsIgnorePattern: '^_' }],
  
  // React
  'react-hooks/exhaustive-deps': 'warn',
  'react/no-direct-mutation-state': 'error',
}
```

---

## 六、审查流程

### 6.1 提交前自审（开发者）

```bash
# 后端
go vet ./...
go build ./cmd/server
go test ./... -count=1
go test -race ./...  # 竞态检测

# 前端
npm run lint
npm run build
npm test -- --coverage
```

### 6.2 PR 审查流程

```
┌─────────────────────────────────────────────────────────────────────┐
│                        PR 创建                                     │
└─────────────────────────────────┬───────────────────────────────────┘
                                  ▼
┌─────────────────────────────────────────────────────────────────────┐
│  1. CI 检查                                                         │
│     □ go build / npm run build                                     │
│     □ go test / npm test                                           │
│     □ go vet / npm run lint                                        │
│     □ 覆盖率不下降                                                  │
└─────────────────────────────────┬───────────────────────────────────┘
                                  ▼
┌─────────────────────────────────────────────────────────────────────┐
│  2. 人工审查（审查者）                                               │
│     □ 逐文件审查关键代码                                             │
│     □ 执行模块化审查清单                                             │
│     □ 标注问题并分级                                                 │
│     □ 给出修复建议                                                   │
└─────────────────────────────────┬───────────────────────────────────┘
                                  ▼
┌─────────────────────────────────────────────────────────────────────┐
│  3. 问题修复（作者）                                                 │
│     🔴 → 必须修复后重新审查                                          │
│     🟠 → 必须修复后重新审查                                          │
│     🟡 → 修复后标注或忽略（有理由）                                   │
│     💭 → 可忽略，有理由即可                                          │
└─────────────────────────────────┬───────────────────────────────────┘
                                  ▼
┌─────────────────────────────────────────────────────────────────────┐
│  4. 审查确认（审查者）                                               │
│     □ 所有 🔴🟠 已修复                                               │
│     □ 🟡 ≤ 3 个且有修复计划                                          │
│     □ 综合评分 ≥ 7.0                                                 │
│     □ Approve                                                         │
└─────────────────────────────────┬───────────────────────────────────┘
                                  ▼
┌─────────────────────────────────────────────────────────────────────┐
│  5. 合并                                                              │
│     □ Squash merge 到 main                                          │
│     □ 删除源分支                                                      │
│     □ 更新相关文档                                                    │
└─────────────────────────────────────────────────────────────────────┘
```

### 6.3 审查时效要求

| PR 类型 | 首次审查 | 问题修复后复核 | 总时限 |
|---------|----------|----------------|--------|
| 紧急修复 | 1 小时 | 30 分钟 | 4 小时 |
| 常规功能 | 4 小时 | 1 小时 | 24 小时 |
| 重构/优化 | 8 小时 | 2 小时 | 48 小时 |

---

## 七、审查报告规范

### 7.1 报告模板

```markdown
# 代码审查报告

**PR**: #[编号] [标题]
**作者**: [姓名]
**审查者**: [姓名]
**日期**: YYYY-MM-DD
**综合评分**: X.X/10 ([评级])

---

## 执行摘要

[2-3 句话总结代码质量]

## 检查清单执行

| 检查项 | 状态 | 说明 |
|--------|------|------|
| go vet | ✅/❌ |  |
| go build | ✅/❌ |  |
| go test | ✅/❌ |  |
| 覆盖率 | X% |  |
| 安全审查 | ✅/❌ |  |
| ... | ... |  |

## 问题清单

### 🔴 阻塞 (X 个)

| # | 问题 | 位置 | 修复状态 |
|---|------|------|----------|
| 1 |  |  | 已修复/未修复 |

### 🟠 严重 (X 个)

...

### 🟡 建议 (X 个)

...

### 💭 挑剔 (X 个)

...

## 做得好的地方

- [亮点1]
- [亮点2]

## 修复建议优先级

| 优先级 | 问题数 | 行动 |
|--------|--------|------|
| P0 (立即) | X |  |
| P1 (今天) | X |  |
| P2 (本周) | X |  |

## 审查结论

✅ **可以合并** / ❌ **需要修改后重新审查**

---

签名: __________ 日期: __________
```

### 7.2 问题追踪

```yaml
# .github/ISSUE_TEMPLATE/code_review.yml
name: Code Review Issue
description: 追踪代码审查中发现的问题
labels: [code-review, security, bug, improvement]
```

---

## 八、质量门禁

### 8.1 合并门禁（必须全部通过）

| 检查项 | 标准 | 命令 |
|--------|------|------|
| 编译 | 成功 | `go build ./...` / `npm run build` |
| 单元测试 | 100% 通过 | `go test ./... -count=1` |
| Lint | 无 error | `go vet` / `npm run lint` |
| 覆盖率 | 不下降 | `go test -coverprofile` |
| 安全扫描 | 无高危漏洞 | `gosec ./...` |

### 8.2 代码扫描工具

```bash
# Go 安全扫描
gosec ./...

# 前端安全扫描
npm audit --audit-level=moderate

# 依赖漏洞检查
go mod verify
npm outdated
```

---

## 九、持续改进机制

### 9.1 审查指标

| 指标 | 目标 | 当前值 | 趋势 |
|------|------|--------|------|
| 平均审查时间 | < 8h | - | - |
| 首次通过率 | > 60% | - | - |
| 阻塞问题数/版本 | < 2 | - | - |
| 代码覆盖率 | > 80% | - | - |

### 9.2 审查知识库

每次审查后：
1. 记录新的反模式 → `docs/security/anti-patterns.md`
2. 记录性能优化案例 → `docs/performance/case-studies.md`
3. 更新检查清单 → `docs/checklists/`

### 9.3 定期回顾

| 周期 | 内容 | 负责人 |
|------|------|--------|
| 每 PR | 审查报告归档 | 审查者 |
| 每周 | 审查指标汇总 | Tech Lead |
| 每月 | 规范更新、工具升级 | 代码审查专家 |
| 每季度 | 全面审查、流程优化 | Team |

---

## 十、附录

### 10.1 快速检查命令

```bash
# 后端完整检查
go vet ./... && go build ./cmd/server && go test ./... -count=1 -race

# 前端完整检查
cd frontend/admin && npm run lint && npm run build && npm test -- --coverage

# E2E 测试
cd frontend/admin && npm run e2e:full:win

# 安全扫描
gosec ./...
npm audit
```

### 10.2 参考资料

- [OWASP Top 10](https://owasp.org/www-project-top-ten/)
- [Go Code Review Comments](https://github.com/golang/go/wiki/CodeReviewComments)
- [Google Engineering Practices](https://google.github.io/eng-practices/)
- [Security Code Review Checklist (OWASP)](https://owasp.org/www-pdf-archive/OWASP_Code_Review_Guide_v2.pdf)

---

*本文档由代码审查专家 Agent 制定并维护，版本: v2.0*
*最后更新: 2026-04-08*