我所理解的 TypeScript 最佳实践(18):用判别联合排除互斥的状态组合
- 为什么选择 TypeScript
- 严格模式
- 使用常量枚举来管理状态
- 按运行环境处理 TypeScript 代码
- 类型检查、Lint 与测试
- TypeScript 7 升级与工具链兼容
- 用 satisfies 检查类型并保留推断
- 用 import type 区分类型依赖和运行时依赖
- 用对象类型表达字段约束
- 用联合类型表达备选,用交集类型叠加约束
- 用元组描述位置固定的数据
- 用泛型保留类型关系,用 extends 写约束和条件
- 按目标类型判断赋值是否成立
- 按输入和输出设计泛型的协变与逆变
- 先校验外部数据,再使用收窄后的类型
- 让局部实现保留推断,用注解约束公开接口
- 从一份定义派生配置、命令和事件的类型
- 用判别联合排除互斥的状态组合(当前)
- 用 never 表示没有值的类型
- 用逆向映射推断还原字段类型
保存文档时,界面要知道现在是否正在写入、何时保存成功,以及失败时显示什么。可以给每一项单独放一个字段,但每次更新都要记住清理旧值。同一次保存只能有一个结果时,适合用一个状态字段表示当前阶段,再让每个阶段带上对应的数据。
多个字段可以表达业务上不成立的组合
几个字段各自更新,界面就可能收到这样的组合。进度提示显示仍在保存,成功提示却已经出现,错误栏还留着上一次的失败原因。
type SaveFlags = {
error?: string;
isSaved: boolean;
isSaving: boolean;
savedAt?: Date;
};
const inconsistent: SaveFlags = {
error: '磁盘空间不足',
isSaved: true,
isSaving: true,
};
如果保存开始时只改 isSaving,上一次的结果和错误就可能仍出现在界面上。把所有字段清理一遍也能修复,但清理规则需要在每个更新点重复维护。这里关注的是同一次保存任务。如果界面还要保留上次保存时间,那是文档的历史信息,可以独立于当前任务状态存放。
每种状态声明自己需要的数据
status 为每个成员提供一个不同的字面量。一次状态更新直接构造一个完整的新成员。正在保存时记录开始时间,成功后记录完成时间,失败时保留能展示的原因。
status |
当前状态携带的数据 | 什么时候进入 |
|---|---|---|
idle |
无 | 还没有开始保存 |
saving |
startedAt |
发起保存 |
saved |
savedAt |
写入成功 |
failed |
error |
写入失败 |
type SaveState = { status: 'idle' } | { startedAt: Date; status: 'saving' } | { savedAt: Date; status: 'saved' } | { error: string; status: 'failed' };
const initialState: SaveState = { status: 'idle' };
const failedState: SaveState = { error: '磁盘空间不足', status: 'failed' };
// @ts-expect-error 保存成功必须提供保存时间。
const incomplete: SaveState = { status: 'saved' };
// @ts-expect-error 正在保存时不能在对象字面量里写入失败原因。
const invalid: SaveState = { error: '磁盘空间不足', startedAt: new Date(), status: 'saving' };
读取状态时,先判断 status,再读取该成员声明的字段。例如 state.status === 'failed' 成立后,state.error 是必填的字符串。对于已有变量,TypeScript 的结构类型仍可能允许未声明的额外字段。更新时直接构造新状态。展开旧对象会把上一阶段的字段带进来。关于额外字段如何参与赋值,见《按目标类型判断赋值是否成立》。
用一次任务的开始和结束演示状态转换
保存按钮可以在 saving 状态下禁用。应用启动任务时立即写入 saving,成功和失败分别构造自己的结果。这段代码假设同一个编辑器只有一个保存任务在执行。
type SaveState = { status: 'idle' } | { startedAt: Date; status: 'saving' } | { savedAt: Date; status: 'saved' } | { error: string; status: 'failed' };
function createDraftSaver(writeDraft: () => Promise<void>) {
let state: SaveState = { status: 'idle' };
function getState(): SaveState {
return state;
}
async function save() {
if (state.status === 'saving') {
return;
}
state = { startedAt: new Date(), status: 'saving' };
try {
await writeDraft();
state = { savedAt: new Date(), status: 'saved' };
} catch (error) {
state = { error: error instanceof Error ? error.message : '保存失败', status: 'failed' };
}
}
return { getState, save };
}
这里的运行时逻辑负责限制一次只能保存一个任务。SaveState 约束的是单个状态值的形状,允许哪些转换、异步结果能否覆盖当前状态,仍要靠更新逻辑决定。例如用户切换文档后,旧任务可能才结束。多个任务共享同一状态时,可以用任务标识核对归属,或者为每份文档保留自己的状态。
用 never 找出新增状态后遗漏的显示分支
把渲染文案的函数接到上面的 SaveState。四个状态都处理完后,default 中剩下的类型应为 never。若以后增加 'cancelled',这里会报错,提醒维护者给取消状态提供文案。
function getSaveStatusLabel(state: SaveState): string {
switch (state.status) {
case 'idle':
return '尚未保存';
case 'saving':
return '正在保存';
case 'saved':
return `已于 ${state.savedAt.toLocaleTimeString()} 保存`;
case 'failed':
return state.error;
default: {
const unhandled: never = state;
throw new Error(`未处理的保存状态 ${JSON.stringify(unhandled)}`);
}
}
}
never 的检查适用于应用内部已经确认类型的值。若状态来自磁盘或 IPC,先检查外部输入,再交给这个函数。联合的收窄和穷尽检查见 TypeScript 手册。
保存阶段彼此互斥,适合放在同一个联合里。文档是否还有未保存的编辑、当前是否只读、窗口是否联网,都可以独立变化。比如写入期间用户又输入了一行,这份文档可以同时处于 saving 且有未保存的改动。把这样的事实留成独立字段,保存状态只负责描述当前任务。