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

FileSystem规范尚不完整。它并未涵盖FileSystem API中的所有操作，甚至包括部分接口和类。对于已涵盖的内容，可能存在一些次要问题，例如边界情况、故障模式和其他意外结果。也可能存在标准FileSystem与规范显著偏离的情况，这需要在测试中进行记录和处理。

最后，FileSystem类和方法并非一成不变。它们可能会在现有类上扩展新的操作，也可能引入全新的类和接口。

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

  1. 将其视为一份实时文档，配合参考实现（HDFS）以及用于验证文件系统的测试用例。
  2. 不要害怕扩展或修正它。
  3. 如果您正在提议对FileSystem API进行增强，则应扩展规范以匹配。

如何更新此规范

  1. 尽管位于hadoop-common代码库中，但HDFS团队拥有FileSystem和FileContext API的所有权。请通过hdfs-dev邮件列表与他们协作。

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

  3. 代码变更当然需要测试。理想情况下，对规范本身的修改应附带新的测试用例。

  4. 如果变更涉及已有Abstract*ContractTest的操作，请向该类添加新的测试方法，并验证它们在继承该类的文件系统特定测试中正常工作。这包括对象存储以及本地和HDFS文件系统。

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

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

  7. 添加测试方法以验证有效的先决条件会导致文件系统达到预期的最终状态。每个测试尽可能少地测试有助于追踪问题。

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

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

  • 规范有误。
  • 测试是错误的。
  • 测试正在寻找错误的异常（即它过于严格）。
  • 规范和测试是正确的 - 但文件系统与预期不符。

必须将HDFS的行为视为正确。如果测试与规范不符合此行为，则需要更新规范。即便如此，在某些情况下文件系统仍可能被更改：

  1. 抛出的异常是一个通用的IOException，而实际上可以抛出更具信息性的子类异常，例如EOFException。
  2. 当传入无效参数集时，FileSystem未能正确执行失败处理。这个问题或许可以修正，但必须谨慎操作。

如果不匹配发生在LocalFileSystem中，那么很可能无法纠正，因为这是通过Java IO API访问的原生文件系统。

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

如果测试失败且被认为是一个无法修复的特定于文件系统的问题，则应向ContractOptions接口添加一个新的合约选项，以允许对结果进行不同的解释，修改测试以响应该选项的存在/缺失，并更新标准文件系统的XML合约文件以指示某个特性/故障模式是否存在。