写给开发者的数据库设计规范指南（团队实战版基础篇）

数据库设计是软件系统的核心基础，其规范性直接影响系统的性能、稳定性与可维护性。为保障各类产品在数据结构和系统架构上的一致性，我们团队根据多年项目经验制定了本《数据库设计规范》。

该规范已在多个产品中落地实践，包括 **qKnow 知识平台、qData 数据中台、qModel 模型管理平台** 等，成为统一的数据库设计标准。通过严格的规范化设计，团队在多项目并行开发中能够保持清晰一致的结构，显著提升系统质量与可扩展性。

---

## 一、模块设计

### 1. 模块划分规范

模块划分是数据库设计的基础环节，应以**业务逻辑清晰**、**结构合理**、**易于维护与扩展**为原则，确保系统在开发、迭代及后期运维中的可持续性。

- **业务驱动**：模块划分应基于实际的业务需求，确保每个模块对应一个明确的功能或业务流程，避免人为拆分或随意堆叠。 **示例：**

* 用户管理模块（User Management Module）负责用户注册、登录、角色分配等。 * 项目管理模块（Project Management Module）负责项目信息维护、任务分配、进度跟踪。 * 报表统计模块（Report Module）负责数据统计与可视化展示。 - **高内聚低耦合**：各模块之间的耦合应尽量降低，确保模块内部功能的高内聚性。比如，用户管理模块（um）不应直接依赖项目管理模块（pm）的表结构，而应通过接口或服务层交互。 **说明：** 如果一个模块需要频繁调用另一个模块的接口，说明划分可能存在问题，应重新审视职责边界。

- **分层设计**：模块划分可根据业务逻辑和功能层次进行设计，通常包括： - **基础层**：如数据库交互、通用工具类； - **逻辑层**：如业务规则计算、状态机处理； - **应用层**：如用户接口、API服务、前端对接逻辑。分层结构有助于系统解耦、测试隔离和分布式部署。

- **均衡性**：模块划分应尽量均衡，避免某些模块过大（如包含上百张表），影响后期的维护和扩展。建议单个模块所辖表数量不超过30张，若超出应考虑进一步拆分。

- **灵活性与扩展性**：模块设计应考虑到未来可能的扩展或变更，避免过度耦合，保持模块的灵活性和扩展性。例如，用户模块未来可能需要支持多租户，应在设计初期预留 tenant_id 字段或采用独立 schema 方案。

### 2. 模块命名规范

良好的模块命名是数据库可读性和可维护性的基础，模块命名应遵循**统一、简洁、有意义**的原则，确保团队成员一目了然。

- **简洁且有意义**：模块名称应简洁且能清晰表达模块的功能，避免过长或过于抽象的命名。 **示例：**

* 用户管理模块 → `user` 或 `um` * 项目管理模块 → `project` 或 `pm`

- **使用缩写**：由于模块名将作为表名的前缀，命名时应简化为适当的缩写，确保不超过合理长度（建议2~4个字母）。常见示例： | 模块名称 | 缩写 | 示例表名 | | ------ | -- | ---------- | | 用户管理模块 | um | um_user | | 项目管理模块 | pm | pm_project | | 系统配置模块 | sc | sc_config |

- **避免冗余**：命名中避免使用“系统”、“管理”等冗余词汇，应侧重反映模块的核心功能。 **不推荐：** `user_manage_system` **推荐：** `um_user`

- **统一命名规则**：所有项目必须采用统一的命名规范，避免因不同团队或开发人员命名方式不一致而影响维护性。建议在项目启动阶段由架构组统一发布模块缩写对照表。

---

## 二、数据库命名规范

### 1. 环境区分命名

为保障开发、测试、生产环境的数据隔离与部署安全，数据库命名必须严格区分环境：

- **开发库**：`[项目代号]_dev` 示例：`qData_dev`、`qKnow_dev` - **测试库**：`[项目代号]_test` 示例：`qData_test`、`qModel_test` - **生产库**：`[项目代号]_prod` 示例：`qKnow_prod`、`qThing_prod`

\u003e ⚠️ 注意：严禁在生产环境中直接使用 `_dev` 或 `_test` 后缀的数据库。

### 2. 项目代号命名

- 项目代号应简短（建议2~10个字符）、唯一、具有业务识别性，便于管理和区分不同项目的数据库。 - 示例：`qData`（千桐数据中台）、`qKnow`（千桐知识平台）、`qAuth`（统一身份认证平台）

### 3. 统一命名规则

- 所有环境下的数据库命名格式必须统一，确保运维人员能快速识别环境类型。- 建议在数据库创建脚本、CI/CD 配置文件中强制校验命名规范。

---

## 三、表设计

### 1. 表命名规范

