此页面由 Cloud Translation API 翻译。

外部 Rust crate 的审核流程

在这里，因为您需要进行审核？直接跳至流程和查看指南。

Rust 的外部库生态系统（简称 crate）是使用该语言。这种现有代码的正文可以起到加快开发速度并降低开发风险。

与此同时，与所有代码一样，外部代码也有风险。我们应该使用外部 crate，但要谨慎使用！本文档介绍了如何最大限度地优势，同时了解并最大限度地降低风险。

背景

截至目前，我们的树中有大约 100 万行外部 Rust 代码，新 crate 的代码审核和对现有 crate 的更新需要大量的工作。为了应对代码库中 Rust 的规模如今，我们必须让所有使用 Rust 的团队都能审核视情况而定

同时，对如何审核外部代码充满不确定性。对外部代码的审核不同于第一方代码审核和规范在业界还不够成熟。事实上，许多小型组织完全依赖其他质量信号，完全没有进行外部代码审核。

对于像 Fuchsia 这样的项目，我们不能容忍此类风险，并且必须审查代码以及我们用来运送产品的各个平台同时，我们应该集中精力以最大限度地提高收益，同时最大限度地减少流程开销。

原则

根据风险分配审核工作

时间和精力都是有限的。识别外部代码可能面临的最大风险并集中精力尽可能减少这类问题。将这些风险与编写新实现的过程。

考虑未来的成本和收益

放眼未来，当下便捷的捷径可能会成为重要的利器问题。解决更常见的问题现在可能需要反复进行可在项目生命周期中享受到哪些好处。

提防意外

请注意，如果清理混乱的代码段或 API 进行多次调用。

无默认结果

所有这些原则既适用于决定使用外部代码的决定，以及为自己做出决策。

回馈

开源库可以为该项目带来一大好处。当我们审核因此，请确保这些评价的详情不对外项目。

流程

对每个相关人员来说，审核第三方代码可能是一项庞大的工作。时间是在向第三方请求和签署第三方请求以尽可能减少开销和重复工作。

添加或更新外部 crate

当您添加或更新外部 crate 并需要审核所做的更改时由其他人提交：

按照外部 Rust crate 将 crate 添加到树中。请勿上传更改至 Gerrit。
是否有任何新的 crate（包括依赖项或许可变更）在现有 crate 的新版本中，请求 OSRB 审批：。
任何新 crate 获得 OSRB 批准后，请将更改上传到 Gerrit。请务必：
- 在提交消息中注明 OSRB 审批 bug。
- 将第一方代码更改与外部代码更改分开，
- 如果 crate 需要更新多个传递依赖项，可以考虑使用 cargo update 将传递性更新分成一个或多个批次，以减少 CL 大小。为了减少审核开销，我们的支持的平台已替换以及使用 cargo 的清单修补功能的空 crate。
为 CL 添加审核者。任何人（包括您！）都可以评论，只要他们请理解本节和下面的准则。
- 如需查找评价者，请在 Fuchsia 上的 #rust 频道中提问栖息着紫红色海豚的 Discord 或其他聊天室。
- 如果审核需要特定领域的专业知识（例如不安全）向具有相关专业知识的审核人员寻求帮助。
- 确保审核者知道他们需要审核哪些 crate。您可以将 crate 分配给个别审核者，这有助于处理大型 CL。
审核完所有代码后，添加 rust_crates OWNERS ¹ 他们的工作是确保相应流程这应该在 CL 注释中得到明确支持。正在积极主动地开展工作将有助于确保快速获得批准。

查看外部 crate

当其他人请求您进行审核时，请务必：

