如何在 TypeScript 中将对象转换为 JSON 字符串：全面指南

2026-02-06 18:13:11 0条评论 3次阅读 0人点赞

在日常的前端开发工作中，我们经常需要与后端 API 进行数据交互，或者将本地状态保存到 LocalStorage 中。这些场景的核心操作都是序列化——即将内存中的对象转换为便于传输或存储的 JSON 格式字符串。TypeScript 作为 JavaScript 的超集，虽然在类型安全上给了我们极大的保障，但在处理 JSON 序列化时，如果不加注意，仍然会遇到不少“坑”。

在这篇文章中，我们将深入探讨在 TypeScript 中将对象转换为 JSON 字符串的各种方法。不仅仅是简单的转换，我们还会一起解决循环引用、处理特殊数据类型（如 Date）、自定义序列化逻辑以及利用高级特性（如装饰器）来优化我们的代码。无论你是初学者还是经验丰富的开发者，这篇文章都会为你提供实用的见解和最佳实践。

1 目录
2 使用 JSON.stringify()
3 使用 json-stringify-safe 库
4 使用自定义序列化函数
5 使用 TypeScript 装饰器进行序列化
6 总结与最佳实践

使用 JSON.stringify()

这是最基础也是最常用的方法。TypeScript 并没有改变 JavaScript 原生的序列化机制，而是通过类型系统帮助我们确保传递给 JSON.stringify 的对象结构是符合预期的。

我们可以按照以下步骤操作：

定义接口：描述该对象所需的属性及其类型。
声明变量：确保变量符合接口的结构。
赋值对象字面量：TypeScript 会检查它是否匹配该接口。
调用方法：在该类型化对象上调用 JSON.stringify()。

示例：基础类型转换

下面的代码演示了如何将一个包含基本数据类型的课程对象转换为 JSON 字符串。

// 定义一个接口，确保我们的数据结构是类型安全的
interface Course {
    courseName: string;
    courseFees: number;
    isActive: boolean;
}

// 声明一个符合 Course 接口的对象
const course: Course = {
    courseName: "TypeScript Mastery",
    courseFees: 2999,
    isActive: true
};

// 使用 JSON.stringify 进行转换
const jsonString: string = JSON.stringify(course);

console.log(jsonString);
// 输出: {"courseName":"TypeScript Mastery","courseFees":2999,"isActive":true}

深入理解：格式化输出

作为开发者，我们在调试时通常需要阅读 JSON 数据。JSON.stringify 提供了第三个参数，用于格式化输出，让结果更具可读性。

// 使用第三个参数进行美化格式，缩进 4 个空格
const prettyJson = JSON.stringify(course, null, 4);

console.log(prettyJson);
/*
输出:
{
    "courseName": "TypeScript Mastery",
    "courseFees": 2999,
    "isActive": true
}
*/

常见陷阱：undefined 和函数

你可能会遇到这样的情况：对象中包含 INLINECODEd7edbdb2 或函数属性。INLINECODEf1b5c257 会自动忽略它们，这在某些时候会导致数据丢失。

interface User {
    name: string;
    age?: number; // 可选属性
    greet?: () => void;
}

const user: User = {
    name: "Alice",
    age: undefined, // 显式赋值为 undefined
    greet: () => console.log("Hello!")
};

// 注意：age 和 greet 不会被包含在结果中
const userJson = JSON.stringify(user); 
console.log(userJson); 
// 输出: {"name":"Alice"}

在处理敏感数据或配置对象时，请务必注意这一特性。

使用 json-stringify-safe 库

标准的 INLINECODE8d3489d9 有一个著名的限制：它无法处理循环引用。如果你的对象结构中有相互引用（例如 A 引用 B，B 又引用 A），程序会直接抛出 INLINECODE481ae77f 错误。

让我们来看看如何解决这个问题。

场景重现：循环引用错误

interface Node {
    id: string;
    child?: Node;
    parent?: Node;
}

const parentNode: Node = { id: "parent" };
const childNode: Node = { id: "child" };

// 建立循环引用
parentNode.child = childNode;
childNode.parent = parentNode;

// 这行代码会抛出错误
// console.log(JSON.stringify(parentNode));

解决方案：引入 json-stringify-safe

为了解决这个问题，我们可以使用 json-stringify-safe 库。它能够智能地检测循环引用并用占位符替换，或者简单地忽略它们，从而防止程序崩溃。

#### 实战步骤：在 TypeScript 项目中集成

虽然这看起来是基础步骤，但在实际工程化项目中，正确的配置至关重要。

初始化项目：

    npm init -y

