跳到正文

我所理解的 TypeScript 最佳实践(18):用判别联合排除互斥的状态组合

我所理解的 TypeScript 最佳实践

  1. 为什么选择 TypeScript
  2. 严格模式
  3. 使用常量枚举来管理状态
  4. 按运行环境处理 TypeScript 代码
  5. 类型检查、Lint 与测试
  6. TypeScript 7 升级与工具链兼容
  7. 用 satisfies 检查类型并保留推断
  8. 用 import type 区分类型依赖和运行时依赖
  9. 用对象类型表达字段约束
  10. 用联合类型表达备选,用交集类型叠加约束
  11. 用元组描述位置固定的数据
  12. 用泛型保留类型关系,用 extends 写约束和条件
  13. 按目标类型判断赋值是否成立
  14. 按输入和输出设计泛型的协变与逆变
  15. 先校验外部数据,再使用收窄后的类型
  16. 让局部实现保留推断,用注解约束公开接口
  17. 从一份定义派生配置、命令和事件的类型
  18. 用判别联合排除互斥的状态组合(当前)
  19. 用 never 表示没有值的类型
  20. 用逆向映射推断还原字段类型

保存文档时,界面要知道现在是否正在写入、何时保存成功,以及失败时显示什么。可以给每一项单独放一个字段,但每次更新都要记住清理旧值。同一次保存只能有一个结果时,适合用一个状态字段表示当前阶段,再让每个阶段带上对应的数据。

多个字段可以表达业务上不成立的组合

几个字段各自更新,界面就可能收到这样的组合。进度提示显示仍在保存,成功提示却已经出现,错误栏还留着上一次的失败原因。

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 且有未保存的改动。把这样的事实留成独立字段,保存状态只负责描述当前任务。