database-patterns

数据库模式 — 快速参考

硬性规则

规则	应该做	不要做
数据类型	TEXT	VARCHAR
主键	UUID	SERIAL、BIGINT
软删除	deleted_at TIMESTAMP	DELETE FROM
外键	在应用层验证	REFERENCES、ON DELETE CASCADE
标准列	id、created_at、updated_at、deleted_at	跳过其中任何一列

迁移模板

包含表、触发器和软删除部分索引的 SQL 迁移。

完整 SQL 模板请参见 code-templates.md。

暴露的表对象

继承 UUIDTable，使用 text() 而非 varchar()，添加标准时间戳列。

完整模板请参见 code-templates.md。

实体数据类

实现 Entity<Instant>，包含所有业务字段以及 createdAt、updatedAt、deletedAt。

完整模板请参见 code-templates.md。

仓储模式

使用接口 + Default* 实现。读取操作使用 db.replica，写入操作使用 db.primary。通过更新 deletedAt 实现软删除。convert() 方法将 ResultRow 映射为实体。

完整的接口和实现代码请参见 code-templates.md。

创建新表时

完整检查清单：

1. SQL 迁移文件（使用序列中的下一个编号）
2. module-repository/table/ 中的表对象
3. module-repository/entity/ 中的实体数据类
4. module-repository/constant/ 中的枚举/常量（如有需要）
5. 仓储接口 + 实现
6. 仓储的工厂 Bean
7. 仓储测试

Flyway 规则

• 绝不要添加用于填补已部署序列空缺的迁移
• 绝不要重命名已部署的迁移文件
• 迁移编号必须从最新编号开始连续递增
• 保持迁移简单且专注（每次迁移一个表）

注意事项

• 只有 id 使用 .value——其他所有列都直接使用。 row[Table.id].value 会得到 UUID，但 row[Table.projectId] 已经返回 UUID。对非 id 列添加 .value 会导致编译错误。
• gen_random_uuid() 和 uuid_generate_v4()——每个项目选用其中一种。 混用虽然可行，但会让代码审查人员困惑。检查现有迁移，确认项目使用的是哪一种。
• 如果继承 SoftDeleteTable，不要重新声明 createdAt、updatedAt、deletedAt。 这些列已继承。再次声明会导致重复列错误。
• 索引忘记加上 WHERE deleted_at IS NULL 会浪费空间。 软删除表上的每个索引都应该是部分索引。完整索引会包含无人查询的失效记录。
• 存储 JSON 的文本列在 Exposed 中仍应使用 text()。 在 Postgres 中使用 JSONB，在 Kotlin 中使用 text()，并在实体层进行序列化/反序列化。