数据库命名规范

概述

本文档定义了 DSPlatform 项目中数据库命名规范，包括表名、字段名、索引名等的命名标准和最佳实践，确保数据库设计的一致性、可维护性和符合行业标准。

目录

• 表命名规范
• 字段命名规范
• 索引命名规范
• 外键字段命名规范
• 视图命名规范
• 存储过程/函数命名规范
• 项目实际规范
• 常见错误避免
• 与 RESTful API 的区别

表命名规范

1. 单数 vs 复数

✅ 推荐使用单数形式（主流做法）

• user（不是 users）
• order（不是 orders）
• rider_fee_rule（不是 rider_fee_rules）
• distributor_order（不是 distributor_orders）

理由：

• 表名表示实体类型，而非集合
• 符合数据库行业惯例（MySQL、PostgreSQL、Oracle）
• 避免语义混淆
• 与 ORM 框架的约定一致

2. 命名格式

• 使用小写字母和下划线（snake_case）
• 避免使用数据库保留字（如 order、group、user 等，如必须使用需加反引号）
• 表名要有意义，能清晰表达用途
• 使用表前缀：项目使用 ds_ 前缀（部署时替换 #__）

✅ 正确示例：

CREATE TABLE `user` (...);
CREATE TABLE `order_item` (...);
CREATE TABLE `rider_fee_rule` (...);
CREATE TABLE `distributor_order` (...);
CREATE TABLE `tbl_goods` (...);

❌ 错误示例：

CREATE TABLE `User` (...);           -- 不应使用大写
CREATE TABLE `userProfile` (...);     -- 不应使用驼峰
CREATE TABLE `users` (...);           -- 单数更推荐
CREATE TABLE `tbl` (...);            -- 无意义
CREATE TABLE `order` (...);          -- 保留字，需加反引号

3. 表名组成规则

• 基础表：直接使用实体名，如 user、order
• 关联表：使用 表名1_表名2 格式，如 user_address、order_goods
• 日志表：使用 表名_log 或 表名_logs 格式，如 user_balance_log、admin_logs
• 配置表：使用 sys_ 前缀，如 sys_config、sys_area

字段命名规范

1. 基本规则

• 使用小写字母和下划线（snake_case）
• 字段名要有意义，能清晰表达用途
• 布尔字段使用 is_、has_、can_ 前缀
• 时间字段统一命名
• 外键字段使用 表名_id 格式

2. 常见字段命名

主键字段

`id` INT PRIMARY KEY AUTO_INCREMENT

外键字段

`user_id` INT                    -- 用户ID
`order_id` INT                   -- 订单ID
`category_id` INT                 -- 分类ID
`store_id` INT                   -- 店铺ID

时间字段

`create_at` INT(11) DEFAULT 0        -- 创建时间（项目使用时间戳）
`update_at` INT(11) DEFAULT 0         -- 更新时间（项目使用时间戳）
`deleted_at` INT(11) DEFAULT NULL     -- 删除时间（软删除）
`pay_time` INT(11) DEFAULT 0          -- 支付时间
`delivery_time` INT(11) DEFAULT 0     -- 配送时间

状态字段

`status` TINYINT                     -- 状态（0/1 或枚举值）
`is_enabled` TINYINT(1)              -- 是否启用
`is_deleted` TINYINT(1)              -- 是否删除
`is_active` TINYINT(1)               -- 是否激活
`has_verified` TINYINT(1)            -- 是否已验证

排序字段

`sort` INT                           -- 排序顺序
`sort_order` INT                     -- 排序顺序（备用）
`display_order` INT                  -- 显示顺序

金额字段

`price` DECIMAL(10,2)                -- 价格
`amount` DECIMAL(10,2)               -- 金额
`balance` DECIMAL(10,2)              -- 余额
`fee` DECIMAL(10,2)                  -- 费用
`discount_amount` DECIMAL(10,2)      -- 优惠金额

3. 字段命名示例

✅ 正确示例：

CREATE TABLE `user` (
  `id` INT PRIMARY KEY AUTO_INCREMENT,
  `username` VARCHAR(50) NOT NULL,
  `email` VARCHAR(100),
  `mobile` VARCHAR(20),
  `is_active` TINYINT(1) DEFAULT 1,        -- 布尔字段
  `has_verified` TINYINT(1) DEFAULT 0,     -- 布尔字段
  `status` TINYINT(1) DEFAULT 1,            -- 状态字段
  `create_at` INT(11) DEFAULT 0,            -- 创建时间
  `update_at` INT(11) DEFAULT 0,            -- 更新时间
  `deleted_at` INT(11) DEFAULT NULL         -- 软删除
);

❌ 错误示例：

CREATE TABLE `user` (
  `ID` INT,                    -- 不应使用大写
  `userName` VARCHAR(50),      -- 不应使用驼峰
  `active` TINYINT(1),         -- 布尔字段应加前缀
  `createTime` INT(11),        -- 时间字段应统一命名
  `created_at` INT(11)          -- 项目使用 create_at 而非 created_at
);

