Flow 中默认类型参数的 TS 到 Flow 迁移实战:以 default_type_params 评测用例为范例
Flow 中默认类型参数的 TS 到 Flow 迁移实战:以 default_type_params 评测用例为范例
导读
本文以 Flow 官方评测仓库 evals/evals/04_ts_to_flow 中的 default_type_params 用例为骨架,讲解如何把 TypeScript 中的默认类型参数(Default Type Parameters)忠实迁移为地道的(idiomatic)Flow 代码。你将掌握 Flow 中类型参数默认值的声明语法、省略类型实参的 Page<> 写法、联合分发与默认值展开等关键细节,并了解该评测的 AST 评分机制,可用于自查迁移结果。
一、评测背景:这是什么任务
evals/evals/04_ts_to_flow/default_type_params/prompt.md 的任务指令非常精炼:
The file
source.tscontains a TypeScript module. Convert it to idiomatic Flow inmain.js, preserving the runtime behavior and the precision of every type.
翻译过来就是:source.ts 里是一个 TypeScript 模块,请把它转换成 main.js 中地道的 Flow 代码,并且要保持运行时行为不变、每一个类型的精度不丢失。整个 04_ts_to_flow 分类共包含 40+ 个此类用例(如 anonymous_interface_param、conditional_types_infer、utility_types_filter_collections 等),每个用例目录结构一致,见 分类 README:
<name>/
├── prompt.md # 转换指令
├── config.json # 元数据 + 评分器(flow_check + AST 评分器)
├── input/
│ ├── source.ts # 待转换的 TypeScript(评分时忽略 .ts)
│ ├── main.js # “// @flow” + TODO 占位
│ └── .flowconfig # React 用例会启用额外实验选项
└── ideal/
└── main.js # 参考解(gold patch)
评分时的金标准补丁(gold patch)就是 diff(input/, ideal/) 的产物,评测通过 run_swebench.py 与 Makefile 驱动,可用 make validate 或 python3 run_swebench.py --dry-run --flow-bin "$FLOW_BIN" --eval default_type_params 进行验证。
二、原始 TypeScript:默认类型参数如何工作
先看待转换的 TypeScript 源码 evals/evals/04_ts_to_flow/default_type_params/input/source.ts:
type ApiError = {code: number; message: string};
type ApiResult<T, E = ApiError> =
| {ok: true; value: T}
| {ok: false; error: E};
type Page<TItem = string, TCursor = number> = {
items: TItem[];
cursor: TCursor;
};
type StringResult = ApiResult<string>;
type DefaultPage = Page;
function describe(result: StringResult): string {
return result.ok ? result.value : result.error.message;
}
function firstItem(page: DefaultPage): string {
return page.items[0];
}
const ok: StringResult = {ok: true, value: 'hi'};
const page: DefaultPage = {items: ['a', 'b'], cursor: 0};
console.log(describe(ok), firstItem(page), page.cursor);
这段代码涉及两个 TS 类型层面的关键点:
- 带默认值的类型参数:
ApiResult<T, E = ApiError>中E缺省为ApiError;Page<TItem = string, TCursor = number>中TItem缺省为string、TCursor缺省为number。 - “全缺省”的裸引用:
type DefaultPage = Page;直接引用Page而不写任何类型实参,等价于Page<string, number>;ApiResult<string>则只显式提供T,让E落到默认值ApiError上。
运行时部分很简单:describe 判别联合上的 ok 字段后读取 value 或 error.message;firstItem 返回数组首元素;最后打印三者的组合。迁移的目标就是把这套类型精度原封不动地搬进 Flow。
三、目标 Flow 代码:逐行对照
参考解位于 evals/evals/04_ts_to_flow/default_type_params/ideal/main.js:
/**
* Copyright (c) Meta Platforms, Inc. and affiliates.
*
* This source code is licensed under the MIT license found in the
* LICENSE file in the root directory of this source tree.
*
* @flow
*/
type ApiError = {code: number, message: string};
type ApiResult<T, E = ApiError> =
| {ok: true, value: T}
| {ok: false, error: E};
type Page<TItem = string, TCursor = number> = {
items: Array<TItem>,
cursor: TCursor,
};
type StringResult = ApiResult<string>;
type DefaultPage = Page<>;
function describe(result: StringResult): string {
return result.ok ? result.value : result.error.message;
}
function firstItem(page: DefaultPage): string {
return page.items[0];
}
const ok: StringResult = {ok: true, value: 'hi'};
const page: DefaultPage = {items: ['a', 'b'], cursor: 0};
console.log(describe(ok), firstItem(page), page.cursor);
3.1 语法层面的三点差异
| 维度 | TypeScript | Flow(参考解) |
|---|---|---|
| 对象类型分隔符 | ; / , 均可 |
统一使用 , |
| 数组类型 | TItem[] |
Array<TItem> |
| 全缺省引用 | type DefaultPage = Page; |
type DefaultPage = Page<>; |
其中 Page<> 是本次迁移最关键的一处:Flow 中裸写 Page 会被解析为对类型别名本身的引用(泛型参数未绑定),必须显式写出空的类型实参列表 <>,才能表示“使用所有默认参数”的实例化。这也是 TS 迁移到 Flow 时最常见的坑之一——TS 允许省略全部实参,Flow 则要求 <> 占位。
3.2 默认参数与省略规则的继承
ApiResult<string>在 Flow 中同样成立:只传T = string,E落到默认值ApiError,因此describe中result.error.message能被正确类型化。Page<TItem = string, TCursor = number>的两个默认值原样保留;DefaultPage = Page<>等价于Page<string, number>,所以firstItem(page)返回string,page.cursor是number,与运行时代码console.log输出完全一致。
3.3 判别联合与可辨识字段
ApiResult<T, E> 的 ok: true / ok: false 是可辨识字段(discriminant),describe 里的 result.ok ? ... : ... 属于联合收窄(refinement)。这一点 TS 与 Flow 语义一致,迁移时原样保留即可,无需改写成 switch 或 match(match 语法仅用于新增代码场景,见 分类 README 的设计说明)。
四、评分机制:如何保证“地道的 Flow”
该用例的评分配置见 evals/evals/04_ts_to_flow/default_type_params/config.json:
{
"metadata": {
"name": "default_type_params",
"category": "ts_to_flow",
"tags": [
"flow", "ts_to_flow", "generics",
"default_type_parameters", "type_arguments"
],
"difficulty": "medium"
},
"grading": {
"graders": [
{
"type": "ast_query",
"selector": ".type == \"TypeParameter\" and .default != null"
}
]
}
}
该用例的难度为 medium,评分方式是一个 AST 查询评分器:在转换产物中必须存在 .default != null 的 TypeParameter 节点,即至少一个类型参数带默认值。如果迁移时把 E = ApiError、TItem = string、TCursor = number 这三个默认值丢掉,AST 中就找不到带默认值的类型参数,评分直接失败。
AST 查询评分器在 evals/graders/ast_query.sh 中实现。同目录下还有 flow_check.sh(跑 flow check)、no_any.sh(禁止 any)、no_flowfixme.sh(禁止 $FlowFixMe)等辅助评分器,共同保证“类型精度不丢失”。
另外注意分类 README 的硬性约束:flow check 会标记 $ReadOnly、$ReadOnlyArray、mixed、+ 协变、<T: Bound> 等已废弃写法,所以迁移必须使用现代拼写(现代拼写完整对照表见分类 README 中提到的 FEATURE_COVERAGE.md 设计)。本例中 Array<TItem> 就比 TItem[] 更符合“地道的现代 Flow”要求。
五、从源码看 Flow 对默认类型参数的支持
Flow 解析器与类型检查器对默认类型参数(TypeParameter.default)的完整支持可以在仓库源码中印证:
- 解析端:在 src/parser 目录下搜索
TypeParameterDefault、typeParameterDefault相关实现,可以看到解析器在读取<T = Default>语法后把默认类型挂到TypeParameter节点上,这正是 AST 评分器选择.default != null的依据。 - 类型端:泛型实例化时“缺省实参回退到默认值”的逻辑,体现在 src/typing 与 src/typing_inference_js.ml 等模块对
TypeParameterInstantiation的处理中——当实参数量少于形参数量时,会用声明里的默认类型补齐。 - 你可以在 tests/generics 与 tests/type_param_defaults 中找到大量关于默认类型参数的回归测试,例如省略实参、部分提供实参、默认值引用其他类型参数等边界场景。
从源码结构可以推断:Flow 在实例化泛型时对“显式 <> + 全默认值”与“部分实参”走同一套默认值补齐逻辑,因此 Page<> 与 ApiResult<string> 在类型精度上是等价的——这也是本用例要求“preserving the precision of every type”的底层保证。
六、迁移要点速查与自查清单
针对“默认类型参数”这一类 TS→Flow 转换任务,可总结出以下 checklist:
- 默认值语法原样保留:
<T, E = ApiError>两种语言语法一致,直接照搬。 - 全缺省必须写
<>:type DefaultPage = Page<>;,绝不能写成type DefaultPage = Page;(后者在 Flow 中含义不同,且会被flow check报错)。 - 数组用
Array<T>:避免T[]后缀写法(flow check会标记$ReadOnlyArray等废弃拼写,尽量用现代拼写)。 - 对象字段分隔符用
,:符合 Flow 惯例。 - 保留判别联合与收窄:
ok字段判别 + 三元收窄无需改写。 - 自查 AST:确认产物中存在
.default != null的TypeParameter节点(对应评分器 ast_query.sh 的 selector),且flow check零错误。
七、结语
default_type_params 这个用例看似小巧,却精准覆盖了 TS→Flow 迁移中“类型参数默认值”这一高频场景:默认值的声明、部分省略、全省略的 <> 写法,以及如何用 AST 评分器自动化约束迁移质量。掌握这套模式后,你可以举一反三,把同一思路应用到同目录下其他泛型相关用例(如 const_type_parameters、conditional_types_infer),并在自己的项目中用 flow check 与 AST 断言守住“类型精度不丢失”这条底线。