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%
19 KiB
19 KiB
代码审查标准与质量评级规范 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 生产合并门禁（必须全部通过）
# 生产级 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 测试覆盖率要求
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）
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 渗透测试要求
penetration_testing:
schedule: quarterly
scope:
- SQL注入测试
- XSS测试
- CSRF测试
- 认证绕过测试
- 会话管理测试
- 敏感数据泄露测试
report: required
responsible: external_security_team
四、部署简单性审查清单
4.1 Docker 部署标准
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 监控要求
monitoring_requirements:
# 基础设施监控
infrastructure:
- CPU使用率
- 内存使用率
- 磁盘使用率
- 网络IO
# 应用监控
application:
- 请求延迟（P50/P95/P99）
- 错误率
- QPS
- 活跃连接数
# 业务监控
business:
- 登录成功率
- 注册成功率
- API 调用成功率
- Token 刷新成功率
# 数据库监控
database:
- 连接池使用率
- 查询延迟
- 慢查询数量
- 复制延迟（如果有）
5.2 告警要求
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 备份与恢复
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 文档
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 要求
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 安全合规
security_compliance:
# 数据保护
data_protection:
- GDPR合规（如果适用）
- 数据加密存储
- 数据传输加密
- 数据访问审计
# 访问控制
access_control:
- 最小权限原则
- 密钥轮换
- 多因素认证
- 访问审计日志
# 漏洞管理
vulnerability_management:
- 依赖扫描（每日）
- 渗透测试（季度）
- 漏洞修复 SLA（严重24h，高危7天）
9.2 运营合规
operational_compliance:
# 可用性
availability:
- SLO定义（99.9%）
- SLA承诺（99.5%）
- 错误预算监控
# 备份
backup:
- 备份策略文档
- 恢复测试记录
- 备份保留策略
# 事件管理
incident_management:
- 事件分级标准
- 升级流程
- 事后复盘要求
十、附录
10.1 快速检查命令
# 完整门禁检查（生产合并前必须）
#!/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