Skip to main content

Flow 注释-导出

升级到 类型优先 模式可能需要在模块边界处进行大量类型注释。为了帮助升级大型代码库的过程，我们提供了一个 codemod 命令，其目标是填充这些缺失的注释。此命令包含在版本 >= 0.125 的 Flow 二进制文件中。

¥Upgrading to Types-First mode may require a substantial number of type annotations at module boundaries. To help with the process of upgrading large codebases, we are providing a codemod command, whose goal is to fill in these missing annotations. This command is included in the Flow binary in versions >= 0.125.

注意：从版本 0.134 开始，类型优先是默认模式。如果你使用的是 >=0.134 版本，请确保在运行此 codemod 时在 .flowconfig 中设置 types_first=false。

¥Note: As of version 0.134, types-first is the default mode. If you are using a version >=0.134, make sure you set types_first=false in your .flowconfig while running this codemod.

此命令使用 Flow 推断的类型来填充否则会引发签名验证失败的位置。它将包括必要的类型导入语句，只要相应的类型是从其定义模块导出的。

¥This command uses types that Flow infers, to fill in positions that would otherwise raise signature-verification failures. It will include the necessary type import statements, as long as the respective types are exported from their defining modules.

它设计用于一次处理多个文件，而不是一次处理一个文件。因此，它不会连接到现有的 Flow 服务器，而是启动自己的检查过程。

¥It is designed for use on multiple files at once, rather than one file at a time. For this reason it doesn't connect to an existing Flow server, but rather starts a checking process of its own.

正如此类机械化方法的典型特性，它有一些注意事项：

¥As is typical with such mechanized approaches, it comes with a few caveats:

  1. 它无法填写每个必需的类型注释。有些情况需要手动操作。

    ¥It won’t be able to fill in every required type annotation. Some cases will require manual effort.

  2. 插入的注释可能会导致新的 Flow 错误，因为并不总是能够将推断的类型与可以编写为注释的类型相匹配。

    ¥Inserted annotations may cause new flow errors, since it’s not always possible to match inferred type with types that can be written as annotations.

  3. 文件格式可能会受到影响。如果使用代码格式化程序（例如 prettier），建议你在 codemod 运行完成后运行它。

    ¥File formatting may be affected. If a code formatter (e.g. prettier) is used, it is recommended that you run it after the codemod has finished running.

如何应用 codemod​

¥How to apply the codemod

调用此命令的典型方法是

¥A typical way to invoke this command is

flow codemod annotate-exports \
  --write \
  --repeat \
  --log-level info \
  /path/to/folder \
  2> out.log

该命令将转换 /path/to/folder 下的文件。该目录不必是根目录（包含 .flowconfig 的目录）。

¥This command will transform files under /path/to/folder. This does not need to be the root directory (the one containing .flowconfig).

它使用以下标志：

¥It uses the following flags:

  • --write 将就地更新需要 /path/to/folder 下注释的文件。如果没有此标志，生成的文件将打印在命令行上。

    ¥--write will update files that require annotations under /path/to/folder in-place. Without this flag the resulting files will be printed on the command line.

  • --repeat 确保将应用转换，直到不再有文件更改。这种模式在这里是必要的，因为 codemod 添加的每个新类型可能需要注释新位置。

    ¥--repeat ensures that the transformation will be applied until no more files change. This mode is necessary here, because each new type the codemod adds may require new locations to be annotated.

  • --log-level info 在标准错误流中输出有用的调试信息。此选项可能会导致详细输出，因此我们将错误输出重定向到日志文件 out.log。

    ¥--log-level info outputs useful debugging information in the standard error stream. This option might lead to verbose output, so we're redirecting the error output to a log file out.log.

提供输入的另一种便捷方法是传递标志

¥Another convenient way to provide the input is by passing the flag

--input-file file.txt

其中 file.txt 包含要转换的文件的特定列表。

¥where file.txt contains a specific list of files to be transformed.

代码调制输出​

¥Codemod output

每次 codemod 迭代后，都会在 CLI 上打印摘要。此摘要包括有关添加的注释数量以及跳过的位置数量的统计信息。它还打印遇到的各种错误的计数。这些可以与日志中打印的错误相匹配。

¥After each iteration of the codemod, a summary will be printed on the CLI. This summary includes statistical information about the number of annotations that were added, and how many locations were skipped. It also prints counts for various kinds of errors that were encountered. These can be matched to the errors printed in the logs.

常见的错误情况是在文件 b.js 中推断出在文件 a.js 中定义但未导出的类型 A。codemod 将跳过添加此注释并在日志中报告错误。修复这种情况，可以在 a.js 中导出 A。请注意，无需在 b.js 中手动导入 A。codemod 会自动执行此操作。

¥A common error case is when a type A, defined in a file a.js, but not exported, is inferred in file b.js. The codemod will skip adding this annotation and report an error in the logs. The fix this case, you can export A in a.js. Note that it is not necessary to manually import A in b.js. The codemod will do this automatically.