TurboTransJSON 插件配置指南

1. 功能简介

1.1 插件介绍

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

1.2 核心特性

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

2. 插件安装与配置

2.1 依赖配置

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

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

2.2 Hvigor 集成

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

// 工程根目录/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 完整选项配置示例

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

4. 插件命令与使用

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

hvigorw [taskNames...]

可用命令

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

使用示例

# 同步模块配置，生成序列化器
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）

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 配置

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 执行同步任务

hvigorw jsonSync

5.5 使用示例（MainPage.ets）

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 = '[email protected]';
          user.age = 25;
          user.role = UserRole.User;

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

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

5.5 构建和验证

# 构建项目
hvigorw assembleHap

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

6. 更多资料

• API 参考
• TurboTransJSON 主文档
• TurboTransSample 参考项目

7. 贡献代码

使用过程中发现任何问题都可以提 Issue，当然，也非常欢迎发 PullRequest 共建。

8. 开源协议

本项目基于 Apache License 2.0，请自由地享受和参与开源。