索引命名规范

1. 主键索引

主键索引由数据库自动创建，无需手动命名。

PRIMARY KEY (`id`)

2. 唯一索引

命名格式：udx_字段名

-- 单字段唯一索引
UNIQUE KEY `udx_user_email` (`email`)
UNIQUE KEY `udx_user_username` (`username`)
UNIQUE KEY `udx_order_no` (`order_no`)

-- 复合唯一索引
UNIQUE KEY `udx_user_mobile` (`user_id`, `mobile`)

3. 普通索引

命名格式：idx_字段名

-- 单字段索引
KEY `idx_user_status` (`status`)
KEY `idx_order_user_id` (`user_id`)
KEY `idx_order_created_at` (`create_at`)

-- 复合索引：idx_字段1_字段2
KEY `idx_order_user_status` (`user_id`, `status`)
KEY `idx_order_created_status` (`create_at`, `status`)
KEY `idx_goods_store_status` (`store_id`, `status`)

4. 全文索引

命名格式：ft_字段名

FULLTEXT KEY `ft_article_title` (`title`)
FULLTEXT KEY `ft_article_content` (`content`)

5. 索引命名示例

CREATE TABLE `tbl_order` (
  `id` INT PRIMARY KEY AUTO_INCREMENT,
  `user_id` INT NOT NULL,
  `store_id` INT NOT NULL,
  `order_no` VARCHAR(50) NOT NULL,
  `status` TINYINT(1) DEFAULT 0,
  `create_at` INT(11) DEFAULT 0,
  
  -- 唯一索引
  UNIQUE KEY `udx_order_no` (`order_no`),
  
  -- 普通索引
  KEY `idx_user_id` (`user_id`),
  KEY `idx_store_id` (`store_id`),
  KEY `idx_status` (`status`),
  KEY `idx_create_at` (`create_at`),
  
  -- 复合索引
  KEY `idx_user_status` (`user_id`, `status`),
  KEY `idx_store_status` (`store_id`, `status`)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4;

外键字段命名规范

1. 核心原则

重要说明：项目中不使用数据库外键约束，数据完整性校验在应用层进行。

不使用外键约束的原因：

• 高并发场景下，外键约束会影响性能
• 需要灵活的数据操作，避免级联限制
• 分布式数据库场景，外键支持有限
• 应用层校验更灵活，便于业务逻辑控制

2. 外键字段命名规范

虽然不使用数据库外键约束，但外键字段的命名仍需遵循规范，以保持代码的一致性和可读性。

命名格式：表名_id

`user_id` INT          -- 引用 user 表的 id
`order_id` INT         -- 引用 order 表的 id
`category_id` INT      -- 引用 category 表的 id
`store_id` INT         -- 引用 store 表的 id
`merchant_id` INT      -- 引用 merchant 表的 id

3. 数据完整性保证

虽然不使用数据库外键约束，但需要在应用层保证数据完整性：

• Service 层校验：在业务逻辑中验证关联数据是否存在
• DAO 层校验：在数据访问层进行关联查询验证
• 事务控制：使用数据库事务保证操作的原子性
• 软删除处理：注意软删除场景下的关联数据查询

视图命名规范

命名格式：v_表名_用途

-- 视图示例
CREATE VIEW `v_user_summary` AS ...
CREATE VIEW `v_order_statistics` AS ...
CREATE VIEW `v_product_sales` AS ...
CREATE VIEW `v_user_order_detail` AS ...

存储过程/函数命名规范

1. 存储过程

命名格式：sp_功能描述

CREATE PROCEDURE `sp_get_user_orders`(...)
CREATE PROCEDURE `sp_calculate_order_total`(...)
CREATE PROCEDURE `sp_update_user_balance`(...)

2. 函数

命名格式：func_功能描述

CREATE FUNCTION `func_calculate_total`(...)
CREATE FUNCTION `func_format_price`(...)
CREATE FUNCTION `func_get_user_level`(...)

项目实际规范

1. 表命名规范

根据项目代码，实际规范如下：

• 使用单数形式：rider、user、order
• 使用小写和下划线：rider_fee_rule、distributor_order、tbl_goods
• 表前缀：ds_（部署时替换 #__）
• 日志表：部分使用复数，如 admin_logs、sys_access_logs

项目表名示例：

`ds_user`                    -- 用户表
`ds_rider`                   -- 骑手表
`ds_rider_fee_rule`          -- 骑手费用规则表
`ds_distributor_order`       -- 分销订单表
`ds_tbl_order`              -- 订单表
`ds_tbl_goods`              -- 商品表
`ds_admin_logs`             -- 管理员日志表
`ds_sys_access_logs`        -- 系统访问日志表

2. 字段命名规范

• 小写下划线：user_id、create_at、is_enabled
• 时间字段：create_at、update_at（项目中使用时间戳，不是 created_at）
• 软删除：is_deleted、deleted_at
• 状态字段：status、is_enabled、is_active

项目字段示例：

-- 时间字段（注意：项目使用 create_at 而非 created_at）
`create_at` INT(11) DEFAULT 0
`update_at` INT(11) DEFAULT 0
`deleted_at` INT(11) DEFAULT NULL

-- 布尔字段
`is_deleted` TINYINT(1) DEFAULT 0
`is_enabled` TINYINT(1) DEFAULT 1
`is_active` TINYINT(1) DEFAULT 1

-- 外键字段
`user_id` INT
`order_id` INT
`store_id` INT

3. 索引命名规范

• 普通索引：idx_字段名
• 唯一索引：udx_字段名
• 复合索引：idx_字段1_字段2

项目索引示例：

-- 唯一索引
UNIQUE KEY `udx_username` (`username`)
UNIQUE KEY `udx_order_no` (`order_no`)

-- 普通索引
KEY `idx_user_id` (`user_id`)
KEY `idx_status` (`status`)
KEY `idx_create_at` (`create_at`)

-- 复合索引
KEY `idx_user_status` (`user_id`, `status`)
KEY `idx_order_user_status` (`order_id`, `user_id`, `status`)

常见错误避免

1. 表命名错误

-- ❌ 避免使用
CREATE TABLE `users` (...);          -- 应使用单数
CREATE TABLE `User` (...);            -- 应使用小写
CREATE TABLE `userProfile` (...);     -- 应使用下划线
CREATE TABLE `order` (...);          -- 保留字，需加反引号

-- ✅ 推荐使用
CREATE TABLE `user` (...);
CREATE TABLE `user_profile` (...);
CREATE TABLE `order_item` (...);
CREATE TABLE `rider_fee_rule` (...);

2. 字段命名错误

-- ❌ 避免使用
`ID` INT                             -- 应使用小写
`userName` VARCHAR(50)               -- 应使用下划线
`active` TINYINT(1)                  -- 布尔字段应加前缀
`createTime` INT(11)                 -- 应使用下划线
`created_at` INT(11)                 -- 项目使用 create_at

-- ✅ 推荐使用
`id` INT
`user_name` VARCHAR(50)
`is_active` TINYINT(1)
`create_at` INT(11)

3. 索引命名错误

-- ❌ 避免使用
KEY `user_id` (`user_id`)            -- 应加 idx_ 前缀
UNIQUE KEY `email` (`email`)         -- 应加 udx_ 前缀
KEY `user_status` (`user_id`, `status`)  -- 应加 idx_ 前缀

-- ✅ 推荐使用
KEY `idx_user_id` (`user_id`)
UNIQUE KEY `udx_email` (`email`)
KEY `idx_user_status` (`user_id`, `status`)

与 RESTful API 的区别

重要说明：数据库命名规范与 RESTful API 路径命名规范是两个不同的层面，两者不需要保持一致。

数据库表名（单数）

-- 数据库表名使用单数
CREATE TABLE `rider_fee_rule` (...);
CREATE TABLE `distributor_order` (...);
CREATE TABLE `user` (...);

RESTful API 路径（复数）

// RESTful API 路径使用复数
GET /adminapi/rider/fee-rules/pages
GET /adminapi/distributor/orders/pages
GET /adminapi/users/pages

原因说明

1. 数据库层面：

   • 表名表示实体类型，使用单数更符合数据库设计惯例
   • 符合 MySQL、PostgreSQL 等主流数据库的命名习惯
   • 与 ORM 框架的约定一致

2. API 层面：

   • RESTful 规范要求资源集合使用复数形式
   • /users 表示用户集合，/users/:id 表示单个用户
   • 符合 RESTful API 设计标准

映射关系示例

数据库表名	RESTful API 路径	说明
user	/users	用户集合
rider_fee_rule	/fee-rules	费用规则集合
distributor_order	/orders	订单集合
balance_log	/balance-logs	余额日志集合

最佳实践总结

表命名

• ✅ 使用单数形式
• ✅ 使用小写字母和下划线
• ✅ 表名要有意义
• ✅ 使用表前缀（ds_）

字段命名

• ✅ 使用小写字母和下划线
• ✅ 布尔字段使用 is_/has_/can_ 前缀
• ✅ 时间字段统一命名（create_at、update_at）
• ✅ 外键字段使用 表名_id 格式

索引命名

• ✅ 普通索引：idx_字段名
• ✅ 唯一索引：udx_字段名
• ✅ 复合索引：idx_字段1_字段2

命名一致性

• ✅ 整个项目保持命名规范一致
• ✅ 新表、新字段遵循规范
• ✅ 定期审查和重构不符合规范的命名

相关文档

• 数据库设计详解
• RESTful 路由设计规范
• API 开发指南

---

最后更新：2024-01-20
维护者：DSPlatform技术团队(德尚网络)