wenzi/docs/review-2025-09-30.md

代码审查报告（2025-09-30）

概览

• 技术栈：Spring Boot 3、Java 17、Maven、JUnit 5、MockMvc、Flyway、Redis（缓存，测试为嵌入式）。
• 构建与测试：已联网执行 mvn clean verify 成功。产物 target/mosquito-0.0.1-SNAPSHOT.jar 生成。
• 测试统计：共 26 个测试，全通过（0 失败/0 错误/0 跳过），详见 target/surefire-reports/。

结构与模块

• 包结构清晰：controller / service / domain / dto / exception / job。
• 资源与迁移：application.properties 与 Flyway 迁移（V1–V5）完整，命名规范。
• 文档完善：docs/（API、架构、数据模型、测试计划）与 specs/ 分层合理。

主要发现

• 控制器：输入校验充分（@Valid），返回码语义正确；异常部分依赖注解映射，建议统一异常处理。
• 服务：ActivityService 为内存态实现，具备并发安全；getLeaderboard 使用 Thread.sleep 模拟耗时，建议替换为可注入的延迟或移除。
• 领域模型：当前未持久化（无 JPA 注解），与 Flyway 表结构存在偏差（如 JSONB 字段、状态字段等）。
• 定时任务：StatisticsAggregationJob 逻辑简单明确，易扩展为真实数据聚合。
• 依赖：引入了 JPA/AMQP 但暂未使用；javax.annotation-api 在 Boot 3 生态建议迁移至 jakarta.annotation（仅测试配置中使用）。
• 缓存：@Cacheable("leaderboards") 生效，建议补充 TTL、序列化策略与命名规范。

建议优先级

1. 统一异常处理与错误响应格式（高）。
2. 去除 Thread.sleep 模拟延迟（高）。
3. 对齐领域模型与数据库（引入 JPA 实体/仓储）（高）。
4. 缓存策略（TTL、序列化、命名）与多环境配置（中）。
5. API Key 安全增强与审计（中）。
6. 测试覆盖补齐（奖励/多级奖励/上传/权限）（中）。
7. 依赖精简或尽快落地 AMQP/JPA（中）。
8. 覆盖率基线（JaCoCo）与质量门禁（中）。