IoTDB Rust 原生接口开发指南：从零生成 + 完整 RPC 调用

IoTDB Rust 原生接口开发指南：从零生成+完整RPC调用

如果你想用 Rust 对接 IoTDB，但又不想用第三方封装，官方这套基于 Thrift 生成 Rust 原生接口的方案绝对是最稳的。不用猜结构体、不用手写序列化，直接生成一套和 Java/Python 完全对等的 RPC 客户端，性能强、类型安全、生产可用。

这篇文章就带你从头走一遍：环境准备 → 修改 pom.xml → 编译生成 Rust 代码 → 集成到项目 → 全量 RPC 接口一览，复制粘贴就能跑通。

一、先搞清楚：为什么用 Rust 原生接口

IoTDB 底层是 Thrift RPC，跨语言都是靠 IDL 文件自动生成。

Rust 原生接口的好处很实在：

性能拉满：无运行时、序列化开销低
类型安全：编译期就把参数错、类型错全拦掉
功能最全：和官方 Java 客户端1:1 对齐，不丢接口
无第三方依赖：纯官方、可维护、生产放心

这套流程适合：边缘采集端、高性能写入代理、Rust 后端直连 IoTDB。

二、环境依赖（一步都不能错）

先把环境配齐，后面编译才不会报错：

JDK ≥ 1.8（Maven 编译要用）
Rust ≥ 1.0.0
Thrift 0.14.1+（必须装，用来生成 Rust 代码）
系统：Linux / macOS / Windows+Git Bash/WSL/cygwin 都行

安装 Thrift 可以看官方教程：

http://thrift.apache.org/docs/install/

最后确保命令行能输出版本：

bash 复制代码

thrift --version
# 要求 >= 0.14.1

三、最关键一步：修改 pom.xml 生成 Rust 代码

这是全文最重要的配置，照着加就行，不用改别的。

下载 IoTDB 源码，打开根目录的 pom.xml
找到生成 Java thrift 的那段 <execution>
在它旁边新增一段 Rust 生成配置：

xml 复制代码

<execution>
    <id>generate-thrift-sources-rust</id>
    <phase>generate-sources</phase>
    <goals>
        <goal>compile</goal>
    </goals>
    <configuration>
        <generator>rs</generator>
        <thriftExecutable>${thrift.exec.absolute.path}</thriftExecutable>
        <thriftSourceRoot>${basedir}/src/main/thrift</thriftSourceRoot>
        <includes>**/common.thrift,**/client.thrift</includes>
        <outputDirectory>${project.build.directory}/generated-sources-rust</outputDirectory>
    </configuration>
</execution>

参数一眼看懂：

generator="rs"：告诉 Maven 生成 Rust 代码
includes：只编译 client + common，最精简、不冗余
outputDirectory：生成代码的输出目录

四、一键编译生成 Rust 接口代码

配置完直接在 IoTDB 源码根目录运行：

bash 复制代码

mvn clean generate-sources

执行完会自动：

清空旧的 target 目录
重新生成 Rust 代码到：
- iotdb-protocol/thrift/target/generated-sources-rust/
- iotdb-protocol/thrift-commons/target/generated-sources-rust/

⚠️ 重要提醒：
这两个目录在 .gitignore 里，千万不要提交到 Git！

五、把生成的 Rust 代码放进你的项目

在你的 Rust 项目里建一个 iotdb 目录
把下面两个文件夹全部复制 进去：
- generated-sources-rust/
- generated-sources-rust-commons/
在 Cargo.toml 加上 Thrift 依赖：

toml 复制代码

[dependencies]
thrift = "0.14.1"

这样你就拥有了完整的 IoTDB Rust 原生客户端。

六、支持哪些 RPC 接口？（全量列表）

生成的代码里，下面这些接口全都能用，和 Java 完全一致：

会话管理

openSession：打开会话
closeSession：关闭会话
getTimeZone / setTimeZone：时区操作

SQL 执行

executeStatement：通用执行
executeQueryStatement：查询
executeUpdateStatement：写入/删除
executeBatchStatement：批量执行
fetchResults：取下一批结果
cancelOperation / closeOperation：取消/关闭查询

元数据 & 存储组

setStorageGroup
deleteStorageGroups
createTimeseries
createMultiTimeseries
deleteTimeseries

数据写入（高性能）

insertRecord / insertRecords
insertStringRecord
insertTablet / insertTablets
insertRecordsOfOneDevice

测试性能接口（只测时延不写入）

testInsertRecord
testInsertTablet
testInsertRecords
等等一批 test 接口

数据删除

deleteData

七、极简使用思路（Rust 调用示例）

虽然生成的是原生 Thrift 结构，但调用模式很固定：

创建 TTransport 连接 IoTDB 6667
创建 TProtocol 协议（Binary 协议）
创建 Client
openSession
调用 insert / executeQuery 等
closeSession

Rust 里伪代码大概长这样：

rust 复制代码

use thrift::transport::TSocket;
use thrift::protocol::TBinaryProtocol;
use iotdb::client::IoTDBClient;

fn main() -> thrift::Result<()> {
    let transport = TSocket::new("127.0.0.1", 6667)?;
    transport.open()?;

    let protocol = TBinaryProtocol::new(transport, true, true);
    let mut client = IoTDBClient::new(protocol);

    // 1. openSession
    let session_resp = client.openSession(...)?;
    let session_id = session_resp.session_id;

    // 2. 插入/查询
    client.insertRecord(...)?;
    let rs = client.executeQueryStatement(...)?;

    // 3. closeSession
    client.closeSession(session_id)?;
    transport.close()?;

    Ok(())
}

剩下的就是把参数按 Thrift 结构体填进去，完全和 Java 一一对应。

八、小结

IoTDB Rust 原生接口其实就三句话：

配好 JDK+Thrift
pom.xml 加一段 rust 生成配置
mvn 编译 → 复制代码到项目 → 直接 RPC 调用

优点非常突出：

官方原生、无魔改
高性能、Rust 生态友好
接口最全，和 Java 客户端保持同步

如果你正在做物联网采集端、边端时序数据写入，这套方案几乎是最优解。