JavaScript / TypeScript / 系统课时

项目需求与类型设计

项目需求与类型设计

类型设计不是把现有 JSON 字段逐个翻译成接口,而是先从需求中找出稳定实体、合法状态和系统边界。本篇以任务管理需求为例,把“哪些状态允许出现”直接编码进类型,并在外部数据进入领域模型前完成运行时校验。

学习目标

  • 从需求描述中识别实体、状态变量与不变量
  • 用可辨识联合类型排除非法状态组合
  • 在 unknown 边界上完成校验,再进入业务函数

先找不变量再写类型

假设需求只有三条:任务包含 id 和标题;状态只能是待办、进行中或完成;只有完成状态必须记录完成时间。这里真正值得进入类型系统的不是页面字段,而是“完成状态一定有 completedAt”这个不变量。

如果直接写成 status: string 加 completedAt?: string,那么“状态为 done 但没有完成时间”仍然是合法类型。更合适的模型是把不同状态拆成联合成员,让每个成员只保留该状态真正允许的字段。

从需求到 TypeScript 领域类型的映射

用联合类型表达合法状态

下面的示例同时包含领域类型、边界校验和一个“完成任务”操作,可以直接保存为 task-model.ts 运行。

ts
type TodoTask = {
  id: string;
  title: string;
  status: "todo";
};

type DoingTask = {
  id: string;
  title: string;
  status: "doing";
};

type DoneTask = {
  id: string;
  title: string;
  status: "done";
  completedAt: string;
};

type Task = TodoTask | DoingTask | DoneTask;
type OpenTask = TodoTask | DoingTask;

function isRecord(value: unknown): value is Record<string, unknown> {
  return typeof value === "object" && value !== null;
}

function parseTask(input: unknown): Task {
  if (!isRecord(input)) {
    throw new Error("task must be an object");
  }

  const { id, title, status } = input;
  if (typeof id !== "string" || typeof title !== "string") {
    throw new Error("id and title must be strings");
  }

  if (status === "todo" || status === "doing") {
    return { id, title, status };
  }

  if (status === "done" && typeof input.completedAt === "string") {
    return { id, title, status, completedAt: input.completedAt };
  }

  throw new Error("invalid task state");
}

function completeTask(task: OpenTask, completedAt: string): DoneTask {
  return {
    id: task.id,
    title: task.title,
    status: "done",
    completedAt
  };
}

const payload: unknown = {
  id: "T-100",
  title: "Design core types",
  status: "todo"
};

const task = parseTask(payload);
if (task.status === "done") {
  throw new Error("task is already done");
}

const done = completeTask(task, "2026-09-01T12:00:00Z");
console.log(JSON.stringify(done));

运行命令:

bash
npx tsc task-model.ts --strict --target ES2022 --module commonjs
node task-model.js

预期输出:

text
{"id":"T-100","title":"Design core types","status":"done","completedAt":"2026-09-01T12:00:00Z"}

这里 completeTask 只接受 OpenTask,因此已经完成的任务不能在没有显式处理的情况下再次进入该操作。与此同时,parseTask 接受 unknown 而不是强制断言为 Task,保证外部 API、文件或消息队列的数据必须先经过运行时检查。

把边界类型和领域类型分开

外部系统通常允许缺字段、旧枚举值或尚未迁移的数据,因此不要让接口响应类型直接等同于领域模型。边界层负责“它实际上是什么”,领域类型负责“进入业务后允许是什么”。

当需求继续增长时,优先检查不变量是否改变。例如新增“取消”状态,应增加新的联合成员,并让所有依赖 task.status 的分支重新接受类型检查;这比在多个函数里散落字符串判断更容易发现遗漏。

用变化频率决定类型边界

实体字段、状态机和跨层契约通常值得建成稳定类型;只服务某个页面的临时展示字段,则更适合留在 UI 层。一个实用判断是:如果字段变化会影响多个业务函数或改变合法状态集合,它应该进入领域模型;如果变化只影响单个展示组件,就不应污染核心类型。

好的类型设计最终应让非法状态更难被构造、外部数据必须先被验证、业务函数只处理自己真正允许的输入。这样后续需求变化时,编译错误会集中暴露受影响位置,而不是依赖人工搜索字符串。

按自己的节奏,确认真正理解。

目录与阅读设置

阅读设置

17

记录一个想法

项目需求与类型设计

0 / 10000 · 笔记保存到账号。未提交的修改会在关闭、离开或刷新后丢失。

登录哪都通