扩展文件系统规范及其测试

文件系统规范不完整。它并未涵盖文件系统 API 中的所有操作，甚至没有涵盖所有接口和类。对于它确实涵盖的内容，可能存在一些小问题，例如特殊情况、故障模式和其他意外结果。标准文件系统也可能与规范有很大出入，并且需要在测试中记录和处理这种情况。

最后，文件系统类和方法并非一成不变。它们可能会扩展到现有类上的新操作，以及潜在的全新类和接口。

因此，不要将此规范视为一个完整的静态文档，就像 Hadoop 代码的其他部分一样。

  1. 将其视为一个实时文档，用于伴随参考实现 (HDFS) 和用于验证文件系统的测试。
  2. 不要害怕扩展或更正它。
  3. 如果您建议对文件系统 API 进行增强，则应扩展规范以进行匹配。

如何更新此规范

  1. 尽管在 hadoop-common 代码库中找到，但 HDFS 团队拥有文件系统和文件上下文 API 的所有权。在 hdfs-dev 邮件列表上与他们合作。

  2. 在 HADOOP 项目、组件 fs 中创建 JIRA 问题，以涵盖 API 和/或规范中的更改。

  3. 代码更改当然需要测试。理想情况下，规范本身的更改会伴随新测试。

  4. 如果更改涉及已具有 Abstract*ContractTest 的操作，请向该类添加新的测试方法，并验证它们在对其进行子类化的文件系统特定测试上是否有效。这包括对象存储以及本地和 HDFS 文件系统。

  5. 如果更改添加了新操作，请添加一个新的抽象测试类，其契约驱动架构与现有架构相同，并为支持该操作的所有文件系统添加一个实现子类。

  6. 添加测试方法以验证无效的前提条件是否会导致预期的失败。

  7. 添加测试方法以验证有效的前提条件是否会导致文件系统的预期最终状态。每个测试尽可能少地进行测试有助于跟踪问题。

  8. 如果可能，请添加测试以显示并发预期。

如果 FileSystem 未通过新添加的测试，则可能是因为

  • 规范错误。
  • 测试错误。
  • 测试正在寻找错误的异常（即它过于严格）。
  • 规范和测试正确，并且文件系统与预期不一致。

HDFS 的行为必须被视为正确。如果测试和规范不符合此行为，则需要更新规范。即便如此，仍可能存在可以更改 FS 的情况

  1. 当可以引发更具信息性的子类（如 EOFException）时，引发的异常是通用 IOException。
  2. 当传递一组无效参数时，FileSystem 不会正确失败。这可能可以纠正，但必须谨慎进行。

如果 LocalFileSystem 中存在不匹配，则可能无法纠正，因为这是通过 Java IO API 访问的本机文件系统。

对于其他文件系统，其行为可能会更新，以更准确地反映 HDFS 和/或 LocalFileSystem 的行为。对于大多数操作来说，这是直接的，尽管 rename() 的语义足够复杂，以至于尚不清楚 HDFS 是否是正确的参考。

如果测试失败并且认为这是无法修复的文件系统特定问题，则应向 ContractOptions 接口添加一个新的契约选项，以允许对结果进行不同的解释，修改测试以对选项的存在/不存在做出反应，并更新标准文件系统的 XML 契约文件以指示何时存在功能/故障模式。