test: add service layer unit tests for webhook/metadata/error/config

- 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%
This commit is contained in:
2026-04-09 15:30:26 +08:00
parent a6a0e58340
commit a3e090e821
13 changed files with 12024 additions and 19 deletions

View File

@@ -0,0 +1,678 @@
# 代码审查标准与质量评级规范 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*