实用提示:使用 TypeScript 保持前端与后端类型的一致性
《实用笔记》操作指南:使用 TypeScript 保持前端与后端类型同步——为采用该模式的团队提供的契约、校验机制及可直接插入的代码片段。
来源: Keeping Frontend and Backend Types in Sync with Typescript Magic
可将此内容视为《利用 TypeScript 的强大功能保持前端与后端类型同步》一文中面向开发人员的优化版本:清晰的阶段划分、有序的代码结构,以及能在交接过程中保留的恢复说明。
没有堆栈跟踪的错误
具有明确阶段的错误最适合被视作可度量的问题。在扩大处理范围之前,先记录一份关键的日志、一个故障案例以及回滚说明;同时在功能结果旁标注处理时间以及令牌或查询成本。提前了解成本情况,就能避免在从演示环境过渡到共享环境时出现意外费用。尽量保持渲染操作的成本较低,只有在经过测量后才会将高成本的计算操作放在记忆化机制之后处理。过早使用记忆化可能会掩盖过时属性带来的问题。
// backend/src/topics/topics.service.ts
async findAll(): Promise<TopicRow[]> {
return this.prisma.topic.findMany({ select: TOPIC_SELECT });
}
// frontend/src/types.ts
export interface TopicRow {
id: string;
code: string;
requiresKey: boolean;
// ...
}
为何此事变得紧急
将“为何需要紧急处理”这一阶段视为可度量的对象来处理效果最佳。在扩大范围之前,先记录一个成功的案例、一个失败案例以及回滚说明。 将配置置于应用程序代码之外。环境文件、密钥存储和功能开关应集中存放于一个位置,以便操作人员无需查看整个系统结构即可进行审计。 尽量降低渲染成本,只有在经过测量后才会将耗时的计算操作放入缓存机制中。过早使用缓存可能会掩盖过时属性带来的错误。
核心理念
将构思阶段视为可度量的对象来处理效果最佳。在扩大范围之前,先记录一个成功的案例、一个失败案例以及回滚说明。同时记录正常流程和恢复流程。重试机制、人工审核环节以及死信处理都是产品本身的一部分,而非后续需要补充的内容。尽量降低渲染成本,只有在经过评估后才将耗时的计算操作放入缓存中;过早使用缓存可能会掩盖过时属性带来的错误。
// backend/contract/assert.ts
/** The wire shape of a server value: JSON.stringify turns Date into string. */
export type Jsonify<T> = T extends Date
? string
: T extends (infer U)[]
? Jsonify<U>[]
: T extends object
? { [K in keyof T]: Jsonify<T[K]> }
: T;
/** Invariant (not merely assignable) equality - catches widened optionals. */
export type Equal<A, B> =
(<T>() => T extends A ? 1 : 2) extends (<T>() => T extends B ? 1 : 2)
? true
: false;
export type Expect<T extends true> = T;
/** The element type of a service method that resolves to an array. */
export type RowOf<T> = Jsonify<Awaited<T>> extends (infer U)[] ? U : never;
/** The resolved wire shape of a service method. */
export type ResultOf<T> = Jsonify<Awaited<T>>;
/** The row type of a paginated `{ rows, total }` service method. */
export type PagedRowOf<T> =
Jsonify<Awaited<T>> extends { rows: (infer U)[] } ? U : never;
// backend/contract/api-contract.ts
import type { Equal, Expect, PagedRowOf, RowOf } from './assert';
import type { TopicsService } from '../src/topics/topics.service';
import type { ContactRequestsService } from '../src/contact-requests/contact-requests.service';
import type { TopicRow, ContactRequestRow } from '../../frontend/src/types';
// GET /topics
export type _Topics = Expect<
Equal<RowOf<ReturnType<TopicsService['findAll']>>, TopicRow>
>;
// GET /contact-requests (paginated)
export type _ContactRequests = Expect<
Equal<PagedRowOf<ReturnType<ContactRequestsService['findAll']>>, ContactRequestRow>
>;
输入法的神奇之处,详解
将“输入法魔法解释阶段”的机制视为可测量的对象来处理,效果最佳。在扩大范围之前,先记录一个成功的案例、一个失败案例以及回滚说明。 优先选择小型且可测试的单元,而非庞大的脚本。当某一步骤失败时,故障应指向单一的责任模块,而非复杂的流程链。 尽量降低渲染成本,只有在经过测量后才将耗时的计算操作放入缓存中。过早使用缓存可能会掩盖过时属性带来的错误。
export type _Topics = Expect<
Equal<RowOf<ReturnType<TopicsService['findAll']>>, TopicRow>
>;
type Equal<A, B> = A extends B ? (B extends A ? true : false) : false; // too loose
(<T>() => T extends A ? 1 : 2) extends <T>() => T extends B ? 1 : 2
export type RowOf<T> = Jsonify<Awaited<T>> extends (infer U)[] ? U : never;
应将其连接到方法上,而非查询语句
将“将其连接到舞台”这一流程视为可测量的界面时效果最佳。在扩大范围之前,先记录一个理想案例、一个失败案例以及回滚说明。 把这一阶段视为输入与已验证输出之间的契约。为相关成果命名,明确成功标准,绝不允许出现悄无声息的半完成状态。 尽量降低渲染成本,只有在经过测量后才将耗时的推导操作置于缓存机制之后处理。过早使用缓存可能会掩盖过时属性带来的错误。 将“将其连接到舞台”这一流程视为可测量的界面时效果最佳。在扩大范围之前,先记录一个理想案例、一个失败案例以及回滚说明。 将配置信息置于应用程序代码之外。环境文件、密钥存储和功能开关应集中存放于一个位置,以便操作人员无需查看整个系统结构即可进行审计。
// Wrong: misses everything the method does after the query
Equal<Jsonify<TopicSelectResult>, TopicRow>
// Right: whatever the method actually resolves to
Equal<RowOf<ReturnType<TopicsService['findAll']>>, TopicRow>
使其运行
在“使其运行”阶段,应在修改代码之前明确输入参数、该步骤的负责人以及终止标准。操作人员应能够从已知的检查点重新运行该步骤,而无需猜测隐藏状态。 需同时记录正常流程和异常恢复流程。重试机制、人工审核环节以及错误消息处理都是产品本身的组成部分,而非后续需要补充的功能。 状态应与负责数据变更的组件放在一起。将所有数据都存放在全局存储中会使得时序错误更难被发现。
// backend/tsconfig.contract.json
{
"extends": "./tsconfig.json",
"compilerOptions": {
"noEmit": true,
"rootDir": "..", // program spans both packages
"module": "preserve",
"moduleResolution": "bundler" // resolve the way the frontend's bundler does
},
"include": ["src/**/*", "contract/**/*", "../frontend/src/types.ts"]
}
{ "scripts": { "check:contract": "tsc -p tsconfig.contract.json" } }
读取故障信息
在“读取失败”阶段,应在修改代码之前明确输入参数、该步骤的负责人以及退出标准。操作人员应能够从已知的检查点重新运行该步骤,而无需猜测隐藏状态。 相比冗长的脚本,更应采用小型、可测试的单元。当某个步骤失败时,故障原因应能指向单一责任模块,而非复杂的流程链。 状态信息应与负责数据变更的组件放在一起。将所有数据都存放在全局存储中会使得时序错误更难被发现。
type P1 = A extends B ? true : false; // false => server is narrower / has extra
type P2 = B extends A ? true : false; // false => frontend is wider
type Extra = Exclude<keyof A, keyof B>; // fields the server sends, frontend lacks
type Missing = Exclude<keyof B, keyof A>; // fields the frontend invented
其代价以及无法覆盖的范围
在修改代码之前,针对“成本”与“阶段”部分,需明确输入参数、该步骤的负责人以及终止标准。操作人员应能够从已知的检查点重新运行该步骤,而无需猜测隐藏状态。 应将此阶段视为输入与已验证输出之间的契约。为相关成果命名,定义成功判定条件,并杜绝无声的半完成状态。 将状态信息与负责数据变更的组件放在一起。若将所有数据都存放在全局存储中,会导致时序错误更难被发现。 在修改代码之前,针对“成本”与“阶段”部分,需明确输入参数、该步骤的负责人以及终止标准。操作人员应能够从已知的检查点重新运行该步骤,而无需猜测隐藏状态。 将配置信息置于应用程序代码之外。环境文件、密钥存储以及功能开关应集中存放于一个位置,以便操作人员无需查看整个系统结构即可进行审计。
核心要点
在处理“核心要点”阶段时,首先需明确契约内容:所需输入、成功信号以及部分失败时的处理方式。这份清单能确保后续的代码修改保持一致性。
同时记录正常流程与异常恢复路径。重试机制、人工审核环节以及死信处理都是产品功能的一部分,而非后续需要补充的内容。
应将各种效应视为与外部世界的同步机制,而非渲染过程中替代派生值的手段。
操作检查清单
在处理“操作检查清单”阶段时,同样需首先明确契约内容:所需输入、成功信号以及部分失败时的处理方式。这份清单能确保后续的代码修改保持一致性。
在功能结果旁记录执行时间以及令牌或查询成本。提前了解成本情况,可避免在从演示环境过渡到共享环境时出现意外费用。
应将效果视为与外部世界的同步机制,而非渲染过程中派生值的替代品。
锁定依赖版本,并记录用于运行演示的图像摘要。可重复性比经验知识更为重要。
将配置置于应用程序代码之外。环境文件、密钥存储以及功能开关应集中存放,以便操作人员无需查看整个架构即可进行审计。
应将效果视为与外部世界的同步机制,而非渲染过程中派生值的替代品。
在升级技术栈之前,先冻结版本,为关键路径生成标准记录,并确认回滚步骤。共享环境需要设置速率限制、租户检查机制,以及明确的密钥轮换负责人。与其追求花哨的一次性演示,不如注重扎实的可靠性。
关于 99a16b87e27d 的批处理说明:不要将提供者密钥放入代码仓库,为每个会话设置令牌上限,并将转录内容存储在评估测试用例的旁边,以便后续更换模型时仍能保持可比性。