服务端数据库规约

1. 设计原则

1.1 基本原则

• 表设计遵循：高内聚、低耦合
• 避免过度范式化（3NF 为主，必要时适当冗余）
• 一个表只表达一个业务实体
• 禁止使用魔法字段（含义不清的字段，如：field1、data2）
• 设计必须支持未来扩展（预留扩展字段）

2. 命名规范

2.1 表命名

• 使用小写字母 + 下划线（snake_case）
• 表名必须是名词，表达业务含义
• 不使用复数
• 禁止使用数据库关键字

示例：

user
order
order_item
payment_record

2.2 字段命名

• 字段名统一使用小写 + 下划线
• 必须语义明确
• 不使用拼音
• 布尔字段以 is_ / has_ 开头

示例：

id
user_id
order_status
is_deleted
created_at
updated_at

2.3 索引命名

idx_表名_字段名
uk_表名_字段名

示例：

idx_user_phone
uk_user_email

3. 字段设计规范

3.1 主键设计

• 必须有主键

• 推荐使用：

  • bigint 自增
  • 或分布式 ID（Snowflake）

• 禁止使用业务字段作为主键

• 主键名统一：id

3.2 时间字段

必须包含：

created_at  创建时间
updated_at  更新时间

可选：

deleted_at  删除时间（软删除）

禁止：

• 使用字符串存时间
• 使用 int 代替 datetime（除非时间戳字段明确）

3.3 状态字段

状态字段必须：

• 使用整型枚举
• 不使用字符串状态

示例：

status: 0=禁用 1=启用 2=冻结

3.4 金额字段

• 使用 decimal(10,2) 或更高精度
• 禁止使用 float / double 存金额

3.5 文本字段

类型	使用场景
varchar	短文本（<=255）
text	长文本
json	结构化扩展字段

3.6 是否删除（软删除）

统一字段：

is_deleted tinyint(1) default 0

4. 索引设计规范

4.1 基本原则

• 高频查询条件必须建索引
• 外键字段建议建索引
• 联合索引遵循最左前缀原则
• 禁止滥用索引

4.2 禁止项

• 禁止对低区分度字段建索引（如：性别、状态）
• 禁止对 text/json 建普通索引（可用全文索引）

4.3 索引数量

• 单表索引不超过 5 个（特殊业务除外）
• 避免重复索引

5. 表结构设计

5.1 字段顺序建议

id
业务字段
状态字段
扩展字段
created_at
updated_at
is_deleted

5.2 表必须包含字段

id
created_at
updated_at

6. SQL 编写规范

6.1 基本要求

• 禁止 select *
• 必须明确字段列表
• SQL 关键字大写
• 表名、字段名小写

示例：

SELECT id, user_id, status
FROM order
WHERE user_id = 1001;

6.2 分页规范

必须使用 limit：

LIMIT 20 OFFSET 0

禁止：

LIMIT 1000000,20

6.3 删除规范

禁止物理删除：

DELETE FROM table;

必须使用软删除：

UPDATE table SET is_deleted=1 WHERE id=?

6.4 更新规范

禁止无条件更新：

UPDATE user SET status=1;

必须带 where：

UPDATE user SET status=1 WHERE id=?;

7. 事务规范

• 事务要短
• 禁止事务中包含远程调用
• 禁止大事务（批量上万行）
• 明确事务隔离级别（默认 READ COMMITTED）

8. 外键与约束

8.1 外键策略

推荐：

• 不使用数据库外键约束
• 使用应用层保证数据一致性

原因：

• 提高扩展性
• 避免分库分表困难
• 避免锁表

8.2 唯一约束

对业务唯一字段加唯一索引：

手机号
邮箱
订单号

9. 数据安全与权限

• 生产环境禁止使用 root 用户
• 按应用分配账号
• 严禁程序使用 DDL 权限
• 重要字段（手机号、身份证）需加密或脱敏

10. 表结构变更规范

• 禁止直接在生产库手动改表

• 所有 DDL 需走：

  • 评审
  • 版本控制
  • 变更脚本

• 必须支持回滚方案

11. 日志与审计字段（推荐）

通用审计字段：

created_by
updated_by

12. JSON 字段使用规范

• 只用于扩展字段
• 不用于高频查询条件
• 必须定义结构说明
• 不允许无限扩展

13. 大表设计建议

• 单表数据量控制在 500 万以内

• 超过需要：

  • 分表
  • 分库
  • 按时间分表

14. 示例表结构

CREATE TABLE user (
  id BIGINT PRIMARY KEY,
  username VARCHAR(50) NOT NULL,
  phone VARCHAR(20),
  status TINYINT NOT NULL DEFAULT 1,
  created_at DATETIME NOT NULL,
  updated_at DATETIME NOT NULL,
  is_deleted TINYINT NOT NULL DEFAULT 0,
  UNIQUE KEY uk_user_phone (phone),
  KEY idx_user_status (status)
);

15. 核心原则总结

• 结构清晰
• 命名统一
• 不存垃圾数据
• 不写危险 SQL
• 不靠运气保证一致性