CodeQ 项目数据库设计一、项目背景CodeQ 是一个代码大模型训练语料质量评估平台旨在通过指标提取与大模型分析相结合的方式为用户提供可解释、可对比的代码质量报告。平台支持多仓库对比、质量趋势追踪是大模型时代下代码质量管理的重要工具。本文将详细介绍 CodeQ 平台的数据库设计方案包括表结构设计、字段说明、关系映射以及设计思路。二、数据库设计概述2.1 数据库选型数据库系统MySQL 8.0字符集utf8mb4支持完整的 Unicode 字符包括 emoji排序规则utf8mb4_unicode_ci支持多语言排序2.2 数据库名称codeq_db2.3 设计原则模块化设计按业务功能划分数据表降低耦合度可扩展性预留 JSON 扩展字段支持指标动态扩展可追溯性记录操作日志便于审计和调试规范化遵循数据库三范式减少数据冗余三、核心表结构设计3.1 用户表user用户表是平台的基础存储所有注册用户的信息。CREATETABLEuser(idBIGINTPRIMARYKEYAUTO_INCREMENTCOMMENT用户唯一ID,usernameVARCHAR(50)NOTNULLUNIQUECOMMENT用户名唯一,passwordVARCHAR(100)NOTNULLCOMMENT加密后的用户密码,emailVARCHAR(100)COMMENT用户邮箱,roleVARCHAR(20)DEFAULTuserCOMMENT用户角色user / admin,created_atDATETIMEDEFAULTCURRENT_TIMESTAMPCOMMENT用户创建时间)COMMENT用户信息表;设计要点id使用 BIGINT 类型支持大规模用户username唯一索引保证用户名不重复password存储加密后的密码不存储明文role支持权限分级默认为普通用户3.2 仓库信息表repository记录用户提交的代码仓库信息。CREATETABLErepository(idBIGINTPRIMARYKEYAUTO_INCREMENTCOMMENT仓库ID,user_idBIGINTNOTNULLCOMMENT所属用户ID,repo_nameVARCHAR(200)COMMENT仓库名称,repo_urlVARCHAR(300)NOTNULLCOMMENT仓库URL地址,languageVARCHAR(50)COMMENT主要编程语言,fork_countINTDEFAULT0COMMENTFork 数量,star_countINTDEFAULT0COMMENTStar 数量,created_atDATETIMEDEFAULTCURRENT_TIMESTAMPCOMMENT仓库记录创建时间,FOREIGNKEY(user_id)REFERENCESuser(id))COMMENT代码仓库信息表;设计要点外键关联user_id建立用户与仓库的归属关系存储fork_count和star_count便于评估仓库影响力language字段用于标识主要编程语言支持多语言筛选3.3 分析任务表analysis_task核心表之一记录每一次代码分析任务的执行情况。CREATETABLEanalysis_task(idBIGINTPRIMARYKEYAUTO_INCREMENTCOMMENT分析任务ID,repo_idBIGINTNOTNULLCOMMENT关联的仓库ID,commit_hashVARCHAR(100)COMMENT分析对应的提交版本,statusVARCHAR(20)COMMENT任务状态PENDING / RUNNING / SUCCESS / FAILED,total_filesINTCOMMENT分析的文件总数,total_linesINTCOMMENT分析的总代码行数,start_timeDATETIMECOMMENT任务开始时间,end_timeDATETIMECOMMENT任务结束时间,created_atDATETIMEDEFAULTCURRENT_TIMESTAMPCOMMENT任务创建时间,FOREIGNKEY(repo_id)REFERENCESrepository(id))COMMENT代码分析任务表;设计要点status字段追踪任务生命周期待处理→执行中→成功→失败commit_hash记录具体分析的代码版本支持版本追溯时间字段记录任务耗时便于性能监控3.4 仓库级质量指标结果表metric_result存储仓库级别的汇总质量指标是质量评估的核心数据来源。CREATETABLEmetric_result(idBIGINTPRIMARYKEYAUTO_INCREMENTCOMMENT指标结果ID,task_idBIGINTNOTNULLCOMMENT关联的分析任务ID,-- 基础统计指标code_linesINTCOMMENT有效代码行数,comment_linesINTCOMMENT注释行数,blank_linesINTCOMMENT空行数,comment_densityDOUBLECOMMENT注释密度注释行 / 总行数,-- 复杂度指标avg_cyclomatic_complexityDOUBLECOMMENT平均圈复杂度,high_complexity_func_countINTCOMMENT高复杂度函数数量,-- 可维护性指标duplication_rateDOUBLECOMMENT代码重复率,naming_violation_countINTCOMMENT命名规范违规数量,-- 健壮性指标static_warning_countINTCOMMENT静态分析警告数量,-- 综合评分quality_scoreDOUBLECOMMENT综合质量评分0~100,created_atDATETIMEDEFAULTCURRENT_TIMESTAMPCOMMENT指标生成时间,FOREIGNKEY(task_id)REFERENCESanalysis_task(id))COMMENT仓库级代码质量指标表;设计要点指标维度覆盖基础统计、复杂度、可维护性、健壮性四大类quality_score是综合评分的归一化结果便于直观比较总计实现10 项核心指标满足任务书要求≥8项3.5 文件级指标表file_metric细粒度到文件级别的指标用于定位具体问题文件。CREATETABLEfile_metric(idBIGINTPRIMARYKEYAUTO_INCREMENTCOMMENT文件指标ID,task_idBIGINTNOTNULLCOMMENT关联的分析任务ID,file_pathVARCHAR(500)COMMENT文件相对路径,code_linesINTCOMMENT文件代码行数,comment_densityDOUBLECOMMENT文件注释密度,cyclomatic_complexityDOUBLECOMMENT文件平均圈复杂度,warning_countINTCOMMENT静态分析警告数,created_atDATETIMEDEFAULTCURRENT_TIMESTAMPCOMMENT记录生成时间,FOREIGNKEY(task_id)REFERENCESanalysis_task(id))COMMENT文件级代码质量指标表;设计要点支持问题定位到具体文件file_path存储相对路径便于跨平台处理为前端提供文件级别的热力图数据3.6 质量分析报告表quality_report存储大模型生成的自然语言报告。CREATETABLEquality_report(idBIGINTPRIMARYKEYAUTO_INCREMENTCOMMENT报告ID,task_idBIGINTNOTNULLCOMMENT关联的分析任务ID,model_nameVARCHAR(50)COMMENT使用的大模型名称,summaryTEXTCOMMENT整体质量总结,advantagesTEXTCOMMENT代码优点分析,problemsTEXTCOMMENT主要问题说明,suggestionsTEXTCOMMENT改进建议,created_atDATETIMEDEFAULTCURRENT_TIMESTAMPCOMMENT报告生成时间,FOREIGNKEY(task_id)REFERENCESanalysis_task(id))COMMENT代码质量分析报告表;设计要点使用 TEXT 类型存储长文本报告结构化存储总结、优点、问题、建议四部分model_name记录使用的大模型便于 A/B 测试3.7 指标明细 JSON 表metric_detail_json扩展指标存储表使用 JSON 格式灵活存储额外指标。CREATETABLEmetric_detail_json(idBIGINTPRIMARYKEYAUTO_INCREMENTCOMMENTJSON指标ID,task_idBIGINTNOTNULLCOMMENT关联的分析任务ID,metric_json JSONCOMMENT指标明细JSON 格式,created_atDATETIMEDEFAULTCURRENT_TIMESTAMPCOMMENT记录时间,FOREIGNKEY(task_id)REFERENCESanalysis_task(id))COMMENT扩展指标JSON表;设计要点使用 MySQL 8.0 的 JSON 原生类型支持动态扩展指标无需修改表结构示例 JSON 结构{function_length:{avg:15.3,max:45},depth:{max_nesting:5},unused_variables:3,potential_bugs:2}3.8 用户操作日志表operation_log记录关键操作用于审计和调试。CREATETABLEoperation_log(idBIGINTPRIMARYKEYAUTO_INCREMENTCOMMENT日志ID,user_idBIGINTCOMMENT操作用户ID,actionVARCHAR(100)COMMENT操作类型,detailVARCHAR(500)COMMENT操作详情,created_atDATETIMEDEFAULTCURRENT_TIMESTAMPCOMMENT操作时间)COMMENT用户操作日志表;四、ER图五、设计亮点总结5.1 指标维度完整设计实现了任务书要求的全部指标类别指标类别具体指标数量基础统计代码行数、注释行数、空行数、注释密度4复杂度平均圈复杂度、高复杂度函数数2可维护性代码重复率、命名规范违规数2健壮性静态分析警告数1综合评分质量评分1合计105.2 支持多粒度分析仓库级metric_result 表提供整体质量评分文件级file_metric 表定位具体问题文件扩展级metric_detail_json 支持函数级指标5.3 可扩展性强JSON 字段支持动态指标扩展模块化表设计便于功能迭代预留多仓库对比的数据结构5.4 可追溯性operation_log 记录关键操作analysis_task 记录完整的分析过程commit_hash 支持版本追溯六、后续优化方向索引优化根据查询频率添加联合索引分区策略对日志表按时间分区缓存设计引入 Redis 缓存热点数据