# ZJson

**Repository Path**: HW-Commons/ZJson

## Basic Information

- **Project Name**: ZJson
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 2
- **Forks**: 1
- **Created**: 2025-02-18
- **Last Updated**: 2025-04-16

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

## 介绍

ZJsonUtil 是一款专为 JSON 和对象之间的转换设计的工具类，旨在将 JSON 或普通对象转换为具体类型的类实例。它具备以下特点：

- 兼容性：支持被 @Observed 和 @ObservedV2 修饰的类对象。
- 深拷贝：在转换过程中确保对象的深拷贝，避免引用问题。
- 自定义实现：最初依赖于 reflect-metadata 和 class-transformer 库来处理元数据和对象转换，现在自己实现，不依赖第三方库。

主要功能

- JSON 转换：将 JSON 字符串转换为指定类型的类实例。
- 对象转换：将普通 Object 对象转换为指定类型的类实例。
- 嵌套对象支持：能够处理复杂的嵌套对象结构，确保所有层级都能正确转换。
- 类型安全：通过系统提供类型检查，确保转换结果的准确性。
  使用场景
- 适用于需要频繁进行 JSON 和对象转换的项目，特别是在需要处理复杂对象结构和确保类型安全的场景中。
- 支持字段映射

## 下载安装

在每个har/hsp模块中，通过ohpm工具下载安装库：

```
ohpm install @hzw/zjson-transform
```

## 注解说明

### @Type()
- 功能：指定嵌套对象的类型元数据
- 参数：转换目标类
- 示例：`@Type(() => Father)` 指定father字段使用Father类进行转换

### @FieldMapping()
- 功能：字段映射配置
- 参数：
  - targetFieldName：目标字段名
  - mapFields：源字段名列表（支持多字段映射）
- 示例：`@FieldMapping({ targetFieldName: 'mother', mapFields: ['mon'] })`
  将mon字段映射到mother字段

## 使用方法

### 实体定义

#### 普通类
```typescript

export class Father {
  id?: number
  name?: string
}

export class Mother {
  id?: number
  name?: string
}

export class Son {
  id?: number
  name?: string
  age?: number
  @Type(() => Father)
  father?: Father | undefined
  @Type(() => Mother)
  @FieldMapping({ targetFieldName: 'mother', mapFields: ['mon'] })
  mother?: Father | undefined
  @FieldMapping({ targetFieldName: 'showTxt', mapFields: ['txt1', 'txt2'] })
  showTxt?: string | undefined
}
```

#### V1类

```typescript
export class FatherV1 {
  id?: number
  name?: string
}

export class MotherV1 {
  id?: number
  name?: string
}

export class SonV1 {
  id?: number
  name?: string
  age?: number
  @Type(() => FatherV1)
  father?: FatherV1 | undefined
  @Type(() => MotherV1)
  @FieldMapping({ targetFieldName: 'mother', mapFields: ['mon'] })
  mother?: FatherV1 | undefined
  @FieldMapping({ targetFieldName: 'showTxt', mapFields: ['txt1', 'txt2'] })
  showTxt?: string | undefined
}
```

#### V2类

```typescript
@ObservedV2
export class FatherV2 {
  @Trace id?: number
  @Trace name?: string
}

@ObservedV2
export class MotherV2 {
  @Trace id?: number
  @Trace name?: string
}

@ObservedV2
export class SonV2 {
  @Trace id?: number
  @Trace name?: string
  @Trace age?: number
  @Type(() => FatherV2)
  @Trace father?: FatherV2 | undefined
  @Type(() => MotherV2)
  @FieldMapping({ targetFieldName: 'mother', mapFields: ['mon'] })
  @Trace mother?: MotherV2 | undefined
  @FieldMapping({ targetFieldName: 'showTxt', mapFields: ['txt1', 'txt2'] })
  @Trace showTxt?: string | undefined
}
```

### 转换

1. json字符串 转 具体类型的对象

```typescript
const jsonStr = '{"id":1,"name":"儿子","txt1":"txt1","father":{"id":1,"name":"父亲"},"mon":{"id":1,"name":"母亲"}}'
const sonBeanVVV = ZJsonUtil.toBean<Son>(Son, jsonStr)
const sonBeanVV1 = ZJsonUtil.toBean<SonV1>(SonV1, jsonStr)
const sonBeanVV2 = ZJsonUtil.toBean<SonV2>(SonV2, jsonStr)
```