安装 TypeScript：

    npm install typescript --save-dev

创建配置文件：

    npx tsc --init

安装库及其类型定义：

    npm install json-stringify-safe
    npm install --save-dev @types/json-stringify-safe

#### 代码示例：安全的序列化

// 引入库，注意在 TypeScript 中推荐使用 import，但 require 也兼容
import stringifySafe from ‘json-stringify-safe‘;

interface Course {
    courseName: string;
    courseFees: number;
}

const course: Course = {
    courseName: ‘Advanced TypeScript‘,
    courseFees: 5000
};

// 即使数据结构正常，使用 stringifySafe 也是安全的，
// 这样可以防止未来数据结构变化导致的潜在崩溃
const jsonString: string = stringifySafe(course);

console.log(jsonString);
// 输出: {"courseName":"Advanced TypeScript","courseFees":5000}

何时使用这个库？

并不是所有项目都需要这个库。如果你处理的是纯粹的 DTO（数据传输对象），通常不会有循环引用。但如果你在处理复杂的领域模型、图结构或树结构（例如 DOM 树抽象），这个库是救命稻草。

使用自定义序列化函数

在某些情况下，我们可能会遇到具有嵌套结构或不可序列化属性（如 INLINECODE365bc29d 对象、INLINECODEb97b8265、INLINECODE7eabbd28 或自定义类实例）的复杂对象。标准的 INLINECODE0fb97da7 会将 Date 转换为字符串，但这不一定符合我们的格式要求（例如我们可能需要时间戳而不是 ISO 字符串）。

在这种场景下，我们可以利用 INLINECODE67a16da7 的第二个参数 INLINECODEa9bde457 来定义转换逻辑。

示例：统一处理 Date 对象

下面的代码演示了如何将 Date 对象统一转换为 UNIX 时间戳，而不是默认的 ISO 字符串，这在某些后端存储格式中更为常见。

interface Course {
    courseName: string;
    courseFees: number;
    startDate: Date;
    tags: string[];
}

const course: Course = {
    courseName: "Full Stack Development",
    courseFees: 12000,
    startDate: new Date("2024-05-01T09:00:00"),
    tags: ["frontend", "backend"]
};

// 定义一个自定义转换函数
function customReplacer(key: string, value: any) {
    // 如果值是 Date 类型，我们将其转换为时间戳
    if (value instanceof Date) {
        return value.getTime(); 
    }
    // 如果值是 undefined，我们可以选择返回 null 或其他默认值
    if (typeof value === "undefined") {
        return null;
    }
    return value;
}

const jsonString = JSON.stringify(course, customReplacer);

console.log(jsonString);
// 输出: {"courseName":"Full Stack Development","courseFees":12000,"startDate":1714520400000,"tags":["frontend","backend"]}

进阶场景：处理私有属性

在 TypeScript 中，以 INLINECODEd8b63b85 开头的私有字段或 INLINECODE1bf03813 关键字修饰的属性在序列化时行为有些微妙。虽然 INLINECODEb0881d79 属性仍会被序列化（因为 JS 运行时并不知道 TypeScript 的类型私有性），但我们可以通过 INLINECODE8ace28c8 函数来显式过滤掉我们不想暴露的字段。

interface User {
    publicId: string;
    email: string;
    _internalSecret: string; // 模拟内部字段
}

const user: User = {
    publicId: "12345",
    email: "[email protected]",
    _internalSecret: "my_secret_key"
};

// 过滤掉以 _ 开头的内部字段
function sanitizeReplacer(key: string, value: any) {
    if (typeof value === ‘string‘ && key.startsWith(‘_‘)) {
        return undefined; // 返回 undefined 会导致该属性被忽略
    }
    return value;
}

const safeUserJson = JSON.stringify(user, sanitizeReplacer);
console.log(safeUserJson);
// 输出: {"publicId":"12345","email":"[email protected]"}
// _internalSecret 被成功过滤

使用 TypeScript 装饰器进行序列化

TypeScript 装饰器提供了一种声明式的方式来修改类声明和成员的行为。在序列化方面，我们可以利用装饰器来标记需要排除的字段，或者自动管理序列化逻辑，而不需要在业务代码中显式调用复杂的 replacer 函数。这在编写 ORM 或 SDK 时非常有用。

示例：构建可序列化的类

让我们创建一个 INLINECODE8a8a4b52 装饰器和一个 INLINECODE91b619c3 装饰器。这使得类的定义本身就包含了序列化规则，代码更加整洁且易于维护。

