数据库设计最佳实践：我们团队沉淀下来的规范

数据库设计的规范化是保障产品质量的重要基础。结合 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

2. 项目代号命名

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

3. 统一命名规则

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

三、表设计

1. 表命名规范

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

• 简洁且准确：表名应简短且准确反映其存储的数据实体。
  示例：

  • um_user：用户管理模块中的用户主表
  • pm_project：项目管理模块中的项目主表

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

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

• 前缀规则：所有业务表必须以所属模块缩写作为前缀。
  示例：

  • um_user_role_rel（用户-角色关系表）
  • om_order_history（订单历史表）
  • sm_system_config（系统配置表）

2. 特殊类型表命名标识

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

四、字段设计

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. 字段名命名规范（业务命名 / 中文注释用）

• 中文命名：在数据模型文档或ER图中，字段应使用中文描述，确保业务人员可理解。
  示例：

  • 物理列名：user_id → 逻辑名称：用户ID
  • 物理列名：create_time → 逻辑名称：创建时间

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

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

3. 字段注释规范

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

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

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

• 注释内容应包含：

  • 字段业务含义
  • 枚举值说明（如有）
  • 是否允许为空（NULL）
  • 是否为主键/外键
  • 默认值（如有）

• 统一风格：建议采用如下模板：

• 示例 SQL：

CREATE 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）

id,
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 的字段，应置于表前部。
• 索引字段显性化：虽然字段物理位置不影响索引性能，但将索引字段靠前有助于开发人员快速识别关键字段。

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

遵守规范，方能行稳致远。