2. Object对象 转 具体类型的对象

```typescript
const father: Father = {
  id: 1,
  name: '父亲',
}
const son: Son = {
  id: 1,
  name: '儿子',
  father: father,
}
const sonBean2 = ZJsonUtil.toBean<Son>(Son, son)
```

3. json字符串 转 Object对象

```typescript
const sonObject = ZJsonUtil.toObject(jsonStr)
```

4. 任意对象 转 json字符串

```typescript
const sonJson = ZJsonUtil.toJson(son)

// @ObservedV2注解的对象（V2状态） 转 json字符串
// 先拿到V2的对象
const sonBeanV2 = ZJsonUtil.toBean<SonV2>(SonV2, son)

// 拿到的字段键值包含__ob_
const sonObjectV2_1 = ZJsonUtil.toJson(sonBeanV2)
// 输出如下：{"__ob_id":1,"__ob_name":"儿子","__ob_father":{"__ob_id":1,"__ob_name":"父亲"}}

// 拿到的字段键值包含不包含
const sonObjectV2_2 = ZJsonUtil.toJsonCompat(sonBeanV2)
// 输出如下：{"id":1,"name":"儿子","father":{"id":1,"name":"父亲"}}
```

5. json字符串转Object对象数组
```typescript
const jsonListErr = 'xxx'
const jsonList =
  '[{"id":1,"name":"儿子","father":{"id":1,"name":"父亲"},"mon":{"id":1,"name":"母亲"},"txt1":"txt1"},{"id":2,"name":"女儿","father":{"id":1,"name":"父亲"}}]'
const objectUndefined = ZJsonUtil.toObjectList(jsonListErr) // undefined
const objectList = ZJsonUtil.toObjectList(jsonList)
```
6. json字符串转具体类型对象数组
```typescript
const beanUndefined = ZJsonUtil.toBeanList<Son>(Son, jsonListErr) // undefined
const beanList = ZJsonUtil.toBeanList<Son>(Son, jsonList)
```

7. Object数组对象转具体类型对象数组
```typescript
const father2: Father = {
  id: 1,
  name: '父亲',
}
const sonListErr: Son = {}
const sonList: Son[] = [
  {
    id: 1,
    name: '儿子',
    father: father2,
  },
  {
    id: 2,
    name: '女儿',
    father: father2,
  },
]
const bean2Undefined = ZJsonUtil.toBeanList<Son>(Son, sonListErr) // undefined
const bean2List = ZJsonUtil.toBeanList<Son>(Son, sonList)
```

## 属性/接口说明

### ZJsonUtil 核心方法

#### toBean<T>(targetClass: new () => T, source: any): T
- 功能：将JSON或普通对象转换为指定类型的类实例
- 参数：
  - targetClass：目标类类型
  - source：源数据（可以是JSON字符串或Object）
- 返回：完全深拷贝的类实例
- 示例：`const sonBean = ZJsonUtil.toBean<Son>(Son, jsonStr)`

#### toObject(source: any): any
- 功能：将JSON字符串转换为普通Object对象
- 参数：JSON字符串
- 返回：解析后的JavaScript对象

#### toJson(source: any): string
- 功能：将任意对象转换为JSON字符串
- 注意：处理@ObservedV2对象时会保留`__ob_`前缀字段

#### toJsonCompat(source: any): string
- 功能：生成兼容性JSON字符串（自动过滤@ObservedV2的特殊字段）
- 示例：`ZJsonUtil.toJsonCompat(sonBeanV2)`

#### toBeanList<T>(targetClass: new () => T, source: any): T[] | undefined
- 功能：转换对象数组
- 参数：
  - targetClass：目标类类型
  - source：源数据（JSON数组字符串或Object数组）
- 返回：完全深拷贝的类实例数组

#### toObjectList(source: any): any[] | undefined
- 功能：将JSON数组字符串转换为普通Object数组
- 参数：JSON数组字符串
- 返回：解析后的Object对象数组