07-数据库规范

概述

本规范基于项目现有代码实现，规定了数据库设计、表结构、字段命名、数据类型映射等相关规范。所有规范必须与现有代码保持一致，不得引入未实现的设想。

数据库选择

使用 MySQL 数据库。
连接配置支持 HikariCP 连接池。
启用 map-underscore-to-camel-case 配置，实现数据库下划线字段与 Java 驼峰属性自动映射。

表命名规范

表名采用小写字母，以 t_ 开头，后跟模块名和实体名，使用下划线分隔单词。
示例：t_user_info、t_user_token。

字段命名规范

字段名采用小写字母，使用下划线分隔单词，与 Java 属性驼峰命名对应。
示例：user_id、create_time、wx_openid。

主键规范

所有表使用 id 作为主键字段，类型为 BIGINT。
使用 MyBatis-Plus 的 ASSIGN_ID 策略（雪花算法生成 ID）。
在实体类中使用 @TableId(value = "id", type = IdType.ASSIGN_ID) 注解。

公共字段规范

所有实体类继承 BaseEntity，包含以下公共字段：
- id：主键，BIGINT。
- version：乐观锁版本号，INT，默认值为 0。
- create_user：创建者 ID，BIGINT。
- create_time：创建时间，DATETIME。
- update_user：更新者 ID，BIGINT。
- update_time：更新时间，DATETIME。
公共字段通过 @TableField 注解指定字段名和填充策略。

注：在代码中 BaseEntity 的字段命名与注解如下（与上面对应）：

@TableId(value = "id", type = IdType.ASSIGN_ID) 标记 id 字段，并使用雪花算法生成ID；返回给前端时对 Long 类型使用 ToStringSerializer 序列化。
@TableField(value = "version") @Version 用于乐观锁。
@TableField(value = "create_user", fill = FieldFill.INSERT) 表示插入时自动填充 createUser。
@TableField(value = "create_time", fill = FieldFill.INSERT) 对应 createTime 字段，类型为 LocalDateTime。
@TableField(value = "update_user", fill = FieldFill.INSERT) 与 updateUser，插入时默认填充；更新时 update_time 标注为 FieldFill.INSERT_UPDATE。

自动填充规范

使用 CustomMetaObjectHandler 实现自动填充。
插入时自动填充：create_time、update_time、create_user、update_user。
更新时自动填充：update_time、update_user。
默认创建者和更新者 ID 为 1（后续可从安全上下文中获取）。

实现说明：CustomMetaObjectHandler 在 insertFill/updateFill 方法中使用 strictInsertFill / strictUpdateFill 来填充时间和用户字段；当 createUser / updateUser 为空时，默认写入常量 currentUserInfoId = 1L。

乐观锁规范

使用 version 字段实现乐观锁。
在实体类中使用 @Version 注解。
配置 OptimisticLockerInnerInterceptor 插件。

实现说明：MybatisPlusConfig 注册了 OptimisticLockerInnerInterceptor 到 MybatisPlusInterceptor 中以启用乐观锁支持。

枚举处理规范

枚举类使用 @EnumValue 注解标记存储值。
自定义 TypeHandler 处理枚举与数据库的映射。
枚举存储为 INT 类型，使用 code 值存储。
示例：Gender 枚举存储为 1（男）、2（女）。

数据类型映射

遵循 MyBatis-Plus 默认映射规则。
字符串类型：VARCHAR。
整数类型：INT 或 BIGINT。
日期时间：DATETIME，使用 LocalDateTime。
布尔类型：根据需要映射为 TINYINT 或 BIT。

Mapper 规范

Mapper 接口继承 BaseMapper<T>。
使用 @Mapper 注解标记。

示例：

@Mapper
public interface UserInfoMapper extends BaseMapper<UserInfo> {
}

索引规范

根据查询需求添加适当索引。
主键自动创建索引。
外键字段建议添加索引。

约束规范

根据业务需求添加必要的约束，如唯一约束、非空约束等。
外键约束根据需要添加，但需注意性能影响。

数据迁移

使用 Flyway 或 Liquibase 等工具进行数据迁移（若有实现）。
迁移脚本命名规范：V{version}__{description}.sql。

注意事项

所有规范基于现有代码实现，不得引入未实现的特性。
数据库设计应遵循第三范式（3NF），但可根据性能需求适当冗余。
定期备份数据库，确保数据安全。

对外接口 ID 传输策略（补充）

说明：数据库中 id 及其它业务 ID 字段保持 BIGINT（或 Long）类型以保证唯一性与性能。但在对外 JSON 响应中，建议将此类长整型 ID 以字符串形式返回，以避免 JavaScript 的 Number 类型在表示超过 2^53-1 的整数时发生精度丢失。

实施建议：

数据库层与实体（Entity/PO）保持 Long/BigInt 类型。
在序列化到客户端时，统一使用字符串序列化：可以在响应 VO/DTO 层手动转换（record.getId().toString()），或在 Jackson 中通过 ToStringSerializer 对 Long 类型字段做统一序列化（但注意这会影响所有 Long 字段的序列化表现）。
在 ORM/Mapper 层不做改变，仅在 DTO/VO 层或全局序列化配置中做转换。

示例（使用 Jackson 注解局部控制）：

public class PhysicalDataResponse {
  @Schema(description = "记录ID，返回为字符串以避免前端精度丢失")
  @JsonSerialize(using = ToStringSerializer.class)
  private String id;
}

注意：统一序列化所有 Long 为字符串会影响日志/调试输出和部分客户端契约，如需细粒度控制建议在 VO 层显式转换并在 API 文档中说明。

07-数据库规范.md 5.6 KB Історія Запис