根据审核指南检查代码，请自行做出最佳判断，并在必要时寻求外部帮助。
对代码添加注释，说明您审核了哪些 crate。请记录您提出的评价的注意事项。请注意任何令人惊讶的行为或 bug 。一般来说，即使您认为风险并不存在，也应留意块合并
- 在 CL 级注释的第一行，说明哪些 crate 和版本您查看过。
- 如果您在评价中发现了任何注意事项或风险，请使用星号。您可以使用“all crate”来将其简写或“除...以外的所有 crate” 这样，所有者就能快速浏览评论审核。
如果代码看起来可以合并，请添加“Code Review +1”。如果您发现存在重大 bug 或其他危险信号，请添加“Code Review -1”并根据需要选择建议的解决方法，例如：
- 在合并之前修补上游 crate。
- 结束 CL 并寻求替代解决方案。
- 如果违规代码位于未在 Fuchsia 支持的平台，我们可以替换 crate 以及使用 cargo 的清单修补功能为空的空 ID。

批准外部添加或更新（所有者）

查找审核指南的相关证据之后是 CL：
- 查看以下流程：添加或更新外部 crate 以确保其已遵循
- 请尽可能将 CL 中的注释放在非正式沟通中，因为评论留下了审计跟踪信息。
- 如果缺少证据，请让 CL 所有者完成审核流程并请他们参阅此文档。
查看审核人员指出的所有风险：
- 需要时可请求澄清。
- 提及任何应阻止合并或有必要进一步合并的问题讨论。添加“Code Review -2”确保 CL 不会被合并然后再解决这些问题。
在妥善遵循指南后，所有风险且您愿意合并，则添加“Code Review +2”。

查看准则

外部 crate 审核最多涉及四个主要部分：

架构审核以较高级别评估外部代码目的是为了捕获“明显”问题。
质量审核：对新引入的 crate 进行额外的审查。
代码审核侧重于验证代码是否正确。
OSRB 批准可确保我们添加的代码符合 Fuchsia 的许可政策。OSRB 审批是一个单独的流程，必须在上传引入外部代码的变更列表之前完成。

哪些要素是必需的，取决于变更的性质：

宝箱操作	需要审核架构	需要进行质量审核	需要进行代码审核	需要OSRB审核
已作为直接依赖项添加到 Cargo.toml 中	✅	✅	✅	✅
作为另一个 crate 的间接依赖项提供	❌	✅	✅	✅
已更新的版本	❌	❌	✅	如果许可有变更*

* 更新外部 crate 时，仅当获得许可时，才需要 OSRB 批准变更（包括按文件变更的许可变更）。

Fuchsia 代码所用 crate 的架构审核

架构审查旨在找出“显而易见的”问题，旨在轻量级如果不确定某个 crate 是否有意义从架构的角度来看，应在 CL 中注明这一点，以便审核人员做出最终判断。

添加要在树内使用的直接依赖项（即它直接列在我们的 Cargo.toml 清单），新用户和审核人员应提出以下问题：

树中是否有可以替代的类似 crate？
这个 crate 会加入多少个依赖项，它们的大小是多少？
检查和更新这些依赖项的费用是否与我们使用 crate 获得的好处？
此 crate 在我们的架构环境中是否有意义？对于代码在 Fuchsia 目标上运行：
- 它能否在异步环境中使用？（例如，API 是否要求阻止语义？）
- 此 crate 是否严重依赖于 POSIX 模拟？
此 crate 是否具有合理的 API 以及足够的文档？
- 如果 API 简单明了，则使用最少的文档也可以。
- 如果 API 包含复杂的抽象化处理，由于缺少相关文档，费用。
- 如果该 API 具有未记录的不变量，尤其是不安全的代码，则风险很高。

请注意，这些问题不适用于本单元介绍的传递依赖项直接使用。我们应针对现有的传递性词语提出和回答这些问题，依赖项。

针对新供应商的 crate 的质量审核

除了下面的评价指南之外，评价者还应提供额外的考虑新的 crate，无论它们是直接由我们使用，还是作为另一个 crate 的依赖项。

确保 crate 已获得 OSRB 批准。

着眼未来。

想想我们与此 crate 的关系可能会随时间发生变化。

审核此 crate 及其依赖项是否值得使用其 API 的好处？

还要考虑审核日后更新所需的费用。

此 crate 可能还在其他哪些上下文中使用？

