5.9 KiB
5.9 KiB
Model 命名规范
更新时间: 2026-03-22 适用范围: app/model、app/service、app/controller 中的 app.model / ctx.model 调用
1. 目标
- 统一 model 文件名、运行时 key、defineName、tableName、关联 alias 的命名规则。
- 将“可直接收敛的风格问题”和“会影响业务语义的结构问题”拆开处理。
- 为阶段 4 的关联规范化和阶段 5 的模型能力清理提供稳定基线。
2. 五层命名对象
当前仓库里,单个模型至少同时存在以下 5 个命名层:
- 文件名: app/model 下的文件名。
- 运行时 key: 代码里通过 app.model.Xxx / ctx.model.Xxx 使用的名称。
- defineName: Sequelize 的 app.model.define(name, attributes, options) 第一个参数。
- tableName: options.tableName,对应数据库真实对象名。
- alias: 关联查询里的 as 字段。
后续规范要求这 5 层职责分离,不再互相混用。
3. 统一规则
3.1 文件名
- 一律使用 snake_case。
- 文件名表达“模型职责”,不表达数据库前缀。
- 工厂模型必须以 _factory 结尾。
- 除非是稳定历史兼容项,否则不在文件名中保留 wms 前缀。
示例:
- account_store_employee.js
- platform_setting.js
- order_delivery_factory.js
3.2 运行时 key
- 一律使用 PascalCase。
- 运行时 key 由文件名去掉扩展名后转为 PascalCase。
- 这是 service/controller/model 之间的主兼容面,优先级高于 defineName。
- 工厂模型保留 Factory 后缀。
示例:
- account_store_employee.js -> AccountStoreEmployee
- platform_setting.js -> PlatformSetting
- order_delivery_factory.js -> OrderDeliveryFactory
3.3 defineName
- 静态模型的 defineName 必须与运行时 key 保持一致。
- 不再使用 snake_case、wms_ 前缀或局部 lowerCamelCase 作为 defineName。
- 动态分表模型允许在运行时使用真实 tableName 作为 defineName,但外部只允许通过工厂 key 获取,不直接在业务层引用动态 defineName。
示例:
- PlatformSetting: 正确
- platform_setting: 不再推荐
- prohibitedType: 不再推荐
- wms_account_store_employee: 不再推荐
3.4 tableName
- tableName 只负责映射数据库真实对象。
- 一律保持数据库现状,不因 model 命名规范化而强制修改表名。
- 物理表继续保留现有 wms_ 前缀、复数形式、历史拼写问题。
- 视图、动态分表、历史表单独记录,不纳入静态命名统一的修改范围。
示例:
- PlatformSetting -> tableName: wms_platfrom_setting
- StockBarcode -> tableName: wms_stock_barcodes
- PrintStations -> tableName: wms_print_stations
说明:
- tableName 中的历史拼写错误属于数据库治理问题,不属于本阶段命名规范化问题。
3.5 alias
- belongsTo / hasOne 使用 lowerCamelCase 单数。
- hasMany / belongsToMany 使用 lowerCamelCase 复数。
- alias 反映关联语义,不复用旧表名或旧模型名。
- alias 必须与真实关系一致,不能把 employee 关系继续命名为 role。
示例:
- belongsTo(Store, { as: 'store' })
- hasMany(EmployeeRole, { as: 'employeeRoles' })
- belongsTo(AccountStoreEmployee, { as: 'accountStoreEmployee' })
4. 兼容优先级
按风险从高到低分三类处理:
A 类: 运行时 key 不存在或调用错误
- 必须先修。
- 这类问题会直接导致运行时取不到模型,或拿到错误关联。
- 典型例子:
- AccountStoreRole
- WmsOrderDeliveryFactory
- WmsOrderItemsFactory
B 类: defineName 不规范但运行时可用
- 可分批修。
- 前提是 tableName 已显式声明,且不存在依赖 defineName 字符串的外部逻辑。
- 典型例子:
- platform_setting
- qimen_app
- qimen_log
- prohibitedType
- stock_barcodes
C 类: alias 与业务语义不一致
- 必须与阶段 4 一起处理。
- 不能只改 alias 文本,需要一起核对外键、include、返回结构。
- 典型例子:
- accountStoreRoles
- accountStoreRole
- employeeRole
5. 仓库内落地规则
5.1 本项目允许保留的历史兼容项
以下项目前阶段不因“风格统一”而强制改文件名:
- print_stations.js
- 原因: 运行时大量使用 PrintStations,且 tableName 为 wms_print_stations。
- store_join.js
- 原因: 运行时与 defineName 已一致,当前主要问题不在命名层。
- order_delivery_factory.js / order_items_factory.js
- 原因: 工厂职责明确,外部兼容面稳定。
5.2 本项目必须执行的统一动作
- 所有静态模型的 defineName 逐步收敛到 PascalCase 运行时 key。
- 所有业务代码统一通过 ctx.model.Xxx / app.model.Xxx 的 PascalCase key 调用。
- 任何 include/as 字段都必须与当前模型关联定义一致。
- 不再新增任何带 wms 前缀的 defineName。
- 不再新增任何与真实语义不一致的 alias。
6. 参考示例
6.1 标准静态模型
- 文件名: platform_setting.js
- 运行时 key: PlatformSetting
- defineName: PlatformSetting
- tableName: wms_platfrom_setting
6.2 标准关联模型
- 文件名: account_store_employee.js
- 运行时 key: AccountStoreEmployee
- defineName: AccountStoreEmployee
- tableName: wms_account_store_employee
- alias:
- belongsTo(Account, { as: 'account' })
- belongsTo(Store, { as: 'store' })
- hasMany(EmployeeRole, { as: 'employeeRoles' })
6.3 标准工厂模型
- 文件名: order_delivery_factory.js
- 运行时 key: OrderDeliveryFactory
- 对外入口:
- ctx.model.OrderDeliveryFactory.getCurrentModel(warehouseId)
- ctx.model.OrderDeliveryFactory.getHistoryModel(warehouseId)
- 约束:
- 业务代码不直接引用动态表 defineName。
7. 执行边界
- 本阶段先统一标准、映射和影响面,不直接大规模改名。
- 运行时 key 修复优先于 defineName 收敛。
- alias 修复必须与关联关系校验一起推进。
- 数据库表名不在本阶段统一修改范围内。