数据库实体验证最佳实践

问题概述

在开发过程中，经常出现实体类字段与数据库表结构不一致的情况。这通常是由于在不了解真实数据库结构的情况下，凭经验或猜测添加字段导致的。

核心原则

始终以数据库文档为准：在创建或修改实体类之前，必须先查阅数据库设计文档，确保实体类与数据库表结构完全一致。

操作流程

查找数据库文档：优先查找项目中的数据库设计文档（如 .pdm 文件、.md 文档等）
对照表结构：逐一对比数据库表字段与实体类字段
验证字段映射：
- 数据库字段名 ↔ 实体类字段名（使用 @Column 注解）
- 数据类型匹配
- 必填字段标识
- 主键/外键关系
同步更新：确保实体类包含数据库表的所有字段

常见陷阱

仅凭业务逻辑推测字段名（如将 WorkTime 错误地映射为 PlanTime）
遗漏重要字段（如 CreateTime/ModifyTime、CreateUserID/ModifyUserID）
混淆相似字段（如 Status 与 RecordStatus）
字段类型不匹配（如将 int 映射为 String）

最佳实践

在项目开始阶段建立完整的数据库文档查阅习惯
创建实体类后，再次核对数据库文档确认一致性
使用工具或脚本来验证实体类与数据库表的映射关系
建立团队规范，要求所有实体类变更必须基于数据库文档

检查清单

数据库文档已查阅
实体类字段与数据库表字段一一对应
Column 注解正确映射数据库字段名
数据类型匹配
必填字段正确标识
时间戳字段（创建时间、修改时间）已包含
用户ID字段（创建用户、修改用户）已包含
状态字段（如 RecordStatus）已包含

修复策略

当发现实体类与数据库不一致时：

立即停止相关开发工作
重新查阅数据库文档
对照实体类，标识所有不匹配的字段
按照数据库文档完整更新实体类
更新相关的 Repository、Service 和 Controller 代码
重新编译和测试