- **小写字母与下划线**：所有表名必须使用小写字母，单词之间用下划线分隔。 ✅ 正确示例：`user_info`、`order_details`、`product_category` ❌ 错误示例：`UserInfo`、`ORDERDETAILS`、`user-info`

\u003e ? 若客户有特殊要求（如 Oracle 环境偏好大写），可使用 PDManer 等建模工具在导出 DDL 时统一转换大小写，但逻辑设计阶段仍以小写为准。

- **简洁且准确**：表名应简短且准确反映其存储的数据实体。示例： - `um_user`：用户管理模块中的用户主表 - `pm_project`：项目管理模块中的项目主表

- **避免业务术语泛化**：禁止使用“数据表”、“记录表”、“信息表”等模糊词汇。应聚焦实体本身，如 `user` 而非 `user_data_table`。

- **避免特殊字符和数字**：表名不得包含空格、中文、`-`、`#`、`@` 等特殊字符，也不应以纯数字开头或结尾。

- **前缀规则**：所有业务表必须以所属模块缩写作为前缀。示例： - `um_user_role_rel`（用户-角色关系表） - `om_order_history`（订单历史表） - `sm_system_config`（系统配置表）

### 2. 特殊类型表命名标识

为提升数据库可读性，特定用途的表需使用统一后缀标识：

| 表类型 | 命名后缀 | 示例 | 说明 ||----------------|------------|--------------------------|------|| 关系表 | `_rel` | `um_user_role_rel` | 多对多关联表 || 日志表 | `_log` | `sm_operation_log` | 操作日志、错误日志等 || 历史记录表 | `_history` | `om_order_history` | 用于记录数据变更历史 || 配置表 | `_config` | `sm_app_config` | 存储系统或应用级配置参数 |

\u003e ? 建议：历史表和日志表应定期归档，避免主库膨胀。

---

## 四、字段设计

### 1. 字段逻辑名命名规范（技术命名）

- **简短且明确**：字段名应体现其业务含义，如 `user_id`、`order_amount`，避免 `uid`、`amt` 等过度缩写。

- **小写字母与下划线**：字段名统一使用小写+下划线风格。 ✅ 示例：`create_time`、`request_ip`、`del_flag`

- **避免保留字**：严禁使用 SQL 保留字作为字段名，如 `order`、`group`、`desc`、`user` 等。若必须使用，需加反引号（不推荐）。

- **统一命名规则**：同一语义字段在不同表中应保持命名一致。示例：所有表中的“创建人”字段均命名为 `create_by`，而非 `creator` 或 `created_by_user`。

### 2. 字段名命名规范（业务命名 / 中文注释用）

\u003e 注：此处“字段名”指在数据库建模工具（如 PDManer、PowerDesigner）中用于显示的**逻辑字段名称**，非物理列名。

- **中文命名**：在数据模型文档或ER图中，字段应使用中文描述，确保业务人员可理解。示例： - 物理列名：`user_id` → 逻辑名称：`用户ID` - 物理列名：`create_time` → 逻辑名称：`创建时间`

- **简洁明了**：避免技术术语堆砌，如“用户唯一标识符”应简化为“用户ID”。

- **避免歧义**：如“时间”应明确为“创建时间”或“更新时间”，不可仅写“时间”。

### 3. 字段注释规范

高质量的字段注释是数据库自文档化的关键：

- **简洁明了**：注释应一句话说明字段用途。示例：`user_status` 的注释为：“用户状态：0-禁用，1-启用”

- **业务驱动**：注释应从用户或业务视角出发，而非技术实现。 ✅ 好注释：“是否接收营销短信（0-否，1-是）” ❌ 差注释：“布尔标志位，用于短信订阅”

- **注释内容应包含**： - 字段业务含义 - 枚举值说明（如有） - 是否允许为空（NULL） - 是否为主键/外键 - 默认值（如有）

- **统一风格**：建议采用如下模板： \u003e “[业务含义]。取值：[枚举说明]。[其他约束]” 示例： \u003e “订单支付状态。取值：0-未支付，1-已支付，2-已退款。非空。”

- **示例 SQL：**

```sqlCREATE TABLE um_user ( id BIGINT PRIMARY KEY COMMENT '主键ID。非空，唯一标识用户记录。', username VARCHAR(50) NOT NULL COMMENT '用户名。唯一且非空。', password VARCHAR(100) NOT NULL COMMENT '登录密码。加密存储，非空。', status TINYINT DEFAULT 1 COMMENT '用户状态。取值：0=禁用，1=启用。非空，默认1。', create_time DATETIME DEFAULT CURRENT_TIMESTAMP COMMENT '记录创建时间。默认当前时间。', update_time DATETIME DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP COMMENT '记录最后修改时间。自动更新。') ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COMMENT='用户信息表。用于存储系统用户的基本信息。';```

