Skip to content

命名规范 ​

模型属性命名:存量并存,新代码走方案 A ​

先纠正一条容易误读的旧说法:本仓不是"内存一律 camelCase"。sequelize.define 已全局 开 underscored: true(src/framework/persistence/db/index.js),所以属性名写 clientId 或 client_id 都能对上 client_id 列 —— 存量因此分成两派:

风格属性名是否写 field典型位置
A(新代码按这个写)camelCase,如 appId写 field: 'app_id' 显式声明src/models/iam/、src/models/posecraft/
B(存量)snake_case,如 config_key不写,靠全局 underscoredsrc/models/console/、src/models/user/、src/models/oauth21/
  • 新增模型一律按 A:属性名 camelCase + field 显式写列名,读代码时不用去猜映射
  • 不要为了"统一"批量重命名存量模型:属性名是业务代码的调用面(DAO / service / 测试都在用), 改名要全仓同步,风险和收益不成比例
  • 数据库物理列名始终 snake_case —— 这一条没有例外

映射方式 ​

方案 A:显式 field 映射(新代码用这个) ​

js
const defineOauthApproval = (sequelize, DataTypes) => {
  const OauthApproval = sequelize.define(
    'OauthApproval',
    {
      appId: {
        type: DataTypes.STRING,
        allowNull: false,
        field: 'app_id', // 显式映射
        comment: '应用唯一标识'
      },
      lastAuthAt: {
        type: DataTypes.DATE,
        field: 'last_auth_at', // 显式映射
        comment: '最后授权时间'
      }
    },
    {
      tableName: 'oauth_user_approval',
      timestamps: true
    }
  );
  return OauthApproval;
};

export default defineOauthApproval; // 🔴 export 收拢到文件末尾(eslint 强制)

方案 B:全局 underscored: true(存量写法) ​

js
const UserRole = sequelize.define(
  'UserRole',
  {
    userId: {
      type: DataTypes.BIGINT,
      allowNull: false
      // 开启 underscored 之后,底层自动生成名为 user_id 的列
    }
  },
  {
    tableName: 'user_roles',
    underscored: true
  }
);

遗留代码渐进式重构 ​

通过 field 映射,不更改任何物理表列名即可将 JS 代码层统一回驼峰命名法:

js
const OauthClient = sequelize.define(
  'OauthClient',
  {
    clientId: {
      type: DataTypes.STRING(128),
      primaryKey: true,
      field: 'client_id', // 物理层保持旧列名
      comment: '客户端唯一标识'
    },
    clientName: {
      type: DataTypes.STRING(100),
      allowNull: false,
      field: 'client_name',
      comment: '客户端名称'
    }
  },
  {
    tableName: 'oauth_clients',
    timestamps: true
  }
);

其他命名规范 ​

类型规范示例
文件名(模型)大驼峰User.js, OauthClient.js
文件名(路由)小驼峰/kebabauth.js, user-info.js
文件名(工具)kebab-casesafe-redis.js, session-store.js
函数名小驼峰getUserById, createSession
常量大蛇形MAX_REFRESH_TOKENS
表名{app}_{功能}myapp_article, user_user
权限编码{app}:{res}:{act}fw:monitor:read
角色编码{app}_{role}fw_admin, myapp_user

Review 规范清单 ​

  • [ ] 新增模型是否走方案 A(camelCase 属性名 + field 显式写列名)
  • [ ] 表名是否遵循 {app}_{功能} 格式(存量例外:oauth_clients / session_tokens / audit_logs / sys_config / iam_user_role,不要为了对齐去改存量表名)
  • [ ] 外部 API 返回的 payload 是否遵循驼峰规范(响应体对外统一 camelCase)
  • [ ] createdAt / updatedAt 不需要逐模型配置映射:全局 underscored: true 已处理

基于 GPL-3.0 许可发布