(注意：要运行以下装饰器代码，请确保你的 INLINECODEf5b1a86a 中开启了 INLINECODE58977d8b 和 emitDecoratorMetadata 选项)

// 用于存储需要排除的属性名
const excludedProperties = new Set();

// 属性装饰器：标记某个属性不参与序列化
function Exclude(target: any, propertyKey: string) {
    excludedProperties.add(propertyKey);
}

// 方法装饰器：添加自定义的 toJSON 方法
function Serializable(constructor: T) {
    return class extends constructor {
        toJSON() {
            const obj: any = {};
            // 获取实例的所有键
            const keys = Object.keys(this);
            
            for (const key of keys) {
                // 如果该属性不在排除列表中，则进行序列化
                if (!excludedProperties.has(key)) {
                    obj[key] = (this as any)[key];
                }
            }
            return obj;
        }
    }
}

@Serializable
class UserProfile {
    username: string;
    email: string;
    
    @Exclude // 这个字段将被自动排除
    passwordHash: string;

    constructor(u: string, e: string, p: string) {
        this.username = u;
        this.email = e;
        this.passwordHash = p;
    }
}

const user = new UserProfile("dev_guru", "[email protected]", "super_secret_123");

// JSON.stringify 会自动调用对象的 toJSON 方法（如果存在）
const jsonStr = JSON.stringify(user);

console.log(jsonStr);
// 输出: {"username":"dev_guru","email":"[email protected]"}
// 注意：passwordHash 没有出现在输出中

为什么要这样做？

这种方法的优点是关注点分离。领域模型类不仅定义了数据结构，还明确定义了数据可见性的规则。当你调用 INLINECODE226ffd74 时，你不需要到处传递 INLINECODE7566c167 函数，规则已经被封装在类内部了。

总结与最佳实践

在这篇文章中，我们探讨了在 TypeScript 中处理 JSON 序列化的多种方式。从最基础的 JSON.stringify，到处理棘手的循环引用，再到利用装饰器实现声明式序列化。作为开发者，选择正确的工具至关重要。

关键要点总结：

默认总是够用的：对于大多数简单的数据传输对象（DTO），原生的 JSON.stringify 配合 TypeScript 接口定义是最高效、最安全的选择。
警惕循环引用：当你在处理图状数据结构或复杂的对象树时，务必使用 INLINECODE9f23757e 或编写自定义的 INLINECODE76e7a66c 来防止应用崩溃。
善用 replacer 参数：不要在序列化前去手动修改你的对象（例如 INLINECODEa72cda9c）。使用 INLINECODEcd128b51 函数或者 toJSON 方法可以保持数据的不变性，这是函数式编程的一个好习惯。
类型安全不等于序列化安全：TypeScript 的类型只在编译时存在。一旦代码编译为 JavaScript，任何不可序列化的数据（如函数、Symbol、undefined）都可能导致数据丢失。利用接口定义和单元测试来验证你的序列化输出。

希望这篇指南能帮助你在项目中更优雅地处理数据转换！如果你正在构建一个大型应用，建议将这些序列化逻辑封装成通用的工具类或库，以便在整个团队中复用。

投稿给我们	如何建站？
vps是什么？	如何安装宝塔？
如何通过博客赚钱？	便宜wordpress托管方案
免费wordpress主题	这些都是免费方案

豆丁博客

如何在 TypeScript 中将对象转换为 JSON 字符串：全面指南

目录

使用 JSON.stringify()

示例：基础类型转换

深入理解：格式化输出

常见陷阱：undefined 和函数

使用 json-stringify-safe 库

场景重现：循环引用错误

解决方案：引入 json-stringify-safe

何时使用这个库？

使用自定义序列化函数

示例：统一处理 Date 对象

进阶场景：处理私有属性

使用 TypeScript 装饰器进行序列化

示例：构建可序列化的类

为什么要这样做？

总结与最佳实践

相关文章美国1G带宽/1T流量高速vps $17.99/年

如何在 TypeScript 中将对象转换为 JSON 字符串：全面指南

目录

使用 JSON.stringify()

示例：基础类型转换

深入理解：格式化输出

常见陷阱：undefined 和 函数

使用 json-stringify-safe 库

场景重现：循环引用错误

解决方案：引入 json-stringify-safe

何时使用这个库？

使用自定义序列化函数

示例：统一处理 Date 对象

进阶场景：处理私有属性

使用 TypeScript 装饰器进行序列化

示例：构建可序列化的类

为什么要这样做？

总结与最佳实践

相关文章美国1G带宽/1T流量高速vps $17.99/年

常见陷阱：undefined 和函数