long-agent
a85d822419
- 所有Handler方法使用标准{code:0,message:"success",data:...}响应格式
- 修复Cursor分页响应包装(GetAllDevices,GetLoginLogs,ListUsers等)
- 修复AuthHandler和SMSHandler认证方法响应格式
- 修复operation_log.go admin用户operation_type前缀问题
- 修复DashboardPage嵌套stats结构
- 修复LoginLogsPage reset功能stale closure问题
- 修复UsersPage批量操作API调用
- 修复多个前端测试(mock格式、按钮选择、断言逻辑)
- 添加OAuth测试域名白名单
- 新增代码审查流程文档
15 KiB
15 KiB
代码审查标准与质量评级规范 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 后端配置
# .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 前端配置
// .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 提交前自审（开发者）
# 后端
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 报告模板
# 代码审查报告
**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 问题追踪
# .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 代码扫描工具
# Go 安全扫描
gosec ./...
# 前端安全扫描
npm audit --audit-level=moderate
# 依赖漏洞检查
go mod verify
npm outdated
九、持续改进机制
9.1 审查指标
| 指标 | 目标 | 当前值 | 趋势 |
|---|---|---|---|
| 平均审查时间 | < 8h | - | - |
| 首次通过率 | > 60% | - | - |
| 阻塞问题数/版本 | < 2 | - | - |
| 代码覆盖率 | > 80% | - | - |
9.2 审查知识库
每次审查后：
- 记录新的反模式 →
docs/security/anti-patterns.md - 记录性能优化案例 →
docs/performance/case-studies.md - 更新检查清单 →
docs/checklists/
9.3 定期回顾
| 周期 | 内容 | 负责人 |
|---|---|---|
| 每 PR | 审查报告归档 | 审查者 |
| 每周 | 审查指标汇总 | Tech Lead |
| 每月 | 规范更新、工具升级 | 代码审查专家 |
| 每季度 | 全面审查、流程优化 | Team |
十、附录
10.1 快速检查命令
# 后端完整检查
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
- Go Code Review Comments
- Google Engineering Practices
- Security Code Review Checklist (OWASP)
本文档由代码审查专家 Agent 制定并维护，版本: v2.0 最后更新: 2026-04-08