### 4. 字段数据类型设置规范

- **合理选择数据类型**： | 业务场景 | 推荐类型 | 示例 | |----------------------|------------------|--------------------------| | 用户ID、订单ID | BIGINT | 自增主键或雪花ID | | 用户名、邮箱 | VARCHAR(50~255) | 根据实际长度预估 | | 密码 | VARCHAR(100) | 存储加密后的字符串 | | 金额 | DECIMAL(18,2) | 避免使用 FLOAT/DOUBLE | | 创建时间 | DATETIME | 精确到秒 | | 是否删除 | TINYINT(1) | 0-否，1-是 | | 长文本（如描述） | TEXT | 不建议超过 64KB |

- **预设类型配置**：建议在数据库建模工具中预定义常用字段模板（如“标准主键”、“标准时间戳”），供设计时直接复用。

- **兼顾扩展性**：如手机号当前为11位，但未来可能支持国际号码，建议 VARCHAR(20) 而非 CHAR(11)。

- **避免过度设计**：不要为“可能将来会用到”的场景预留超大字段。例如，用户昵称通常不超过30字符，无需定义为 VARCHAR(255)。

---

## 五、字段排序原则

合理的字段顺序有助于提升可读性和查询效率。

### 1. 常规字段排序（推荐顺序）

1. **主键字段**（如 `id`） 2. **外键字段**（如 `user_id`, `project_id`） 3. **核心业务字段**（如 `username`, `order_no`, `amount`） 4. **状态/分类字段**（如 `status`, `type`, `gender`） 5. **元数据字段**（如 `create_by`, `create_time`, `update_time`, `del_flag`）

\u003e 示例：`um_user` 表字段顺序 ```sqlid,tenant_id, -- 多租户场景username,email,phone,status, -- 0-禁用 1-启用gender, -- 性别：0-未知 1-男 2-女create_by,create_time,update_time,del_flag```

### 2. 类型字段排序

- **分类字段靠前**：如 `gender`、`user_type`、`order_source` 等，便于 WHERE 条件过滤。- **枚举字段优先**：高频使用的枚举字段（如状态）建议排在业务字段之后、时间字段之前。

---

## 六、字段分组原则

### 1. 相关字段分组

- **逻辑相关字段集中放置**： - 用户基本信息：`username`, `email`, `phone`, `avatar` - 审计字段：`create_by`, `create_time`, `update_by`, `update_time` - 软删除字段：`del_flag`, `delete_time`

- **数据类型相似字段分组**： - 所有时间字段集中（`create_time`, `update_time`, `login_time`） - 所有金额字段集中（`order_amount`, `discount`, `pay_amount`）

### 2. 频繁查询字段优先

- **高频查询字段靠前**：如 `user_id`、`order_status`、`create_time` 等常用于 WHERE 或 JOIN 的字段，应置于表前部。- **索引字段显性化**：虽然字段物理位置不影响索引性能，但将索引字段靠前有助于开发人员快速识别关键字段。

---

## 附录：常见字段命名及其规范

