JSON 工具

parseJson

将一个 JSON 字符串解析为指定类型的对象。支持泛型，可确保类型安全，并提供错误处理和值转换的配置选项。

参数说明

参数名	类型	必填	说明
str	string	否	要解析的 JSON 字符串。若为空或空白，将返回 defaultValue。
options	ParseJsonOptions	否	配置项对象，详见下表。

ParseJsonOptions 配置项

属性名	类型	默认值	说明
ignoreError	boolean	false	是否忽略解析错误。若为 true，解析失败时返回 defaultValue 而不是抛出异常。
reviver	(key: string, value: any) => any	-	一个转换函数，用于在解析时转换结果（同 JSON.parse 的 reviver）。
defaultValue	any	undefined	当输入为空或解析失败（且 ignoreError 为 true）时的默认返回值。

返回值说明

• 类型：T
• 说明：
  • 成功解析时返回对应泛型类型的对象。
  • 输入为空/空白时，返回 options 中指定的 defaultValue（若未指定则返回 undefined）。
  • 若解析失败且 ignoreError 为 false（默认），则抛出异常。
  • 若解析失败且 ignoreError 为 true，则返回 options 中指定的 defaultValue。

示例

// 1. 基本用法
const jsonStr = '{"name": "Tom", "age": 25}';
const user = parseJson<{ name: string; age: number }>(jsonStr);
console.log(user); // { name: "Tom", age: 25 }

// 2. 处理空值与默认值
const empty = parseJson<any>(null, { defaultValue: { name: 'Guest' } });
console.log(empty); // { name: 'Guest' }

const emptyStr = parseJson<any>('   ', { defaultValue: '默认字符串' });
console.log(emptyStr); // "默认字符串"

// 3. 忽略错误 (不抛出异常)
const invalidJson = '{"invalid": json}';
const safeParse = parseJson<any>(invalidJson, { ignoreError: true, defaultValue: {} });
console.log(safeParse); // {} (解析失败，返回默认值)

// 4. 使用 Reviver 转换数据 (例如处理日期)
const jsonWithDate = '{"date": "2023-10-01T00:00:00.000Z"}';
const withDate = parseJson(jsonWithDate, {
  reviver: (key, value) => {
    if (key === 'date') return new Date(value);
    return value;
  },
});
console.log(withDate.date instanceof Date); // true