简体中文 | English
taos 是 TDengine 的官方 Rust 语言连接器，Rust 开发人员可以通过它开发存取 TDengine 数据库的应用软件。它支持数据写入、数据查询、数据订阅、无模式写入以及参数绑定等功能。
- 使用 Rust Connector，请参考 开发指南，其中包括数据写入、数据查询、数据订阅、无模式写入以及参数绑定等示例。
- 其它参考信息请看 参考手册，其中包括版本历史、数据类型映射、示例程序汇总、API 参考以及常见问题等内容。
- 本 README 主要是为想自己贡献、编译、测试 Rust Connector 的开发者写的。如果要学习 TDengine，可以浏览 官方文档。
- 已安装 Rust 1.70 及以上版本。
- 本地已安装 TDengine，具体步骤请参考 部署服务端。
- 修改
/etc/taos/taos.cfg配置文件，添加以下配置：supportVnodes 256 - 启动 taosd 与 taosAdapter。
在项目目录下运行以下命令以构建项目：
cargo build在项目目录下执行以下命令运行测试：
cargo test测试用例将连接到本地的 TDengine 服务器和 taosAdapter 进行测试。测试完成后，将看到类似以下的结果摘要，若所有测试用例通过，failed 项应为 0：
test result: ok. 101 passed; 0 failed; 0 ignored; 0 measured; 0 filtered out; finished in 1.21s
-
创建测试模块：在需要测试的
.rs文件中，添加一个带有#[cfg(test)]属性的模块。该属性确保测试代码仅在执行测试时编译。#[cfg(test)] mod tests { // 在此处编写测试用例 }
-
引入被测模块的内容：在测试模块中，使用
use super::*;将外部模块的所有内容引入测试模块的作用域，以便访问需要测试的函数和结构体。#[cfg(test)] mod tests { use super::*; // 在此处编写测试用例 }
-
编写测试函数：测试模块中，定义带有
#[test]属性的函数。每个测试函数应包含以下步骤：- 设置：准备测试所需的数据或状态。
- 执行：调用需要测试的函数或方法。
- 断言：使用断言宏验证结果是否符合预期。
#[cfg(test)] mod tests { use super::*; #[test] fn test_add() { let result = add(2, 3); assert_eq!(result, 5); } }
上述示例中，
assert_eq!宏用于检查result是否等于预期值5。如果不相等，测试将失败并引发 panic。 -
异步函数测试：对于异步函数，可以使用
#[tokio::test]属性宏来标记测试函数，并为其提供 Tokio 异步运行时。#[cfg(test)] mod tests { use super::*; use tokio; #[tokio::test] async fn test_async_function() { let result = async_function().await; assert_eq!(result, expected_value); } }
要启用异步测试支持，需确保在
Cargo.toml中包含 Tokio 依赖。你可以依据项目需求选择适合的异步运行时和相应的测试属性宏。 -
测试引发 panic 的情况：对于预期会引发 panic 的函数，可以使用
#[should_panic]属性。该属性可选地接受expected参数，用于指定预期的 panic 消息。#[cfg(test)] mod tests { use super::*; #[test] #[should_panic(expected = "Divide by zero error")] fn test_divide_by_zero() { divide(1, 0); } }
此示例中，
divide函数在分母为零时应引发 panic，且消息应为 "Divide by zero error"。 -
忽略特定测试：对于耗时较长或不常运行的测试，可以使用
#[ignore]属性标记。默认情况下，这些测试不会运行，除非使用cargo test -- --ignored命令显式运行。#[cfg(test)] mod tests { use super::*; #[test] #[ignore] fn test_long_running() { // 耗时较长的测试代码 } }
性能测试正在开发中。
我们欢迎提交 GitHub Issue。提交时请说明下面信息：
- 问题描述，是否必现，最好能包含详细调用堆栈。
- Rust 连接器版本。
- 连接参数（不需要用户名密码）。
- TDengine 服务端版本。
我们欢迎开发者一起开发本项目，提交 PR 时请参考下面步骤：
- Fork 本项目，请参考 (how to fork a repo)。
- 从 main 分支创建一个新分支，请使用有意义的分支名称 (
git checkout -b my_branch)。注意不要直接在 main 分支上修改。 - 修改代码，保证所有单元测试通过，并增加新的单元测试验证修改。
- 提交修改到远端分支 (
git push origin my_branch)。 - 在 GitHub 上创建一个 Pull Request (how to create a pull request)。
- 提交 PR 后，可以通过 Pull Request 找到自己的 PR，点击对应链接进去可以看到自己 PR CI 是否通过，如果通过会显示 “All checks have passed”。无论 CI 是否通过，都可以点击 “Show all checks” -> “Details” 来查看详细用例日志。
- 提交 PR 后，如果 CI 通过，可以在 codecov 页面找到自己 PR，看单测覆盖率。