TurboTransProtobufPlugin插件配置指南

1. 功能介绍

1.1 插件介绍

TurboTransProtobufPlugin是一个基于 Hvigor 构建系统的编译时插件，专门为项目提供自动代码生成能力。在编译期自动生成高性能的序列化和反序列化代码，让开发者无需手写繁琐的对象转换逻辑。

• 1.2 核心特性

• 编译时自动生成序列化和反序列化代码

• 自动导入，生成的代码自动集成到项目中

2. 配置编译插件

2.1 依赖配置

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

{
  "modelVersion": "6.0.0",
  "dependencies": {
    "@hadss/turbo-trans-protobuf-plugin": "^1.0.0-rc.0"
  }
  // ...其余配置
}

2.2 Hvigor 集成

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

// 工程根目录/hvigorfile.ts
import { turboTransProtobufPlugin } from "@hadss/turbo-trans-protobuf-plugin"

export default {
  system: appTasks,
  plugins: [
    turboTransProtobufPlugin({
      saveDir: 'src/generated/ArkTS', // 保存路径
      ignoreModuleNames: ['TurboTransCore', 'PerformanceBaseline'], // 忽略模块
      sendable: false, // 是否开启sendable
      debug: false, // 是否debug模式
      scanDir: ['protofile', 'src/main'], //扫描路径
    }),
  ]
}

3. 配置选项

3.1 基础配置

| 配置项 | 类型 | 是否必填 | 默认值 | 说明 | |---------------------|------------------|------|-------------------------|:-----------------------------------------------------------------------------------------------------------------| | saveDir | string | 否 | src/generated/ArkTS | 生成代码保存模块下的路径 | | ignoreModuleNames | string[] | 否 | [] | 需要忽略的模块 | | namePattern | string | 否 | DefaultPattern | 变量的命名模式，可选项有DefaultPattern CamelCase，CamelCase表示驼峰命名，DefaultPattern表示默认命名用下线连接 | | debug | boolean | 否 | false | 是否开启debug模式 | | sendable | boolean | 否 | true | 生成的代码是否开启sendable | | enableFunctions | string[] | 否 | ['create','encode','decode','getTypeUrl','fromObject','toObject','verify'] | 默认值生成所有的函数，可选值有create encode decode fromObject toObject verify getTypeUrl | | scanDir | string[] | 否 | ['src/main'] | 扫描每个模块下的路径的proto文件 |

3.3 完整选项配置示例

turboTransJsonPlugin({
  saveDir: 'src/generated/ArkTS',
  ignoreModuleNames: [],
  namePattern: 'CamelCase',
  sendable: false,
  debug: false,
  enableFunctions:[],
  scanDir: ['src/main'],
})

4. 完整使用示例

4.1 项目结构

│─ protofile
├─/src/main/ets
├── pages/
│   └── MainPages.ets
└─ ...

4.2 proto定义（order_data.ets）

syntax = "proto3";

package com.hadss;

option java_package = "com.hadss.turboTransProtobuf";

enum OrderStatus {
  ORDER_STATUS_UNSPECIFIED = 0;
  ORDER_STATUS_PAID = 1;
  ORDER_STATUS_COMPLETED = 2;
}

enum PayMethod {
  PAY_METHOD_UNSPECIFIED = 0;
  PAY_METHOD_ALIPAY = 1;
  PAY_METHOD_WECHAT = 2;
}

message User {
  string user_id = 1;
  string username = 2;
  string phone = 3;
}

message Product {
  string product_id = 1;
  string product_name = 2;
  int64 unit_price = 3;
}

message OrderItem {
  Product product = 1;
  int32 quantity = 2;
  int64 total_price = 3;
}

message Order {
  string order_id = 1;
  User user = 2;
  repeated OrderItem items = 3;
  PayMethod pay_method = 4;
  OrderStatus status = 5;
  int64 total_amount = 6;
  string create_time = 7;
}

message OrderQueryResponse {
  repeated Order orders = 1;
  int64 total = 2;
}

4.3 hvigorfile.ts 配置

turboTransProtobufPlugin({
      saveDir: 'src/main/ets/protobuf',
      ignoreModuleNames: ['TurboTrans'],
      sendable: true,
      debug: false,
      scanDir: ['protofile'],
    })

4.4 执行编译命令

hvigorw default

4.5 使用示例

const context = getContext(this).createModuleContext('ProtobufSample');
try {
  const bin = context.resourceManager.getRawFileContentSync('OrderData_java.bin');
  this.bin = bin;
  this.messageSimple = com.hadss.OrderQueryResponse.decode(bin.buffer as ArrayBuffer);
} catch (error) {
  
}

5. 更多资料

• API参考
• TurboTransProtobuf 使用说明
• TurboTransProtobufSample 参考项目

6.贡献代码

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

7.开源协议

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