契约如何落到实现与验证

从字符串清理的具体需求建立输入输出约定,划分类型检查与行为验证,并用反例审查实现。

本章目录CONTENTS ↓

一个清理函数接受单个字符串或字符串数组。单个输入返回去掉首尾空格的字符串,数组输入返回逐项清理后的数组。这样的需求看起来很小,却足以展示程序设计中三个不同的问题:我们到底承诺了什么,怎样组织实现,以及凭什么相信实现兑现了承诺。

先把契约写清楚,比直接让 AI 生成函数更有用。本例限定同步调用和普通字符串数组,不处理外部数据解析;批量输入保持顺序和重复项,空数组得到空数组,空字符串仍得到空字符串。这里的约定来自本例需求,不是所有清理工具都必须采用的规则。

从总体范围到逐输入的保证

只写“输入和输出都可以是字符串或数组”不够。一个函数完全可以在输入字符串时返回数组,在输入数组时返回字符串,依然没有超出这两种类型的总体范围。真正的要求还包含输入输出之间的关系。

输入条件 输出形状 输出内容
一个字符串 一个字符串 去掉该字符串首尾空格。
一个字符串数组 一个数组 按原顺序清理每一项,保留数量与重复项。
空数组 空数组 不凭空添加元素。

当实现交给 AI 时,这张表给出了可检查的工作边界。不能只要求“写一个 clean 函数”,然后把能够编译当成完成。

让分支对应契约

本例只有两个输入形态,用一个分支直接对应两条规则即可。没有必要为了体现设计而增加模块或类。

function clean(input: string | string[]): string | string[] {
if (typeof input === "string") return input.trim();
return input.map(text => text.trim());
}

第一条路径只处理单个字符串;第二条路径逐项生成结果。这里的普通联合签名足以展示实现,代价是调用处的结果类型较宽。希望字符串调用得到精确 string 提示时,可以增加类型声明;相关泛型、条件返回与重载检查单独见 TS 类型检查边界。

比较下面的错误实现:

function cleanWrong(input: string | string[]): string | string[] {
if (typeof input === "string") return [input.trim()];
return input.join(",");
}

它没有返回联合范围之外的值,所以类型检查可能通过,却违反了上表的关系。增加一个更精确的对外声明也不能修复这段运行代码;需要检查真实分支及其结果。

用有针对性的输入检查实现

类型检查验证声明允许的调用和静态结果;行为测试则执行函数,比较真实值与契约。两者检查的对象不同。

function checkClean(input: string | string[], expected: string | string[]): void {
const actual = clean(input);
const sameShape = Array.isArray(actual) === Array.isArray(expected);
const sameValue = JSON.stringify(actual) === JSON.stringify(expected);
if (!sameShape || !sameValue) throw new Error("清理结果不符合约定");
}
checkClean(" hi ", "hi");
checkClean([" hi ", " ts "], ["hi", "ts"]);
checkClean([], []);
checkClean("", "");
checkClean([" a ", " a "], ["a", "a"]);

这里比较的是字符串或字符串数组,JSON.stringify 足以比较这些案例的值,不是任意对象的通用相等算法。将检查里的 clean 换成 cleanWrong,单个非空字符串和非空数组案例就能揭示错误。

单个与数组覆盖两类输入;不同数组元素帮助发现顺序或内容错误;空数组检查空输入行为;重复项检查实现是否意外去重。有限案例不能证明所有输入都正确,但可以针对已识别的风险提供证据,再与代码审查相互补充。

需求变化时重新划定责任

如果以后接收的是网络传来的未知数据,就要新增输入验证责任:先判断值是否满足约定,再交给清理函数。若以后需要异步处理,则返回时机、失败传播和测试等待方式都要重新约定。这些变化不应仅靠修改 TypeScript 的返回标注来“完成”。

同样,分页配置是否采用默认值、异常是否转换为结果对象、批量任务是否允许部分成功,首先是行为契约的选择。确定行为后,类型课程再研究如何表达可选参数、结果联合及参数关联。两类工作相互支持,但学习目标不同。

从抽象与建模到本章,关注点从“保留哪些信息”推进到“操作承诺什么、实现如何兑现”。审查 AI 实现时,先对照契约,再看分支与边界案例;代码短、类型精确或测试通过,都需要放回具体保证中判断。

类型检查的具体边界可查官方 Function Overloads 与 Type Assertions。本章案例用于解释与验证上述契约,不声称某种结构适用于所有程序。

这一页,先记到这里。