类型算对了,为什么实现仍报错:检查边界
区分调用推导与函数体收窄,用泛型重载连接精确声明和普通实现,再验证输入输出的对应关系。
本章目录CONTENTS ↓
清理函数接受单个字符串或字符串数组:单个输入返回清理后的字符串,数组输入返回逐项清理后的数组。调用者希望保留这组对应关系,实现者则需要判断输入形态并执行相应操作。
这是同一个 API 的两项要求:声明向调用者提供信息,函数体兑现声明。精确的声明可以改善使用体验,却不能代替运行时代码,也不保证编译器能证明全部业务关系。本章沿着联合、重载与条件返回的选择,解释同一份类型关系在调用处与函数体里为何得到不同检查结果。运行时分支审查和测试方法单独进入软件设计课程。
返回值检查:表达式能否赋给承诺的类型
理解返回类型报错,先区分返回表达式自身的类型和函数承诺的返回类型。对本章显式标注返回类型的普通函数,每一处 return 都需要检查:表达式的类型能否赋给返回类型。例如:
function trimText(input: string): string { const result = input.trim(); // result: string return result; // string 可以赋给 string}
function wrongLength(input: string): number { const result = input.trim(); // result: string // @ts-expect-error string 不能赋给声明的 number return result;}能调用 trim,说明 input 支持这项操作;能返回计算结果,还需要结果满足返回类型。这是两个检查,前者通过不会使后者自动通过。
泛型函数体需要满足整份契约
T extends string 表示允许 T 取满足 string 约束的类型,包括 string 和更具体的字符串字面量类型。它不表示 T 就等于 string。看一个没有联合、收窄和条件类型的例子:
function keep<T extends string>(input: T): T { return input; // 输入本来就是 T,可以作为 T 返回}
function trimAsSame<T extends string>(input: T): T { // @ts-expect-error trim 返回 string,不能保证仍符合调用时的 T return input.trim();}如果 T 取字面量类型 " hi ",返回 T 就承诺结果仍是带空格的 " hi "。但 trim 实际得到 "hi",不符合这个承诺。string 是比该字面量更宽的类型,不能仅因两者都是字符串,就把任意 string 当作这个 T 返回。这里的拒绝揭示了真正的契约错误,而不是编译器遗漏了正确推理。官方 Working with Constrained Values 用对象约束展示了同类区别。
调用处与函数体承担不同任务:调用处利用实参推导或显式指定 T,再得到该次调用的结果类型;函数体按通用声明检查,需要对所有满足约束的 T 成立,不能只因为某一次调用可行就判定实现正确。泛型也不是把函数体中的 T 直接替换为约束后再检查。
后面的 clean 改为承诺 CleanResult:字符串输入只需返回 string,不需要保留原字面量,因此避开了 trimAsSame 的契约错误。它随后遇到的是另一件事:编译器能否从运行时分支证明条件返回类型。两种报错不能混为一谈。
普通联合实现能证明什么
先把输入输出都写成联合:
function cleanUnion(input: string | string[]): string | string[] { if (typeof input === "string") { return input.trim(); } return input.map(text => text.trim());}检查 typeof 后,字符串分支能使用 trim;另一分支剩下 string[],因此能使用 map。编译器也能检查两处返回值都属于 string|string[]。这是控制流收窄带来的保证,详见官方 Narrowing。
但对外签名没有表达“输入字符串就返回字符串”。调用 cleanUnion(" hi ") 的静态结果仍是 string|string[]。函数体中存在正确分支,不意味着对外声明自动保留了分支关系。
调用处的计算与函数体的检查不同
用条件类型表达对应关系:
type CleanResult<T extends string | string[]> = T extends string ? string : string[];
function cleanDirect<T extends string | string[]>( input: T): CleanResult<T> { if (typeof input === "string") { const value: string = input; // 通过:当前值可按 string 使用 const result: string = input.trim(); // 通过:操作结果是 string // @ts-expect-error string 仍无法被证明符合 CleanResult<T> return result; }
const value: string[] = input; // 通过:字符串路径已返回 const result: string[] = input.map(text => text.trim()); // 通过 // @ts-expect-error string[] 仍无法被证明符合 CleanResult<T> return result;}在调用处,具体实参能帮助确定 T。例如 T 是字面量类型 " hi ",CleanResult 就得到 string;T 是 string[],结果就是 string[];T 是 string|string[],条件按联合成员分配,结果为 string|string[]。
函数体内,input 已经发生了控制流收窄。字符串分支中的赋值和 trim 操作都通过,报错只发生在返回兼容检查:编译器仍需要把 result 的 string 与尚未确定的 CleanResult<T> 比较,却没有在本例中建立“当前走字符串分支,因此这个返回符合条件结果”的关联证明。它不是完全不知道返回值的类型,而是没有证明源类型符合目标类型。
| 位置 | 已知的信息 | 仍需检查什么 |
|---|---|---|
| 字符串分支中的 input | 当前值可按 string 使用 | 支持哪些操作。 |
| trim 的结果 | 表达式类型为 string | 能否作为函数承诺的结果返回。 |
| 返回类型 | 由尚未确定的 T 计算的 CleanResult | 分支结果与类型计算是否对应。 |
值检查也不等于把调用时选定的 T 改为 string。例如:
const directUnion = cleanDirect<string | string[]>(" hi ");// 本次 T 明确为 string | string[],结果类型也是 string | string[]这个调用的实际值是字符串,所以会进入字符串分支;但本次指定的 T 仍是联合。该调用用于区分当前值与类型参数,不是用来证明函数体有错误。对于这个具体 T,CleanResult 可以算出联合;通用函数体的检查却不能只代入这个 T 就结束。
控制流收窄回答“当前位置可以怎样使用这个值”;条件类型计算回答“给定某个类型参数,结果类型是什么”。 两者需要关联才能证明本例的返回,而 TypeScript 6.0.3 没有在这个写法中完成关联。条件类型是编译时的类型计算,不是在运行时执行的另一个 if;具体计算规则见官方 Conditional Types。
上述报错用 TypeScript 6.0.3 strict 实测。不要概括成“泛型不能收窄”,也不要认定所有条件返回实现都一定报错;具体能力与签名形状、编译器版本有关。官方仓库的 #33912 讨论了控制流与条件返回类型的关联问题,本章以实际例子的检查结果为准。
用泛型重载连接精确接口和普通实现
一种可维护的写法是:对外保留泛型条件返回,对内使用普通联合实现。
function clean<T extends string | string[]>(input: T): CleanResult<T>;function clean(input: string | string[]): string | string[] { if (typeof input === "string") { return input.trim(); } return input.map(text => text.trim());}
const one = clean(" hi "); // stringconst many = clean([" hi ", " ts "]); // string[]const input = Math.random() > 0.5 ? " hi " : [" hi "];const possible = clean(input); // string | string[]// @ts-expect-error 数字不在输入范围内clean(42);第一行是对外可见的重载签名,负责推导精确结果;第二行是实现签名,接住所有允许的输入,检查每个返回值属于总体输出范围。两行共同描述一个运行时函数,没有生成两个函数。
这里仅有一个泛型重载就能接受联合实参,因为其 T 可以推导成整个 string|string[]。它与两个分别只接收 string、string[] 的重载不同:后者没有一条可见签名能接住联合变量。实现签名本身也不会额外成为对外调用入口。参见官方 Function Overloads。
这个实现没有使用类型断言,但仍需要审查输入输出的配对。重载机制检查签名与实现的兼容性,没有证明每一种输入都执行了正确分支。
编译通过仍可能把关系写反
下面的实现也能通过 TypeScript 6.0.3 strict 检查:
function cleanWrong<T extends string | string[]>(input: T): CleanResult<T>;function cleanWrong(input: string | string[]): string | string[] { if (typeof input === "string") { return [input.trim()]; } return input.join(",");}
const promisedString = cleanWrong(" hi "); // 静态类型 string// 实际返回 ["hi"],是数组每处返回值都在实现签名的 string|string[] 范围内,因此总体范围检查通过。但字符串输入返回了数组,数组输入返回了字符串,违反对外的条件返回契约。
如果接着调用 promisedString.toUpperCase(),编译器按声明允许这次操作,运行时却会失败。这说明需要测试对应关系,而不只是检查“输出属于某个大联合”。
类型断言也存在这条边界:as CleanResult<T> 告诉编译器按该类型处理值,不会转换或校验实际结果。对正确实现使用局部断言,有时是应对证明能力不足的工程选择;前提是能明确说明它依赖哪些分支条件,并验证这些条件。把断言藏进辅助函数、改成双重断言,或使用 any,都不会增加运行时证据。参见官方 Type Assertions。
本章的类型保证
调用处的类型计算、函数体的收窄和返回值兼容检查是三个不同环节。泛型重载能提供精确的调用结果,但普通联合实现只检查总体返回范围;上面的反例展示了这种检查没有证明什么。类型断言也不会补上运行时证据。
本章限定同步处理、普通可变数组和已符合声明的调用输入,不承诺元组长度或字面量保持。如何从契约选择实际输入、检查分支对应关系,并验证 AI 给出的实现,继续阅读软件设计:契约如何落到实现与验证。
这一页,先记到这里。