JavaScript / TypeScript / 系统课时
项目需求与类型设计
项目需求与类型设计
类型设计不是把现有 JSON 字段逐个翻译成接口,而是先从需求中找出稳定实体、合法状态和系统边界。本篇以任务管理需求为例,把“哪些状态允许出现”直接编码进类型,并在外部数据进入领域模型前完成运行时校验。
学习目标
- 从需求描述中识别实体、状态变量与不变量
- 用可辨识联合类型排除非法状态组合
- 在
unknown边界上完成校验,再进入业务函数
先找不变量再写类型
假设需求只有三条:任务包含 id 和标题;状态只能是待办、进行中或完成;只有完成状态必须记录完成时间。这里真正值得进入类型系统的不是页面字段,而是“完成状态一定有 completedAt”这个不变量。
如果直接写成 status: string 加 completedAt?: string,那么“状态为 done 但没有完成时间”仍然是合法类型。更合适的模型是把不同状态拆成联合成员,让每个成员只保留该状态真正允许的字段。

用联合类型表达合法状态
下面的示例同时包含领域类型、边界校验和一个“完成任务”操作,可以直接保存为 task-model.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));运行命令:
npx tsc task-model.ts --strict --target ES2022 --module commonjs
node task-model.js预期输出:
{"id":"T-100","title":"Design core types","status":"done","completedAt":"2026-09-01T12:00:00Z"}这里 completeTask 只接受 OpenTask,因此已经完成的任务不能在没有显式处理的情况下再次进入该操作。与此同时,parseTask 接受 unknown 而不是强制断言为 Task,保证外部 API、文件或消息队列的数据必须先经过运行时检查。
把边界类型和领域类型分开
外部系统通常允许缺字段、旧枚举值或尚未迁移的数据,因此不要让接口响应类型直接等同于领域模型。边界层负责“它实际上是什么”,领域类型负责“进入业务后允许是什么”。
当需求继续增长时,优先检查不变量是否改变。例如新增“取消”状态,应增加新的联合成员,并让所有依赖 task.status 的分支重新接受类型检查;这比在多个函数里散落字符串判断更容易发现遗漏。
用变化频率决定类型边界
实体字段、状态机和跨层契约通常值得建成稳定类型;只服务某个页面的临时展示字段,则更适合留在 UI 层。一个实用判断是:如果字段变化会影响多个业务函数或改变合法状态集合,它应该进入领域模型;如果变化只影响单个展示组件,就不应污染核心类型。
好的类型设计最终应让非法状态更难被构造、外部数据必须先被验证、业务函数只处理自己真正允许的输入。这样后续需求变化时,编译错误会集中暴露受影响位置,而不是依赖人工搜索字符串。