MongoDB Rust Driver

这是官方支持的 MongoDB Rust 驱动，一个用于与 Rust 应用程序中的 MongoDB 部署交互的客户端库。它使用 bson crate 来支持 BSON。驱动包含一个完整的异步 API，需要 tokio。驱动还提供了一个可通过功能标志启用的同步 API。

有关功能、可运行示例、故障排除资源等更多信息，请参阅 官方文档。

安装

要求

• Rust 1.64+ (更多信息请参阅 MSRV 政策)
• MongoDB 3.6+

支持的平台

该驱动在 CI 中针对 Linux、MacOS 和 Windows 进行测试。

导入

该驱动在 crates.io 上可用。要在您的应用程序中使用该驱动，只需将其添加到项目的 Cargo.toml 文件中。

[dependencies]
mongodb = "3.0.1"

此 crate 的第 1 版已达到生命周期的终点，将不再接收任何更新或错误修复，因此建议所有用户始终依赖于最新的 2.x 版本。如果从 1.x 版本升级，请参阅 2.0.0 版本说明 以获取迁移信息。

启用同步 API

该驱动还提供了一个阻塞的同步 API。要启用此功能，请将 "sync" 功能添加到您的 Cargo.toml

[dependencies.mongodb]
version = "3.0.1"
features = ["sync"]

注意：可以从 mongodb::sync (例如 mongodb::sync::Client) 导入特定于同步的类型。

所有功能标志

Web 框架示例

Actix

通过在 Actix 应用程序数据中存储 Client，可以轻松地使用 Actix Web 框架。有关使用 MongoDB 和 Actix 的完整示例应用程序，请参阅 此处。

Rocket

Rocket Web 框架通过 Rust 驱动程序内置了对 MongoDB 的支持。有关使用 MongoDB 和 Rocket 应用程序的相关说明，请参阅 rocket_db_pools 包的文档。

连接到 Atlas 部署的注意事项

为了连接到 M2 或更大且版本低于 4.2 的预配置 Atlas 实例，必须启用 openssl-tls 功能标志。对于小于 M2 的集群或运行 4.2 或更高版本的服务器版本的集群，无需此标志。

Windows DNS 注意事项

在 Windows 上，由于驱动程序使用的 trust-dns-resolver 包存在已知问题，这会导致使用系统配置的解析器性能严重下降。由于驱动程序默认使用系统配置，建议用户在问题解决之前指定替代解析器配置（例如 ResolverConfig::cloudflare()）直到该问题得到解决。这仅在连接到使用 mongodb+srv 连接字符串的部署时才有影响。

关于超时/取消的警告

在异步Rust中，通常通过在一段时间后丢弃future而不是轮询其完成来实施取消和超时。例如，这就是tokio::time::timeout工作方式。然而，使用由驱动程序返回的future这样做可能会导致驱动程序的内部状态不一致，这可能导致不可预测或错误的行为（有关详细信息，请参阅RUST-937）。因此，强烈建议将驱动程序返回的所有future都轮询到完成。为了仍然使用类似tokio::time::timeout的超时机制与驱动程序一起使用，一个选项是在其JoinHandle future上而不是直接在驱动程序的future上超时。这将确保驱动程序的future始终被完全轮询，同时允许在超时的情况下应用程序继续。

错误报告/功能请求

要提交错误报告或功能请求，请在我们Jira项目上创建一个票据。

• 在jira.mongodb.org上创建账户并登录。
• 转到jira.mongodb.org/browse/RUST上的RUST项目。
• 单击创建问题 - 如果您提交的票据是错误报告，请尽可能详细地说明问题以及如何重现它。

在提交票据之前，请使用Jira的搜索功能查看是否已提交类似的问题。

贡献

我们鼓励并乐意接受以GitHub拉取请求形式进行的贡献。在打开之前，请确保在本地运行测试；有关如何执行此操作的测试部分提供信息。一旦您打开拉取请求，您的分支将与我们用于持续集成系统的同一测试矩阵进行运行，因此通常只需在独立实例上针对本地运行集成测试即可。记住，在打开拉取请求之前始终运行lint测试。

运行测试

集成和单元测试

要运行测试（主要是集成测试），您必须有权访问MongoDB部署。您可以在MONGODB_URI环境变量中指定MongoDB连接字符串，测试将使用它连接到部署。如果未设置MONGODB_URI，测试将尝试连接到端口27017上的本地部署。

注意：集成测试将清除它们需要使用的数据库/集合，但不会自行清理。

要实际运行测试，您可以使用cargo，就像在其他crate中一样。

cargo test --verbose # runs against localhost:27017
export MONGODB_URI="mongodb://127.0.0.1:123"
cargo test --verbose # runs against localhost:123

身份验证测试

只有满足某些要求时，身份验证测试才会包含在测试运行中。

• 部署必须启用--auth。
• 必须在MONGODB_URI中指定凭据。
• MONGODB_URI中指定的凭据必须有效并具有部署上的root权限。

export MONGODB_URI="mongodb://user:pass@localhost:27017"
cargo test --verbose # auth tests included

特定拓扑测试

某些测试将仅针对某些拓扑运行。为确保运行整个测试套件，请确保分别针对独立、复制和分片部署单独运行测试。

export MONGODB_URI="mongodb://my-standalone-host:27017" # mongod running on 27017
cargo test --verbose
export MONGODB_URI="mongodb://127.0.0.1:27018,localhost:27019,localhost:27020/?replicaSet=repl" # replicaset running on ports 27018, 27019, 27020 with name repl
cargo test --verbose
export MONGODB_URI="mongodb://127.0.0.1:27021" # mongos running on 27021
cargo test --verbose

使用TLS/SSL运行测试

要使用TLS/SSL启用测试，您必须在部署和MONGODB_URI中启用它。

export MONGODB_URI="mongodb://127.0.0.1:27017/?tls=true&tlsCertificateKeyFile=cert.pem&tlsCAFile=ca.pem"
cargo test --verbose

注意： 当你打开一个拉取请求时，你的代码将运行在一个全面的测试矩阵中，因此通常不需要在本地对拓扑/身份验证/TLS的所有组合运行集成测试。

代码风格检查测试

我们的代码风格检查测试使用 rustfmt 的夜间版本来验证源代码格式正确，并使用 clippy 的稳定版本来静态检测任何常见错误。你可以使用 rustup 来安装它们。

rustup component add clippy --toolchain stable
rustup component add rustfmt --toolchain nightly

我们的代码风格检查测试还使用 rustdoc 来验证所有必要的文档都已存在且格式正确。 rustdoc 包含在标准的 Rust 分发中。

要运行代码风格检查测试，请运行 check-clippy.sh、check-rustfmt.sh 和 check-rustdoc.sh 脚本，这些脚本位于 .evergreen 目录中。要运行所有三个，请使用 check-all.sh 脚本。

bash .evergreen/check-all.sh

持续集成

对 main 的提交将自动在 evergreen 上运行。

最低支持的 Rust 版本 (MSRV) 政策

此 crate 的 MSRV 目前为 1.64.0。这很少会增加，如果真的增加，也只有在小版本或大版本发布时。

许可证

此项目采用 Apache License 2.0 许可。

此产品包含由 OpenSSL 项目为在 OpenSSL 工具包中使用而开发的软件（http://www.openssl.org/）。