| 序号 | 字段含义 | 字段名称 | 备注 | 类型 | 长度 ||------|----------------|------------------|------------------------------------------------------------------------------------------------------------------------------------|-------------|--------|| 1 | 分类/类别 | category | 用于表示类别或分类的字段。 | VARCHAR | 128 || 2 | 类型 | type | 用于表示类型的字段，常见于状态类型等。 | VARCHAR | 10 || 3 | 描述 | description | 用于简要描述某个数据实体的字段。SQL中多处使用 `varchar(512)`。 | VARCHAR | 512 || 4 | 介绍 | introduction | 用于详细介绍或说明某个数据实体的字段。 | TEXT | — || 5 | 编码 | code | 唯一标识编码（如：商品编码，用户编码等）。 | VARCHAR | 128 || 6 | 级别 | level | 用于表示级别、权限等级等。 | INT | — || 7 | 内容 | content | 用于存储主要的内容字段。 | TEXT | — || 8 | 排序值 | order_num | 排序字段，通常用于排序或优先级控制。 | INT | — || 9 | 状态 | status | 状态字段（如：启用/禁用，激活/冻结等）。 | CHAR | 1 || 10 | 审核状态 | audit_status | 审核状态（如：待审核、审核通过、审核拒绝）。 | CHAR | 1 || 11 | 审核人 | auditor_id | 审核人（通常是审核人的ID或用户名）。 | BIGINT | — || 12 | 审核时间 | audit_time | 表示审核的时间，通常用于记录审核的具体时间点。 | DATETIME | — || 13 | 名称 | name | 用于表示名称字段，如用户姓名，项目名称等。 | VARCHAR | 128 || 14 | 手机号 | phone | 手机号码字段。 | VARCHAR | 20 || 15 | 邮箱 | email | 邮箱字段。 | VARCHAR | 100 || 16 | 地址 | address | 地址字段。 | VARCHAR | 255 || 17 | 性别 | gender | 性别字段（如：男/女）。 | TINYINT | 1 || 18 | 年龄 | age | 年龄字段。 | INT | — || 19 | 生日 | birthday | 出生日期字段。 | DATE | — || 20 | 头像 | avatar | 头像字段。 | VARCHAR | 256 || 21 | 创建人 | create_by | 记录创建人的姓名。 | VARCHAR | 32 || 22 | 创建人id | creator_id | 记录创建人的id。 | BIGINT | — || 23 | 创建时间 | create_time | 记录创建时间字段。 | DATETIME | — || 24 | 更新人 | update_by | 记录最后更新人的姓名。 | VARCHAR | 32 || 25 | 更新人id | updater_id | 记录最后更新人的id。 | BIGINT | — || 26 | 更新时间 | update_time | 记录最后更新时间字段。 | DATETIME | — || 27 | 删除人 | delete_by | 软删除字段，表示记录删除者的姓名。 | VARCHAR | 32 || 28 | 删除人id | deleter_id | 软删除字段，表示记录删除者的id。 | BIGINT | — || 29 | 删除时间 | delete_time | 软删除字段，表示记录删除的时间。 | DATETIME | — || 30 | 是否删除 | del_flag | 软删除标志（0: 未删除，1: 已删除）。 | VARCHAR | 1 || 31 | 是否有效 | valid_flag | 用于表示是否有效（0: 无效，1: 有效）。 | VARCHAR | 1 || 32 | 是否锁定 | lock_flag | 用于表示是否被锁定（0: 未锁定，1: 已锁定）。 | VARCHAR | 1 || 33 | 是否启用 | enable_flag | 0表示禁用，1表示启用。 | CHAR | 1 || 34 | 是否必填 | require_flag | 用于表示字段是否为必填项，（0: 不必填，1: 必填）。 | VARCHAR | 1 || 35 | 备注 | remark | 用于补充说明或备注信息。 | VARCHAR | 512 || 36 | 父级ID | parent_id | 记录的父级ID，用于树状结构或层级关系的父节点标识。 | BIGINT | — || 37 | 子级ID | child_id | 用于树状结构或层级关系的子节点标识。 | BIGINT | — || 38 | 路径 | path | 用于存储路径信息，如文件路径，URL路径等。 | VARCHAR | 256 || 39 | 关联ID | related_id | 关联其他实体的ID（如：订单关联的用户ID）。 | BIGINT | — || 40 | 操作类型 | action_type | 操作的类型（如：添加、删除、更新等）。 | CHAR | 1 || 41 | 权限 | permission | 权限字段。 | VARCHAR | 100 || 42 | 权限组 | role_group | 权限组字段（例如角色分配）。 | VARCHAR | 100 || 43 | 文件名 | file_name | 文件的名称。 | VARCHAR | 128 || 44 | 文件大小 | file_size | 文件的大小。 | BIGINT | — || 45 | 文件路径 | file_path | 文件存储路径。 | VARCHAR | 256 || 46 | 文件类型 | file_type | 文件类型（如：pdf，jpg，png等）。 | VARCHAR | 32 || 47 | 过期时间 | expiry_date | 表示某个数据是否过期的时间字段。 | DATETIME | — || 48 | 时间戳 | timestamp | 用于记录时间戳。 | DATETIME | — || 49 | 请求来源 | source | 请求来源字段。 | CHAR | 1 || 50 | 请求参数 | params | 请求参数字段。 | TEXT | — || 51 | 请求IP | request_ip | 请求来源IP地址。 | VARCHAR | 45 || 52 | IP地址 | ip_address | 存储IP地址字段。 | VARCHAR | 45 || 53 | 版本号 | version | 数据版本字段，记录版本号。 | INT | — || 54 | 是否默认 | default_flag | 是否为默认值字段（0: 否，1: 是）。 | VARCHAR | 1 || 55 | 触发时间 | trigger_time | 触发事件的时间。 | DATETIME | — || 56 | 响应时间 | response_time | 响应事件的时间。 | DATETIME | — || 57 | 访问次数 | visit_count | 记录访问次数。 | INT | — || 58 | 验证信息 | verification_info| 用于存储验证信息（如验证码）。 | VARCHAR | 100 || 59 | 唯一标识符 | uuid | 唯一标识符，常用于分布式系统中。 | VARCHAR | 36 || 60 | 序列号 | serial_no | 常用于物品、订单、产品等的唯一编号。 | VARCHAR | 64 || 61 | 标签 | tag | 记录项目、用户、产品等的标签信息。 | VARCHAR | 128 |