Sequelize 中实现自定义 JSON 序列化的最佳实践

2025-05-05 00:18:21作者：彭桢灵Jeremy

Feature-rich ORM for modern Node.js and TypeScript, it supports PostgreSQL (with JSON and JSONB support), MySQL, MariaDB, SQLite, MS SQL Server, Snowflake, Oracle DB, DB2 and DB2 for IBM i.

项目地址：https://gitcode.com/gh_mirrors/se/sequelize

在现代 Web 开发中，数据序列化是一个常见需求。作为 Node.js 生态中最流行的 ORM 之一，Sequelize 提供了基础的 toJSON() 方法用于模型实例的序列化。然而，开发者经常需要更精细的控制，比如隐藏敏感字段、格式化特定属性等。

为什么需要自定义序列化

在实际项目中，我们经常会遇到以下场景：

隐藏敏感信息（如密码、API密钥等）
格式化特定字段（如部分隐藏邮箱、电话号码等）
控制字段大小写转换（camelCase 或 snake_case）
处理嵌套关联模型的序列化

虽然 Sequelize 核心团队认为 JSON 序列化不属于 ORM 的核心职责，但社区中确实存在这样的需求。理解这一点很重要，它解释了为什么 Sequelize 没有内置这些功能，以及为什么我们需要寻找其他解决方案。

自定义序列化的实现方案

方案一：继承基础模型类

最直接的方式是创建一个继承自 Sequelize Model 的基础类，重写其 toJSON() 方法：

class BaseModel extends Model {
  toJSON() {
    const data = super.toJSON();
    // 自定义处理逻辑
    return data;
  }
}

class User extends BaseModel {
  // 模型定义
}

这种方式简单直接，但缺乏灵活性，难以针对不同字段应用不同的处理规则。

方案二：使用装饰器模式

更优雅的解决方案是使用装饰器来标记字段的序列化行为：

class User extends Model {
  @JsonField({ serializer: maskEmail })
  email;
  
  @JsonField(false) // 隐藏字段
  password;
}

这种方案需要配合一个能够处理这些装饰器的序列化逻辑。虽然 Sequelize 本身不提供这种功能，但可以通过第三方库或自定义实现来达成。

推荐的解决方案：Jsonthis 库

针对 Sequelize 的序列化需求，社区开发了 Jsonthis 库，它提供了以下功能：

字段级控制：通过装饰器精确控制每个字段的序列化行为
多种处理方式：
- 完全隐藏敏感字段
- 自定义序列化函数（如部分隐藏邮箱）
- 自动大小写转换
嵌套模型处理：自动处理关联模型的序列化
空值控制：可选是否包含 null/undefined 值

使用示例

// 初始化
const jsonthis = new Jsonthis({ sequelize });

// 模型定义
class User extends Model {
  @Attribute(DataTypes.STRING)
  @JsonField({ serializer: maskEmail })
  email;
  
  @Attribute(DataTypes.STRING)
  @JsonField(false)
  password;
}

// 序列化结果
const user = await User.create({
  email: "test@example.com",
  password: "secret"
});

console.log(user.toJSON());
// 输出: { email: "t***@example.com" }