前言

JSON是现代应用中最常用的数据交换格式，@pura/harmony-utils 的 JSONUtil 封装了JSON解析和转换方法，提供了比原生JSON更安全便捷的操作。本文将从API说明、代码实战、进阶用法、常见问题等多个维度进行全面讲解，帮助开发者快速掌握并应用到实际项目中。

一、JSONUtil核心API

JSONUtil 提供了以下JSON操作方法：

方法	说明	返回类型	使用场景
parse(str)	安全解析JSON	Object	数据解析
stringify(obj)	安全序列化	string	数据传输
parseArray(str)	解析JSON数组	T[]	列表解析
getString(obj, key)	安全获取字符串	string	属性读取
getNumber(obj, key)	安全获取数字	number	属性读取
getBoolean(obj, key)	安全获取布尔值	boolean	属性读取

1.1 核心特性

• 简洁易用：封装复杂逻辑为一行调用，降低使用门槛
• 类型安全：完整的TypeScript类型定义，编译期即可发现错误
• 异常处理：安全解析不会因格式错误导致崩溃
• 安全取值：getString/getNumber/getBoolean避免空指针

1.2 JSONUtil与原生JSON对比

特性	原生JSON	JSONUtil
解析异常	抛出异常	安全返回null
类型获取	需手动判断	提供类型方法
数组解析	需类型断言	专用方法
空值处理	undefined	默认值

二、完整使用步骤

2.1 安装依赖

ohpm install @pura/harmony-utils

2.2 安全解析JSON

import { JSONUtil } from '@pura/harmony-utils';

Button('安全解析JSON')
  .width('100%')
  .onClick(() => {
    try {
      let json = '{"name":"张三","age":25}';
      let obj = JSONUtil.parse(json);
      this.result = `解析成功 ✅\nname: ${obj.name}\nage: ${obj.age}`;
    } catch (e) {
      this.result = '解析失败: ' + e;
    }
  })

2.3 安全获取属性

Button('安全获取属性')
  .width('100%')
  .onClick(() => {
    try {
      let obj = { name: '张三', age: 25, active: true };
      let name = JSONUtil.getString(obj, 'name');
      let age = JSONUtil.getNumber(obj, 'age');
      let active = JSONUtil.getBoolean(obj, 'active');
      this.result = `name: ${name}\nage: ${age}\nactive: ${active}`;
    } catch (e) {
      this.result = '异常: ' + e;
    }
  })

三、完整页面示例

import { JSONUtil } from '@pura/harmony-utils';

@Entry
@Component
struct JsonDemo {
  @State result: string = '';

  build() {
    Column({ space: 12 }) {
      Button('安全解析').width('100%').onClick(() => {
        let obj = JSONUtil.parse('{"name":"张三","age":25}');
        this.result = obj ? `name: ${obj.name}` : '解析失败';
      });
      Button('安全取值').width('100%').onClick(() => {
        let data = { name: '李四', score: 95 };
        this.result = `name: ${JSONUtil.getString(data, 'name')}\nscore: ${JSONUtil.getNumber(data, 'score')}`;
      });
      Text(this.result).fontSize(14).fontColor('#333333')
    }
    .padding(16)
  }
}

四、进阶用法

4.1 API响应处理

import { JSONUtil } from '@pura/harmony-utils';

function handleApiResponse(response: string): UserInfo | null {
  let obj = JSONUtil.parse(response);
  if (!obj) return null;
  return {
    name: JSONUtil.getString(obj, 'name'),
    age: JSONUtil.getNumber(obj, 'age'),
    active: JSONUtil.getBoolean(obj, 'active'),
  };
}

4.2 配置文件读取

function loadConfig(jsonStr: string): AppConfig {
  let obj = JSONUtil.parse(jsonStr) || {};
  return {
    theme: JSONUtil.getString(obj, 'theme') || 'light',
    fontSize: JSONUtil.getNumber(obj, 'fontSize') || 14,
  };
}

五、注意事项

1. 安全解析：parse方法对无效JSON安全返回null
2. 类型转换：getString等方法会尝试类型转换
3. 默认值：属性不存在时返回类型的默认值
4. 初始化依赖：使用前需确保 AppUtil.init() 已调用
5. 嵌套对象：安全取值只支持一级属性

六、常见问题

Q1: parse解析失败返回什么？

安全解析失败返回null，不会抛出异常。

Q2: getString对数字属性返回什么？

会尝试将数字转为字符串，如 25 返回 “25”。

Q3: parseArray支持泛型吗？

支持，可以指定数组元素类型。

Q4: 如何获取嵌套对象的属性？

需要先获取外层对象，再逐层取值。

总结

JSONUtil 的JSON解析和转换方法为数据处理提供了安全便捷的支持。本文详细介绍了核心API、使用步骤、完整示例、进阶用法以及常见问题的解决方案。开发者可以利用这些方法安全地解析JSON和获取属性值。

本文基于 @pura/harmony-utils 工具库，更多功能请参考官方文档与后续系列文章。