项目：CodeQ 代码大模型训练语料质量评估平台

开发模块：Repository 层查询方法扩展与 Service 层指标数据服务开发

当前进度：FileMetricRepository、MetricResultRepository、MetricDetailJsonRepository、QualityReportRepository 扩展 taskId 查询能力，FileMetricService、MetricResultService、MetricDetailJsonService、QualityReportService 全部新建完成，Spring Data JPA 查询方法命名规范实践，全接口编译通过。

---

一、任务与目标

上一篇完成了个人中心模块的 Service 层开发，本次进入数据查询层的系统化建设。在 ETL 完成数据入库后，上层业务需要按照分析任务维度查询各项指标数据，而原始 Repository 仅提供了基础的 JPA CRUD 方法，缺乏按 taskId 聚合查询的能力。本次目标是为 4 个核心指标实体补充按任务维度的查询方法，并封装对应的 Service 层，为 AI 评估模块和前端展示提供统一的数据查询入口。

---

二、Repository 层扩展

基于 Spring Data JPA 的方法命名派生规则，在不写一行 SQL 的前提下为 4 个 Repository 新增 taskId 查询方法：

FileMetricRepository —— 文件级指标查询：

Optional<FileMetric> findByTaskId(Long taskId);

根据分析任务 ID 查询文件级代码度量数据，包括圈复杂度、代码行数、警告数等维度。

MetricResultRepository —— 任务汇总指标查询：

Optional<MetricResult> findByTaskId(Long taskId);

返回单次分析任务的汇总得分，包括注释密度、平均圈复杂度、代码重复率、命名违规数等。

MetricDetailJsonRepository —— 指标明细 JSON 查询：

Optional<MetricDetailJson> findByTaskId(Long taskId);

获取 ETL 阶段写入的完整指标 JSON，供前端渲染详细图表。

QualityReportRepository —— 质量报告查询：

Optional<QualityReport> findByTaskId(Long taskId);

查询 AI 评估后生成的自然语言质量报告。

Spring Data JPA 的优势在此体现：方法名即查询语义，框架自动解析为 WHERE task_id = ? ，零 SQL 零配置。

---

三、Service 层封装

遵循 Controller → Service → Repository 的标准三层调用链，为每个实体创建对应的 Service：

关键设计：

- 所有查询方法使用 Optional 返回值，上层调用方自己判断是否存在数据，避免 NPE
- Service 不包含业务逻辑仅做查询封装，保持层次边界清晰
- @Autowired 注入 Repository，方法直接委托给 JPA

---

四、Controller 层新建

为 4 个 Service 创建对应的 REST 控制器，统一前缀 /api ：

- FileMetricController ：GET /api/file-metric/task/{taskId} / DELETE
- MetricResultController ：GET /api/metric-result/task/{taskId} / POST / DELETE
- MetricDetailJsonController ：GET /api/metric-detail/task/{taskId}
- QualityReportController ：GET /api/quality-report/task/{taskId} / GET /{id} / DELETE
全部使用 R<T> 统一返回格式，与项目已有接口风格一致。

---

五、技术理解

本次开发的核心收获是对 Spring Data JPA 查询派生命名规范的复用实践。在团队项目中，表结构已经固定，新增查询方法只需在 Repository 接口中声明即可，无需修改任何 SQL 或 XML。这种"零侵入"的扩展方式，非常适合多人在建表后分批开发业务模块的场景。

---

六、当前项目进度

- 4 个 Repository 扩展完成
- 4 个 Service 新建完成
- 4 个 Controller 基础 CRUD 接口暴露完成
- Maven 编译通过，JPA 方法解析无误
下一篇将进入大模型 API 接入与质量评估模块，实现 AI 驱动的代码质量评分与报告生成。