npm package: @hadss/turbo-trans-json-plugin
Description: TurboTransJSON Compiler Plugin for automatic serialization code generation
Author: DTSE
Latest version: 1.0.0-rc.2

# TurboTransJSON 插件配置指南

## 1. 功能简介

### 1.1 插件介绍

TurboTransJSONPlugin 是一个基于 Hvigor 构建系统的编译时插件，专门为项目提供自动化 JSON 序列化代码生成能力。该插件通过静态分析项目中的 `@Serializable` 装饰器，在编译期自动生成高性能的序列化和反序列化代码，让开发者无需手写繁琐的对象转换逻辑。

### 1.2 核心特性

- 编译时自动生成序列化和反序列化代码
- 支持泛型、继承、枚举、联合类型等复杂类型
- 支持通过装饰器覆盖类和属性名称、将某个属性设为必须验证、忽略某个属性
- 自动导入重写，生成的代码自动集成到项目中

## 2. 插件安装与配置

### 2.1 依赖配置

修改工程根目录下的 `hvigor/hvigor-config.json` 文件，加入序列化编译插件：

```json5
{
  "modelVersion": "6.0.0",
  "dependencies": {
    "@hadss/turbo-trans-json-plugin": "latest",
    // 使用npm仓版本号
  }
  // ...其余配置
}
```

### 2.2 Hvigor 集成

修改工程根目录下的 `hvigorfile.ts`，使用序列化编译插件：

```typescript
// 工程根目录/hvigorfile.ts
import { hvigor } from "@ohos/hvigor";
import { appTasks } from '@ohos/hvigor-ohos-plugin';
import { turboTransJsonPlugin } from "@hadss/turbo-trans-json-plugin";

export default {
  system: appTasks,
  plugins: [
    turboTransJsonPlugin(hvigor, {
      ignoreModuleNames: [/** 不需要扫描的模块名，如: 'SomeLibModule' */],
      scanDir: ['src/main/ets'],
      deserializationMode: 'performance', // 反序列化模式，可选值: 'performance' | 'strict'
    }),
  ]
}
```

## 3. 配置选项

### 3.1 基础配置

| 配置项                   | 类型                      | 默认值                | 说明                                  |
|-----------------------|-------------------------|--------------------|:------------------------------------|
| `deserializationMode` | `performance \| strict` | `performance`      | 反序列化模式：performance-性能优先，strict-验证优先 |
| `ignoreModuleNames`   | `string[]`              | `[]`               | 跳过处理的模块名称列表                         |
| `scanDir`             | `string[]`              | `['src/main/ets']` | 扫描源码的目录列表                           |
| `importRewrite`       | `ImportRewriteOptions`  | `空`                | 重写源代码中序列化类的导入路径                     |

### 3.2 ImportRewriteOptions 导入重写配置

| 配置项                       | 类型         | 默认值                | 说明           |
|---------------------------|------------|--------------------|:-------------|
| `scanPaths`               | `string[]` | `['src/main/ets']` | 导入重写的扫描路径    |
| `preserveOriginalImports` | `boolean`  | `false`            | 保留原始导入语句组为注释 |

### 3.3 完整选项配置示例

```typescript
turboTransJsonPlugin(hvigor, {
  ignoreModuleNames: [/** 不需要扫描的模块名，如"SomeModule" */],
  scanDir: ['src/main/ets'],
  deserializationMode: 'performance',
  importRewrite: {
    scanPaths: ['src/main/ets'],
    preserveOriginalImports: false
  }
})
```

## 4. 插件命令与使用

序列化插件提供专门的任务命令，使用方式如下：

```shell
hvigorw [taskNames...]
```

### 可用命令

| 任务          | 说明                                                                                                          |
|-------------|-------------------------------------------------------------------------------------------------------------|
| `jsonSync`  | 同步模块配置并生成序列化器。该任务会扫描项目中使用 `@Serializable` 注解的模块，自动修改这些模块的 `build-profile.json5` 文件以添加必要的编译配置，然后生成对应的序列化器代码。 |
| `jsonClean` | 清空生成的序列化器代码                                                                                                 |
| `jsonWatch` | 监听 `@Serializable` 装饰器文件修改，自动重新执行同步和生成                                                                      |

### 使用示例

