Dropbox SDK for Rust

Rust 对 Dropbox APIv2 的绑定，由 Stone 从官方规范生成。

用于生成代码的 Stone SDK 和 Dropbox API 规范分别位于 stone 和 dropbox-api-spec 子模块中。使用 git submodule init 和 git submodule update 来获取它们。

生成的代码存储在 src/generated 下以简化构建。要重新生成或更新它，运行 python generate.py。这样做需要有效的 Python 环境和一些依赖项。有关详细信息，请参阅 Stone 文档。

此 SDK 的状态

此 SDK 尚未官方化。这意味着什么？

• 目前没有正式的 Dropbox 对 SDK 的支持。
• 错误可能得到修复，也可能不会修复。
• 可能并非所有 SDK 功能都得到实现。

然而，话虽如此，

• SDK 是可用的！
• 我们很高兴从社区获得反馈和/或拉取请求！有关更多信息，请参阅 贡献。

HTTP 客户端

要实际使用 API 调用，您需要一个 HTTP 客户端 -- 所有函数都将 HttpClient 类型实现作为其第一个参数。此特性位于 dropbox_sdk::client_trait::HttpClient。实现此特性并将其作为客户端参数传递。

如果您不想自己实现，此SDK附带了一个可选的默认客户端，它使用ureq和rustls。要使用它，请使用带有default_client功能标志进行构建，然后在dropbox_sdk::default_client模块中将有一组客户端可供使用，对应于Dropbox使用的每种认证类型（见下文）。默认客户端需要一个Dropbox API令牌；您如何获取它取决于您和您的程序。请参阅examples/下的程序示例，以及oauth2模块中的辅助代码。

认证类型

Dropbox API有多种不同的认证类型。每个路由都需要一个与所需特定认证类型兼容的HTTP客户端。除了基础HttpClient特质外，还需要实现一个标记特质来指定认证类型：其中之一为NoauthClient、UserAuthClient、TeamAuthClient或AppAuthClient。

默认客户端实现了所有这些（目前除了AppAuthClient之外）。它们都共享一个公共实现，只是在请求中添加了不同的HTTP头。

功能标志

如果您只使用API的一部分，并且想缩短编译时间，您可以明确指定与您需要的命名空间相对应的功能。对于每个命名空间，都有一个对应的功能dbx_{ whatever}。如果需要，可以使用update_manifest.py脚本来更新功能集。例如，只需要'files'和'users'命名空间的示例：

[dependencies.dropbox-sdk]
version = "*"
default_features = false
features = ["dbx_files", "dbx_users"]

结果类型和错误

路由返回一个嵌套的结果类型：Result<Result<T, E>, dropbox_sdk::Error>。外层的Result是Err，如果在实际发送请求的过程中出现错误，如网络I/O错误或请求数据序列化或反序列化失败。这个Result的Ok变体是另一个Result，其中Ok值是调用成功后的反序列化结果，而Err值是API返回的强类型错误。这个内部错误表明请求存在问题，如文件不存在、权限不足等。

这样分割错误的原因是，前一类问题通常只能通过重试请求来解决，而后一类问题表明请求本身存在问题，可能不应该重试。由于大多数调用者无法以任何合理的方式处理I/O错误，这允许它们使用?语法将其传递到堆栈中，同时仍然处理服务器返回的错误。

测试

测试也是从规范自动生成的，但与主代码不同，它们不会被检查。运行python generate.py来生成测试，并运行cargo test来执行它们。

测试生成器首先生成一个参考Python SDK并加载该代码。然后它生成SDK中每种类型的实例，并使用Python代码将它们序列化为JSON。然后它发出包含JSON字符串的Rust测试，将其反序列化，断言所有字段包含预期的值，重新序列化它，再次反序列化，并再次断言字段。因此，我们对Rust生成器发出的序列化和反序列化逻辑有相当好的覆盖率，与Python实现（Dropbox在服务器端使用的）进行了检查。

杂项

一些实现说明、限制和待办事项

• Stone允许结构继承自其他结构并具有多态性。Rust没有这些范式，因此此SDK将多态父结构表示为枚举，并将继承的字段放入所有变体中。有关示例，请参阅dropbox_sdk::files::Metadata。
• 此crate仅支持同步I/O。最终我们可能希望支持异步I/O，这将需要对路由返回的类型进行不兼容的更改。这可能需要等到futures生态系统和async/await稳定一些。
• 此代码大部分不使用serde_derive，而是使用手动发出的序列化代码。此crate之前的工作尝试使用serde_derive，但Dropbox API序列化包含结构的联合（通过将它们的字段折叠到联合中）的方式不受serde_derive支持。它还花费了极长的时间编译（发布构建约为30分钟）和巨大的（约190MB）.rlib文件。手写的代码更灵活，编译更快，生成的二进制文件更小，但代价是生成的源代码更大。
• 具有约束的类型（例如具有模式或最小/最大长度的字符串或具有范围的整数）不会检查存储在其中的数据是否符合约束。

快乐的Dropbox生活！