long-agent
a3e090e821
- webhook_service_test.go: isPrivateIP, isSafeURL, computeHMAC - request_metadata_test.go: context functions - classified_error_test.go: error types - config_defaults_test.go: password reset/SMS defaults - email_config_test.go: email code defaults - auth_runtime_test.go: isUserNotFoundError Service coverage: 11.2% -> 14.7%
679 lines
19 KiB
Markdown
679 lines
19 KiB
Markdown
# 代码审查标准与质量评级规范 v3.0
|
||
|
||
**文档版本**: v3.0
|
||
**生成日期**: 2026-04-08
|
||
**适用范围**: User Management System (UMS) 项目
|
||
**审查专家**: 代码审查专家
|
||
**目标**: 生产级软件质量标准
|
||
|
||
---
|
||
|
||
## 修订说明
|
||
|
||
v3.0 版本针对"生产上线"要求进行全面升级：
|
||
|
||
| 维度 | v2.0 | v3.0 | 差距 |
|
||
|------|------|------|------|
|
||
| 代码质量 | 9.7/10 | **7.5/10** | 测试覆盖率仅32.1%，严重不足 |
|
||
| 安全强度 | 9.7/10 | **6.0/10** | 无gosec扫描、占位JWT密钥、缺渗透测试 |
|
||
| 部署简单性 | 8.0/10 | **5.0/10** | docker-compose简陋、无K8s、无健康检查 |
|
||
| 运维可靠性 | 7.0/10 | **4.0/10** | 无备份自动化、无灾备方案、监控薄弱 |
|
||
| 文档规范性 | 7.0/10 | **5.0/10** | 缺OpenAPI、缺Runbook、缺应急响应 |
|
||
|
||
**综合评分（v3.0真实评估）**: **5.9/10 ⚠️ 不合格**
|
||
|
||
---
|
||
|
||
## 一、生产级质量标准（v3.0）
|
||
|
||
### 1.1 五维评估体系
|
||
|
||
| 维度 | 权重 | 生产标准 | 当前差距 |
|
||
|------|------|----------|----------|
|
||
| **代码质量** | 25% | 覆盖率≥80%，无技术债 | 覆盖率32.1%，差距48% |
|
||
| **安全强度** | 30% | 渗透测试、gosec合格、合规 | 无扫描工具、占位密钥 |
|
||
| **部署简单性** | 15% | 一键部署、配置分离、不可变 | docker-compose简陋 |
|
||
| **运维可靠性** | 20% | 监控完善、告警到位、备份自动化 | 监控基础、告警未验证 |
|
||
| **文档规范性** | 10% | OpenAPI、Runbook、应急响应 | 文档残缺 |
|
||
|
||
### 1.2 生产合并门禁（必须全部通过）
|
||
|
||
```yaml
|
||
# 生产级 PR 合并门禁
|
||
pre_merge_checks:
|
||
# 代码质量
|
||
- name: 后端覆盖率
|
||
command: go test -coverprofile coverage.out ./...
|
||
threshold: 80%
|
||
critical_paths: 90%
|
||
- name: 前端覆盖率
|
||
command: npm test -- --coverage
|
||
threshold: 80%
|
||
|
||
# 安全
|
||
- name: Go安全扫描
|
||
command: gosec ./...
|
||
critical: high/critical must be 0
|
||
- name: 前端安全扫描
|
||
command: npm audit
|
||
critical: 0 vulnerabilities
|
||
- name: 依赖漏洞扫描
|
||
command: govulncheck ./...
|
||
critical: 0 findings
|
||
|
||
# 构建
|
||
- name: 后端编译
|
||
command: go build ./cmd/server
|
||
- name: 前端构建
|
||
command: npm run build
|
||
|
||
# 测试
|
||
- name: 后端测试
|
||
command: go test ./... -count=1 -race
|
||
- name: 前端测试
|
||
command: npm test -- --coverage
|
||
- name: E2E测试
|
||
command: npm run e2e:full:win
|
||
```
|
||
|
||
### 1.3 问题分级（生产级）
|
||
|
||
| 级别 | 标识 | 定义 | 合并影响 |
|
||
|------|------|------|----------|
|
||
| **P0 阻塞** | 🔴 | 安全漏洞、数据丢失风险、生产不可用 | **必须修复** |
|
||
| **P1 严重** | 🟠 | 功能错误、性能严重劣化、合规风险 | **必须修复** |
|
||
| **P2 高** | 🟡 | 测试覆盖率不足、技术债积累、文档缺失 | **72小时内修复** |
|
||
| **P3 中** | 🔵 | 代码风格、轻微优化、文档完善 | **本周修复** |
|
||
| **P4 低** | 💭 | 挑剔级改进、愿望清单 | 可延迟 |
|
||
|
||
---
|
||
|
||
## 二、代码质量审查清单
|
||
|
||
### 2.1 测试覆盖率要求
|
||
|
||
```yaml
|
||
coverage_requirements:
|
||
backend:
|
||
overall: 80%
|
||
critical_paths:
|
||
auth_handler: 90%
|
||
jwt: 95%
|
||
password: 95%
|
||
repository: 70%
|
||
excluded:
|
||
- cmd/server/main.go # 可豁免
|
||
- docs/ # 文档包
|
||
- testdb/ # 测试数据库
|
||
- testutil/ # 测试工具
|
||
|
||
frontend:
|
||
overall: 80%
|
||
critical_paths:
|
||
auth: 90%
|
||
http_client: 90%
|
||
router: 100%
|
||
guards: 100%
|
||
```
|
||
|
||
### 2.2 单元测试审查
|
||
|
||
```
|
||
□ 每个公开函数有单元测试
|
||
□ 边界条件被测试（空值、极大值、特殊字符）
|
||
□ 错误路径被测试
|
||
□ 并发安全被测试（go test -race）
|
||
□ 无 mock 滥用（真实依赖优先）
|
||
□ 测试命名规范：Test[函数名][场景]
|
||
□ 单元测试不依赖外部状态
|
||
```
|
||
|
||
### 2.3 集成测试审查
|
||
|
||
```
|
||
□ 数据库操作有集成测试
|
||
□ API 端点有集成测试
|
||
□ 认证流程有集成测试
|
||
□ 测试使用隔离数据库（不污染开发数据）
|
||
```
|
||
|
||
---
|
||
|
||
## 三、安全强度审查清单
|
||
|
||
### 3.1 自动化安全扫描（必须集成CI）
|
||
|
||
```yaml
|
||
security_automation:
|
||
gosec:
|
||
schedule: daily
|
||
fail_on: high/critical
|
||
exclusions: documented
|
||
|
||
npm_audit:
|
||
schedule: daily
|
||
fail_on: moderate/high
|
||
audit_level: moderate
|
||
|
||
govulncheck:
|
||
schedule: weekly
|
||
fail_on: any
|
||
|
||
owasp_dependency_check:
|
||
schedule: weekly
|
||
report: required
|
||
```
|
||
|
||
### 3.2 安全审查清单
|
||
|
||
#### 认证安全
|
||
```
|
||
□ 密码使用 Argon2id（已验证 ✅）
|
||
□ Token 使用 crypto/rand（已验证 ✅）
|
||
□ JTI 防枚举（已验证 ✅）
|
||
□ Token 滚动轮换（已验证 ✅）
|
||
□ 登录速率限制（已验证 ✅）
|
||
□ 异常登录检测（已验证 ✅）
|
||
□ 退出登录清理状态（已验证 ✅）
|
||
```
|
||
|
||
#### 数据安全
|
||
```
|
||
□ 敏感数据不写入日志
|
||
□ 敏感数据不返回 API
|
||
□ 数据库使用参数化查询
|
||
□ 密码不硬编码
|
||
□ 密钥从环境变量/密钥管理器读取
|
||
```
|
||
|
||
#### 传输安全
|
||
```
|
||
□ HTTPS 强制
|
||
□ HSTS 配置
|
||
□ CSRF 保护
|
||
□ CORS 非 wildcard
|
||
```
|
||
|
||
#### 依赖安全
|
||
```
|
||
□ 无已知 CVE 漏洞
|
||
□ 无弃用依赖
|
||
□ 最小权限依赖原则
|
||
```
|
||
|
||
### 3.3 渗透测试要求
|
||
|
||
```yaml
|
||
penetration_testing:
|
||
schedule: quarterly
|
||
scope:
|
||
- SQL注入测试
|
||
- XSS测试
|
||
- CSRF测试
|
||
- 认证绕过测试
|
||
- 会话管理测试
|
||
- 敏感数据泄露测试
|
||
report: required
|
||
responsible: external_security_team
|
||
```
|
||
|
||
---
|
||
|
||
## 四、部署简单性审查清单
|
||
|
||
### 4.1 Docker 部署标准
|
||
|
||
```yaml
|
||
docker_requirements:
|
||
# 镜像构建
|
||
multi_stage: true # 使用多阶段构建减小镜像
|
||
non_root_user: true # 非 root 用户运行
|
||
scratch_base: preferred # 最小基础镜像
|
||
|
||
# 健康检查
|
||
healthcheck:
|
||
test: ["CMD", "curl", "-f", "http://localhost:8080/health/ready"]
|
||
interval: 30s
|
||
timeout: 10s
|
||
retries: 3
|
||
|
||
# 资源限制
|
||
resources:
|
||
memory: 512Mi
|
||
cpu: "500m"
|
||
|
||
# 重启策略
|
||
restart: unless-stopped
|
||
restart_max_attempts: 5
|
||
```
|
||
|
||
### 4.2 Kubernetes 部署要求
|
||
|
||
```
|
||
□ 有 Helm Chart 或 Kustomize 配置
|
||
□ 有 Deployment/StatefulSet
|
||
□ 有 Service 配置
|
||
□ 有 Ingress 配置
|
||
□ 有 ConfigMap/Secret 管理配置
|
||
□ 有 HPA（水平自动扩缩容）
|
||
□ 有 PodDisruptionBudget
|
||
□ 有资源请求/限制
|
||
□ 有健康检查（liveness/readiness）
|
||
□ 有安全上下文
|
||
□ 有网络策略
|
||
```
|
||
|
||
### 4.3 部署配置管理
|
||
|
||
```
|
||
□ 环境变量与配置分离
|
||
□ 敏感配置使用 Secret
|
||
□ 配置有版本控制
|
||
□ 支持多环境部署（dev/staging/prod）
|
||
□ 部署脚本幂等
|
||
□ 回滚方案可用
|
||
```
|
||
|
||
---
|
||
|
||
## 五、运维可靠性审查清单
|
||
|
||
### 5.1 监控要求
|
||
|
||
```yaml
|
||
monitoring_requirements:
|
||
# 基础设施监控
|
||
infrastructure:
|
||
- CPU使用率
|
||
- 内存使用率
|
||
- 磁盘使用率
|
||
- 网络IO
|
||
|
||
# 应用监控
|
||
application:
|
||
- 请求延迟（P50/P95/P99）
|
||
- 错误率
|
||
- QPS
|
||
- 活跃连接数
|
||
|
||
# 业务监控
|
||
business:
|
||
- 登录成功率
|
||
- 注册成功率
|
||
- API 调用成功率
|
||
- Token 刷新成功率
|
||
|
||
# 数据库监控
|
||
database:
|
||
- 连接池使用率
|
||
- 查询延迟
|
||
- 慢查询数量
|
||
- 复制延迟（如果有）
|
||
```
|
||
|
||
### 5.2 告警要求
|
||
|
||
```yaml
|
||
alerting_requirements:
|
||
# 关键告警
|
||
critical:
|
||
- 服务不可用
|
||
- 错误率 > 5%
|
||
- P99延迟 > 1s
|
||
- 数据库连接池耗尽
|
||
|
||
# 警告告警
|
||
warning:
|
||
- 错误率 > 1%
|
||
- P95延迟 > 500ms
|
||
- 磁盘使用率 > 80%
|
||
- 内存使用率 > 85%
|
||
|
||
# 通知渠道
|
||
channels:
|
||
- email: on_call_team
|
||
- slack: ops-alerts
|
||
- sms: critical_only
|
||
|
||
# 告警升级
|
||
escalation:
|
||
- 5分钟未响应 → 升级
|
||
- 15分钟未响应 → 升级到 manager
|
||
```
|
||
|
||
### 5.3 日志要求
|
||
|
||
```
|
||
□ 结构化日志（JSON）
|
||
□ 日志级别配置
|
||
□ 日志轮转配置
|
||
□ 敏感信息脱敏
|
||
□ 日志保留期配置（默认30天）
|
||
□ 集中式日志收集
|
||
□ 日志查询支持
|
||
```
|
||
|
||
### 5.4 备份与恢复
|
||
|
||
```yaml
|
||
backup_requirements:
|
||
# 数据库备份
|
||
database:
|
||
frequency: daily
|
||
retention: 30days
|
||
verification: weekly
|
||
encrypted: true
|
||
offsite: true
|
||
|
||
# 配置备份
|
||
config:
|
||
frequency: on_change
|
||
storage: git
|
||
|
||
# 文件备份
|
||
files:
|
||
frequency: weekly
|
||
scope: uploads/
|
||
|
||
# 恢复测试
|
||
recovery_test:
|
||
frequency: quarterly
|
||
documented: true
|
||
```
|
||
|
||
---
|
||
|
||
## 六、文档规范性审查清单
|
||
|
||
### 6.1 API 文档
|
||
|
||
```yaml
|
||
api_documentation:
|
||
# OpenAPI 规范
|
||
openapi:
|
||
version: "3.0.0"
|
||
required: true
|
||
generation: automated
|
||
|
||
# 文档内容
|
||
content:
|
||
- 所有端点有描述
|
||
- 所有参数有说明
|
||
- 所有响应有示例
|
||
- 错误码有说明
|
||
- 认证方式有说明
|
||
|
||
# 文档位置
|
||
location:
|
||
- swagger_ui: /swagger/index.html
|
||
- openapi_json: /swagger/doc.json
|
||
- redoc: /docs
|
||
```
|
||
|
||
### 6.2 部署文档
|
||
|
||
```
|
||
□ 部署前置条件清单
|
||
□ 部署步骤（分环境）
|
||
□ 环境变量说明
|
||
□ 依赖服务说明
|
||
□ 验证步骤
|
||
□ 回滚步骤
|
||
□ 常见问题与解决方案
|
||
```
|
||
|
||
### 6.3 运维文档
|
||
|
||
```
|
||
□ 系统架构图
|
||
□ 组件说明
|
||
□ 监控指标说明
|
||
□ 告警处理手册
|
||
□ 日志说明
|
||
□ 备份恢复手册
|
||
□ 扩容指南
|
||
□ 故障排查手册
|
||
□ 应急响应流程
|
||
```
|
||
|
||
### 6.4 Runbook 要求
|
||
|
||
```yaml
|
||
runbook_requirements:
|
||
# 必需 Runbook
|
||
required:
|
||
- service_startup: 服务启动
|
||
- service_shutdown: 服务停止
|
||
- config_update: 配置更新
|
||
- log_analysis: 日志分析
|
||
- backup_restore: 备份恢复
|
||
- incident_response: 事件响应
|
||
- security_incident: 安全事件响应
|
||
- scaling: 扩缩容
|
||
- database_migration: 数据库迁移
|
||
|
||
# Runbook 格式
|
||
format:
|
||
- 触发条件明确
|
||
- 步骤清晰可执行
|
||
- 验证步骤明确
|
||
- 回滚步骤存在
|
||
- 联系人明确
|
||
```
|
||
|
||
---
|
||
|
||
## 七、差距分析与行动计划
|
||
|
||
### 7.1 当前差距评估
|
||
|
||
| 维度 | 当前状态 | 目标状态 | 差距 | 优先级 |
|
||
|------|----------|----------|------|--------|
|
||
| 后端测试覆盖率 | 32.1% | 80% | -47.9% | 🔴 P0 |
|
||
| 前端测试覆盖率 | ~70% | 80% | -10% | 🟠 P1 |
|
||
| gosec 集成 | 未安装 | 集成CI | N/A | 🔴 P0 |
|
||
| JWT密钥占位符 | config.yaml | 环境变量 | N/A | 🔴 P0 |
|
||
| Docker健康检查 | 无 | 必须 | N/A | 🟠 P1 |
|
||
| K8s配置 | 无 | 必需 | N/A | 🟡 P2 |
|
||
| 备份自动化 | 手动 | 自动 | N/A | 🟠 P1 |
|
||
| 监控完善 | 基础 | 完整 | N/A | 🟡 P2 |
|
||
| Runbook | 缺失 | 必需 | N/A | 🟡 P2 |
|
||
| 渗透测试 | 无 | 季度 | N/A | 🟠 P1 |
|
||
|
||
### 7.2 修复行动计划
|
||
|
||
#### 🔴 P0 - 必须立即修复（本周）
|
||
|
||
| # | 任务 | 影响 | 工作量 |
|
||
|---|------|------|--------|
|
||
| 1 | 安装 gosec 并集成 CI | 安全扫描 | 2h |
|
||
| 2 | 移除 config.yaml 占位密钥，改为环境变量 | 生产安全 | 1h |
|
||
| 3 | 提升后端测试覆盖率至 60% | 代码质量 | 8h |
|
||
| 4 | Docker 添加 healthcheck | 部署可靠性 | 1h |
|
||
|
||
#### 🟠 P1 - 本周内完成
|
||
|
||
| # | 任务 | 影响 | 工作量 |
|
||
|---|------|------|--------|
|
||
| 5 | 后端覆盖率提升至 80% | 代码质量 | 16h |
|
||
| 6 | 前端覆盖率提升至 80% | 代码质量 | 8h |
|
||
| 7 | Docker 添加资源限制 | 运维可靠性 | 1h |
|
||
| 8 | 备份脚本自动化 | 运维可靠性 | 4h |
|
||
| 9 | 季度渗透测试计划 | 安全合规 | 2h |
|
||
|
||
#### 🟡 P2 - 本月完成
|
||
|
||
| # | 任务 | 影响 | 工作量 |
|
||
|---|------|------|--------|
|
||
| 10 | K8s Helm Chart | 部署简单性 | 16h |
|
||
| 11 | 完善监控指标 | 运维可靠性 | 8h |
|
||
| 12 | 告警配置验证 | 运维可靠性 | 4h |
|
||
| 13 | 核心 Runbook | 运维可靠性 | 8h |
|
||
| 14 | OpenAPI 规范完善 | 文档规范性 | 4h |
|
||
|
||
---
|
||
|
||
## 八、审查流程（v3.0）
|
||
|
||
### 8.1 PR 审查流程
|
||
|
||
```
|
||
┌─────────────────────────────────────────────────────────────────────┐
|
||
│ PR 创建 │
|
||
└─────────────────────────────────┬───────────────────────────────────┘
|
||
▼
|
||
┌─────────────────────────────────────────────────────────────────────┐
|
||
│ 1. CI 门禁（自动） │
|
||
│ □ go vet / npm run lint │
|
||
│ □ go build / npm run build │
|
||
│ □ go test / npm test │
|
||
│ □ 覆盖率检查（≥80%） │
|
||
│ □ gosec / npm audit（安全扫描） │
|
||
│ ⚠️ 任一失败 → PR Blocked │
|
||
└─────────────────────────────────┬───────────────────────────────────┘
|
||
▼
|
||
┌─────────────────────────────────────────────────────────────────────┐
|
||
│ 2. 人工审查（审查者） │
|
||
│ □ 业务逻辑审查 │
|
||
│ □ 安全审查 │
|
||
│ □ 性能审查 │
|
||
│ □ 可维护性审查 │
|
||
│ □ 文档审查 │
|
||
└─────────────────────────────────┬───────────────────────────────────┘
|
||
▼
|
||
┌─────────────────────────────────────────────────────────────────────┐
|
||
│ 3. 问题修复（作者） │
|
||
│ 🔴 P0 → 必须修复后重新审查 │
|
||
│ 🟠 P1 → 必须修复后重新审查 │
|
||
│ 🟡 P2 → 72小时内修复 │
|
||
│ 🔵 P3 → 本周修复 │
|
||
└─────────────────────────────────┬───────────────────────────────────┘
|
||
▼
|
||
┌─────────────────────────────────────────────────────────────────────┐
|
||
│ 4. 审查确认（审查者） │
|
||
│ □ 所有 🔴🟠 已修复 │
|
||
│ □ 覆盖率达标 │
|
||
│ □ 安全扫描通过 │
|
||
│ □ Approve │
|
||
└─────────────────────────────────┬───────────────────────────────────┘
|
||
▼
|
||
┌─────────────────────────────────────────────────────────────────────┐
|
||
│ 5. 生产合并前检查 │
|
||
│ □ E2E 测试通过 │
|
||
│ □ 部署文档更新 │
|
||
│ □ 变更日志记录 │
|
||
│ □ 监控指标验证 │
|
||
└─────────────────────────────────┴───────────────────────────────────┘
|
||
```
|
||
|
||
### 8.2 审查时效
|
||
|
||
| PR 类型 | 首次审查 | 问题修复复核 | 总时限 |
|
||
|---------|----------|------------|--------|
|
||
| 紧急修复 | 1小时 | 30分钟 | 4小时 |
|
||
| 常规功能 | 4小时 | 2小时 | 24小时 |
|
||
| 重构/优化 | 8小时 | 4小时 | 48小时 |
|
||
| P0修复 | 30分钟 | 15分钟 | 2小时 |
|
||
|
||
---
|
||
|
||
## 九、合规要求
|
||
|
||
### 9.1 安全合规
|
||
|
||
```yaml
|
||
security_compliance:
|
||
# 数据保护
|
||
data_protection:
|
||
- GDPR合规（如果适用）
|
||
- 数据加密存储
|
||
- 数据传输加密
|
||
- 数据访问审计
|
||
|
||
# 访问控制
|
||
access_control:
|
||
- 最小权限原则
|
||
- 密钥轮换
|
||
- 多因素认证
|
||
- 访问审计日志
|
||
|
||
# 漏洞管理
|
||
vulnerability_management:
|
||
- 依赖扫描（每日）
|
||
- 渗透测试（季度）
|
||
- 漏洞修复 SLA（严重24h，高危7天）
|
||
```
|
||
|
||
### 9.2 运营合规
|
||
|
||
```yaml
|
||
operational_compliance:
|
||
# 可用性
|
||
availability:
|
||
- SLO定义（99.9%）
|
||
- SLA承诺（99.5%）
|
||
- 错误预算监控
|
||
|
||
# 备份
|
||
backup:
|
||
- 备份策略文档
|
||
- 恢复测试记录
|
||
- 备份保留策略
|
||
|
||
# 事件管理
|
||
incident_management:
|
||
- 事件分级标准
|
||
- 升级流程
|
||
- 事后复盘要求
|
||
```
|
||
|
||
---
|
||
|
||
## 十、附录
|
||
|
||
### 10.1 快速检查命令
|
||
|
||
```bash
|
||
# 完整门禁检查（生产合并前必须）
|
||
#!/bin/bash
|
||
set -e
|
||
|
||
echo "=== 代码质量检查 ==="
|
||
go test ./... -count=1 -race
|
||
go tool cover -func coverage.out | grep total | awk '{print "Coverage:", $3}'
|
||
|
||
echo "=== 安全扫描 ==="
|
||
gosec ./...
|
||
npm audit
|
||
govulncheck ./...
|
||
|
||
echo "=== 构建检查 ==="
|
||
go build ./cmd/server
|
||
npm run build
|
||
|
||
echo "=== E2E 测试 ==="
|
||
npm run e2e:full:win
|
||
|
||
echo "=== 所有检查通过 ==="
|
||
```
|
||
|
||
### 10.2 评分计算器
|
||
|
||
```
|
||
综合评分 = 代码质量×0.25 + 安全强度×0.30 + 部署简单性×0.15 + 运维可靠性×0.20 + 文档规范性×0.10
|
||
|
||
生产标准：
|
||
- ≥9.0：卓越，可随时发布
|
||
- 8.0-8.9：优秀，可发布
|
||
- 7.0-7.9：良好，修复P2后发布
|
||
- 6.0-6.9：需要改进，修复P1后发布
|
||
- <6.0：不合格，修复P0后重新评估
|
||
```
|
||
|
||
---
|
||
|
||
*本文档由代码审查专家 Agent 生成*
|
||
*版本: v3.0*
|
||
*最后更新: 2026-04-08*
|
||
*下次审查: 2026-04-15*
|