TypeScript JSON：JSON.parse 类型、JSON 转接口与导入

JSON.parse 返回 any，所以无论你把结果赋给什么类型，TypeScript 都会接受。这让为解析后的 JSON 标注类型只需要一行代码，但也意味着这个类型是你做出的承诺，而不是编译器检查过的东西：

interface User {
  name: string;
  age: number;
}

const text = '{"name":"Ada","age":36}';
const user: User = JSON.parse(text); // JSON.parse returns any

console.log(user.name.toUpperCase(), user.age + 1); // ADA 37

// The annotation is a promise, not a check:
const wrong: User = JSON.parse('{"name":"Bob","age":"41"}');
console.log(wrong.age + 1); // 411, a string concatenation

第二个对象中的 age 是字符串 "41"。TypeScript 仍然认为它是 number，因为 any 可以赋值给任何类型，于是程序打印出 411。如果 JSON 是你自己的代码刚刚生成的，这样标注没有问题。如果数据来自请求、文件或本地存储，就要校验它。

解析为 unknown

把结果的类型标注为 unknown，编译器就会坚持要求你在使用任何属性之前先做检查：

// This does not compile: unknown must be narrowed before use.
const data: unknown = JSON.parse('{"name":"Ada"}');

console.log(data.name);

错误是 index.ts(4,13): error TS18046: 'data' is of type 'unknown'.。之后你写下的每一项检查都会把 data 再收窄一点。

用类型守卫校验

类型守卫是返回 value is User 的函数。当它返回 true 时，TypeScript 从此把这个值当作 User，而函数内部的检查都是真正的运行时检查：

interface User {
  name: string;
  age: number;
}

function isUser(value: unknown): value is User {
  return (
    typeof value === "object" &&
    value !== null &&
    "name" in value &&
    typeof value.name === "string" &&
    "age" in value &&
    typeof value.age === "number"
  );
}

function parseUser(text: string): User {
  const data: unknown = JSON.parse(text);
  if (!isUser(data)) {
    throw new Error("Not a valid user: " + text);
  }
  return data; // narrowed to User
}

console.log(parseUser('{"name":"Ada","age":36}')); // { name: 'Ada', age: 36 }
try {
  parseUser('{"name":"Bob","age":"41"}');
} catch (e) {
  console.log(e instanceof Error ? e.message : e); // Not a valid user: {"name":"Bob","age":"41"}
}

格式错误的文本会让 JSON.parse 本身抛出 SyntaxError，所以实际代码还要用 try/catch 包住它。对于大型或嵌套的数据，手写的类型守卫会变得很长；Zod 或 Valibot 这类 schema 库让你只声明一次形状，就能同时得到校验器和 TypeScript 类型。

JSON 转 TypeScript 接口

把 JSON 示例转换成类型是一件机械的工作。假设有这样一个响应：

{
    "id": 42,
    "title": "Learn TypeScript",
    "done": false,
    "owner": { "id": 7, "name": "Ada" },
    "tags": ["study", "ts"],
    "dueDate": "2024-03-15T10:30:00Z",
    "notes": null
}

把每个值对应到它的类型，给嵌套对象写单独的接口，并标出可能变化的部分：

interface Owner {
  id: number;
  name: string;
}

interface Task {
  id: number;
  title: string;
  done: boolean;
  owner: Owner;         // nested object: its own interface
  tags: string[];       // array of strings
  dueDate: string;      // JSON has no dates: it is an ISO string
  notes: string | null; // null in this sample, text in others
  priority?: number;    // missing in this sample, present in others
}

const task: Task = {
  id: 42,
  title: "Learn TypeScript",
  done: false,
  owner: { id: 7, name: "Ada" },
  tags: ["study", "ts"],
  dueDate: "2024-03-15T10:30:00Z",
  notes: null,
};

console.log(task.owner.name, task.tags.length, task.priority ?? "none"); // Ada 2 none

仅凭一个示例无法判断哪些字段是可选的或可能为 null。在确定 ? 和 | null 之前，多看几个响应，或者查阅 API 的文档。

日期与 reviver

JSON 没有日期类型，所以日期以字符串的形式到达。JSON.parse 的第二个参数 reviver 会对每个键调用一次，可以用它把日期重建出来：

interface Order {
  id: number;
  placedAt: Date;
}

const text = '{"id":7,"placedAt":"2024-03-15T10:30:00.000Z"}';

const order: Order = JSON.parse(text, (key, value) =>
  key === "placedAt" ? new Date(value) : value
);

console.log(order.placedAt instanceof Date, order.placedAt.getUTCHours()); // true 10
console.log(JSON.stringify(order, null, 2));

reviver 的 value 参数是 any，结果也是 any，所以 Order 类型仍然是被信任的，而不是被检查的。JSON.stringify(order, null, 2) 用两个空格缩进输出，并把 Date 转回 ISO 字符串。

JSON.stringify 会丢失什么

JSON.stringify 的返回类型是 string。它转换的值并不总能原样还原，而类型不会提醒你：

interface Meeting {
  title: string;
  at: Date;
  tags: Set<string>;
}

const meeting: Meeting = {
  title: "Launch",
  at: new Date("2024-03-15T10:30:00Z"),
  tags: new Set(["release"]),
};

const json = JSON.stringify(meeting);
console.log(json); // {"title":"Launch","at":"2024-03-15T10:30:00.000Z","tags":{}}

const back = JSON.parse(json);
console.log(typeof back.at, back.tags); // string {}

const nothing: string = JSON.stringify(undefined); // typed string...
console.log(nothing); // ...but the value is undefined

运行时的规则和普通 JavaScript 相同，详见 JavaScript 中的 JSON。

表示任意 JSON 值的类型

当代码要处理任意 JSON 时，可以用一个递归类型准确描述 JSON 能容纳的内容，并拒绝它不能容纳的值：

type JsonValue =
  | string
  | number
  | boolean
  | null
  | JsonValue[]
  | { [key: string]: JsonValue };

function countLeaves(value: JsonValue): number {
  if (Array.isArray(value)) {
    return value.reduce((n: number, v) => n + countLeaves(v), 0);
  }
  if (typeof value === "object" && value !== null) {
    return Object.values(value).reduce((n: number, v) => n + countLeaves(v), 0);
  }
  return 1;
}

const doc: JsonValue = { name: "Ada", langs: ["en", "fr"], address: { city: "London", zip: null } };
console.log(countLeaves(doc)); // 5

// @ts-expect-error a Date is not a JSON value
const bad: JsonValue = { at: new Date() };

如果没有那条注释，最后一行就是编译错误，因为 Date 对象不是 JsonValue。

导入 .json 文件

.json 文件可以像模块一样导入，TypeScript 会根据文件内容推断它的类型：

{ "name": "app", "port": 8080, "tags": ["a"] }

// CommonJS output, or a bundler
import config from "./config.json";
const port: number = config.port; // typed from the file: number

// An ES module under module: nodenext
import settings from "./config.json" with { type: "json" };

在 TypeScript 7 中，当 module 设为 nodenext、node20、commonjs、esnext 或 preserve 时，这不需要额外设置。在 node16 和 node18 下，它会报错 TS2732：Cannot find module './config.json'. Consider using '--resolveJsonModule' to import module with '.json' extension.，直到你加上 "resolveJsonModule": true；把它设为 false 则会在所有情况下关闭 JSON 导入。在 nodenext 或 node20 下的 ES 模块中，导入需要 with { type: "json" } 属性（缺少时报错 TS1543），并且只允许默认导入（import { port } 会报错 TS1544）。tsc 会把导入的 .json 文件复制到 outDir，放在编译出的 JavaScript 旁边。