```bash
# 同步模块配置，生成序列化器
hvigorw jsonSync

# 清空生成的序列化器
hvigorw jsonClean

# 监听文件变化自动重新生成
hvigorw jsonWatch

# 构建项目（自动生成序列化器）
hvigorw assembleHap
```

> **关于 `jsonSync` 任务的配置修改行为：**
> 
> `jsonSync` 任务会自动修改使用了 `@Serializable` 注解的模块的 `build-profile.json5` 文件，添加序列化插件所需的编译配置。这样做的好处：配置写入文件后，IDE可以在静态编码阶段识别生成的序列化器代码，提供更好的代码提示和类型检查
> 
> **使用建议：** 在项目中引入插件后，建议手动执行一次 `hvigorw jsonSync`，确保所有模块配置正确同步。之后在正常的构建流程（如 `assembleHap`）中，插件会自动处理序列化器的生成。

## 5. 完整使用示例

### 5.1 项目结构

```
├─/src/main/ets
├── model/
│   ├── User.ets
│   ├── Product.ets
│   └── Order.ets
├── pages/
│   └── MainPages.ets
└── ...
```

### 5.2 模型定义（User.ets）

```typescript
import { Serializable, SerialName, Required, Transient } from '@hadss/turbo-trans-core';

export enum UserRole {
  Admin = 'admin',
  User = 'user',
  Guest = 'guest'
}

@Serializable({ generateSendable: true })
export class User {
  @Required()
  @SerialName({ name: 'user_id' })
  id: string = '';

  @Required()
  name: string = '';

  email: string = '';
  age: number = 0;
  role: UserRole = UserRole.Guest;

  @Transient()
  password: string = '';

  createdAt: Date = new Date();
}
```

### 5.3 hvigorfile.ts 配置

```typescript
import { hapTasks } from '@ohos/hvigor-ohos-plugin';
import { turboTransJsonPlugin } from "@hadss/turbo-trans-json-plugin";

export default {
  system: hapTasks,
  plugins: [
    turboTransJsonPlugin(hvigor, {
      ignoreModuleNames: ['TurboTransCore', 'TurboTransJSON'],
      scanDir: ['src/main/ets'],
      deserializationMode: 'performance',
      importRewrite: {
        scanPaths: ['src/main/ets', 'src/ohosTest/ets'],
        preserveOriginalImports: false
      }
    })
  ]
}
```

### 5.4 执行同步任务

```shell
hvigorw jsonSync
```

### 5.5 使用示例（MainPage.ets）

```extendtypescript
import { User, UserRole } from '../model/User';
import { TJSON } from '@hadss/turbo-trans-json';

@Entry
@Component
struct MainPage {
  build() {
    Column() {
      Button('测试序列化')
        .onClick(() => {
          const user = new User();
          user.id = '123';
          user.name = 'John Doe';
          user.email = 'john@example.com';
          user.age = 25;
          user.role = UserRole.User;

          // 序列化为 JSON
          const jsonString = TJSON.toString(user, User);

          // 反序列化为实体类
          const userInstance = TJSON.fromString<User>(jsonString, User);
        })
    }
  }
}
```

### 5.5 构建和验证

```bash
# 构建项目
hvigorw assembleHap

# 检查生成的代码(生成的代码位于各个模块/src/generated目录下)
# 插件会进行代码生成并重写导入语句(导入语句的路径会被重写为${模块的包名}/ets/开头的路径)
# 确认编译无错误后表示集成成功
```

## 6. 更多资料

- [API 参考](https://gitcode.com/openharmony-sig/turbo_trans/wiki/API-Reference.md)
- [TurboTransJSON 主文档](https://gitcode.com/openharmony-sig/turbo_trans/wiki)
- [TurboTransSample 参考项目](https://gitcode.com/openharmony-sig/turbo_trans/tree/master/TurboTransSample)

## 7. 贡献代码

使用过程中发现任何问题都可以提 [Issue](https://gitcode.com/openharmony-sig/turbo_trans/issues)，当然，也非常欢迎发 [PullRequest](https://gitcode.com/openharmony-sig/turbo_trans/pulls) 共建。

## 8. 开源协议

本项目基于 [Apache License 2.0](https://gitcode.com/openharmony-sig/turbo_trans/blob/master/LICENSE)，请自由地享受和参与开源。