我们不会再针对每次新使用情形再次审核相应实现。如果您觉得 crate 只应在特定平台上使用，或者使用请记住这个假设，请在 Cargo.toml 中的注释中进行说明。

有些 crate 并非在所有可能的情境下都安全使用，平台。如果 crate 在任何情况下不能安全地使用，必须修改 build，以防止在 build 中使用 crate。否则，无法导入 crate。

如果维护人员放弃 crate，会发生什么情况？

我们是否愿意自行开发和维护它？

注意质量信号。

所有这些质量信号都可以使用 crates.io 查找或通常链接到的源代码库

一阶信号为我们提供了有关 crate 质量的直接证据：

代码审核
- 代码审核是最基本的一阶信号。虽然代码审查始终是必须的，审查几乎从不详尽无遗。
测试
- 在 crate 中缺少测试是一个危险信号。测试并不一定需要进行审核，但是值得抽查一下，看看是否有意义语义检查和良好的覆盖率。此外，还要检查 crate 的测试是否或者是传入本地结账 cargo test。进行可靠测试是一个很好的迹象。

二阶信号提供了 crate 质量的间接证据，用作支持证据。不应缺少二阶信号使用 crate 取消资格。相反，这些信号应该有助于填补增强自信，并在不明朗的时刻做出调整：

多个维护者
著名作家
充分利用反向依赖项
- 这些列在“依赖项”下
仓库和问题跟踪器中的活动

所有外部代码的代码审核

在审核外部代码时，无论是新 crate 还是对现有 crate 的更新：

寻找风险

外部代码中存在的常见风险包括：

unsafe 个验证码 <ph type="x-smartling-placeholder">
- 只应在必要时使用不安全的代码。应该能够轻松实现易于遵循和/或记录其不变量及其如何保留。不安全的 API 应该非常罕见，并且必须始终记录调用方需要坚持的不变性。²
需要专业领域专业知识才能理解的代码
- 如果可能，请联系域名专家查看此代码。例如：不安全、低级别原子、并发、加密和网络协议实现
要在关键路径中使用的代码
- 其中包括对安全至关重要的路径，如加密，以及性能关键型路径请特别注意此代码，确保它不会破坏关键路径
代码过于复杂
- 惯用的 Rust 利用适当的抽象级别，使用管理不变量。如果代码很难会让您对那些不变量问题良好、没有信心但其质量可能较低，并且包含可避免的错误。

与往常一样，请务必记住我们的替代方案。假设我们需要如果我们编写代码，我们是否会面临相同的风险该怎么办？这样做实际会产生更好的结果，是否值得您不想费心编写和维护该代码？

验证内容是否正确，但不要过度。

在理想情况下，我们可以正式验证性能。不过，这通常不切实际，因此我们需要充分利用我们投入的时间和精力来增强信心，同时仍然保持尽最大努力：

验证实现是否合理
- 给定函数签名、特征等。
发现惊喜内容
- 请务必记下 CL 注释中的所有内容（最好内嵌在代码）。
专注于您面前的代码
- 可以假定其他函数会执行它们所说的，因为您最终都会审核。不应跟踪整个函数调用图如果确实有必要，那么这通常是一个不好的信号。发挥你的最佳判断依据，帮助您集中精力。
确保 build.rs 更改反映在我们的 build 中 <ph type="x-smartling-placeholder">
- build.rs 脚本不会在我们的 build 中运行，但需要翻译调用 crate。cargo-gnaw对此提供有限支持，但并非无所不包查看这些更改，确认所有内容都会体现在我们的构建规则中如果您可以放心地审核这些内容，请让 CL 所有者再找一位审核员。

跳过不相关的内容。

您无需查看以下内容：

代码样式
已审核的未更改代码
单独的测试用例和基准
我们确定绝不会在平台上使用针对具体平台的代码³
对了解 API Surface 没有直接帮助的文档以及实施情况足够好

在评估新 crate 的质量时，其中一些指标仍然适用，。