58 lines
2.1 KiB
Markdown
58 lines
2.1 KiB
Markdown
|
# SQL 目录规则
|
||
|
|
|
||
|
|
## 目录定位
|
||
|
|
|
||
|
|
`sql/` 是数据库模式、迁移脚本和持久化约束的真源之一。这里的改动默认高风险，因为它们会影响已有数据、运行时兼容性、回滚能力和跨服务契约。
|
||
|
|
|
||
|
|
SQL 不是附属文档，而是生产行为的一部分。
|
||
|
|
|
||
|
|
## 第一原则
|
||
|
|
|
||
|
|
1. 数据兼容性优先。
|
||
|
|
新增、修改、删除表结构前，先考虑已有数据、旧代码、灰度过程和回滚路径。
|
||
|
|
|
||
|
|
2. 模式变更必须服务真实运行主链路。
|
||
|
|
不要在 SQL 里提前铺大量“未来可能需要”的字段和表。
|
||
|
|
|
||
|
|
3. DDL、代码、文档要同步。
|
||
|
|
字段、索引、约束、枚举、默认值变更，必须同步检查对应存储模型、接口输出和文档说明。
|
||
|
|
|
||
|
|
4. 显式优于隐式。
|
||
|
|
约束、索引、检查条件、唯一性要求应尽量在 schema 中表达，不要把关键一致性只留在应用代码里。
|
||
|
|
|
||
|
|
## 变更前必须先回答
|
||
|
|
|
||
|
|
- 这是新增表、补丁、兼容性修复，还是破坏性变更？
|
||
|
|
- 现网数据是否已经存在？
|
||
|
|
- 应用层是否已经能理解新字段/新约束？
|
||
|
|
- 如果发布失败，如何回滚或向前修复？
|
||
|
|
|
||
|
|
## 编写要求
|
||
|
|
|
||
|
|
- 文件名要体现语义和版本，不要使用含糊命名
|
||
|
|
- 注释要说明边界、用途和与其他 schema 的关系
|
||
|
|
- 对 authority、audit、outbox、账务、结算类表要特别谨慎
|
||
|
|
- Patch 脚本必须说明它修复的具体问题，不要变成长期主 schema 的隐性替代
|
||
|
|
|
||
|
|
## 验证要求
|
||
|
|
|
||
|
|
- 检查 DDL 是否可重复执行或明确说明一次性前提
|
||
|
|
- 检查约束是否与应用层枚举/状态机一致
|
||
|
|
- 索引变更要有明确查询场景，不做无根据加索引
|
||
|
|
- 涉及高并发更新时，要考虑锁、唯一键和冲突语义
|
||
|
|
|
||
|
|
## 风险重点
|
||
|
|
|
||
|
|
- 状态枚举漂移
|
||
|
|
- 乐观锁/悲观锁语义失配
|
||
|
|
- audit 字段缺失或不一致
|
||
|
|
- token / settlement / order / usage 这类关键表的唯一性与时间字段设计
|
||
|
|
- patch 覆盖正式 schema 但未同步主文档
|
||
|
|
|
||
|
|
## 禁止事项
|
||
|
|
|
||
|
|
- 不要在未评估兼容性的情况下直接改列语义
|
||
|
|
- 不要把应用层 bug 临时补丁长期固化进 schema 却不回收
|
||
|
|
- 不要让 SQL 成为代码真实行为的“另一个版本”
|
||
|
|
|