# TurboTransProtobufPlugin插件配置指南

## 1. 功能介绍

### 1.1 插件介绍

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

- ### 1.2 核心特性

- 编译时自动生成序列化和反序列化代码
- 自动导入，生成的代码自动集成到项目中


## 2. 配置编译插件

### 2.1 依赖配置

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

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

### 2.2 Hvigor 集成

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

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

```typescript
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）
```proto
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 执行编译命令
```shell
hvigorw default
```


4.5 使用示例
```typescript
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参考](https://gitcode.com/openharmony-sig/turbo_trans/wiki/protobuf%2FTurbo-Trans-Protobuf-API-Reference.md)
   - [TurboTransProtobuf 使用说明](https://gitcode.com/openharmony-sig/turbo_trans/wiki/protobuf%2FHome.md)
   - [TurboTransProtobufSample 参考项目](https://gitcode.com/openharmony-sig/turbo_trans/tree/turbo_trans_protobuf/TurboTransSample/ProtobufSample)

## 6.贡献代码

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

## 7.开源协议

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