深入 TypeScript 泛型从基础语法到企业级抽取基准中的类型实践【免费下载链接】wigoloThe go-to web for your AI coding agent — local-first search, fetch, crawl research over MCP. No API keys, no cloud, $0/query. Public beta.项目地址: https://gitcode.com/GitHub_Trending/wi/wigolo导读TypeScript 泛型Generics是构建一次编写、类型复用代码的关键机制。本文以 golden/article-001.md 这份金标准文档的完整内容为骨架系统讲解泛型函数、泛型约束、泛型接口、泛型类、映射类型与条件类型的进阶用法并附上一个可落地的 API Client 综合示例。与此同时本仓库 wigolo 恰好把这份文档作为 HTML→Markdown 抽取评测的金标准样例见 manifest.json因此文末会结合 runner.ts 与 metrics.ts 的源码说明用这类带代码块、表格、链接的技术文章衡量抽取器质量的真实工程场景。读完本文你既能掌握 TypeScript 泛型的完整知识链也能理解技术文档如何被当作结构化评测数据的底层逻辑。为什么需要泛型Why GenericsTypeScript 泛型提供了一种编写可与多种类型协同工作的复用组件的方式是类型系统中最强大的能力之一。如果没有泛型你会被迫在两种糟糕选择间二选一要么使用any彻底放弃类型安全要么为每个类型重复编写几乎相同的函数function identityString(arg: string): string { return arg; } function identityNumber(arg: number): number { return arg; }而使用泛型只需编写一个函数即可同时获得类型安全与代码复用function identityT(arg: T): T { return arg; } const str identitystring(hello); // type: string const num identitynumber(42); // type: numberT在这里是一个类型参数type parameter它把入参类型与返回值类型绑定为同一个类型调用时由 TypeScript 推断或用尖括号显式指定。这正体现了 golden 文档在标题里强调的核心理念用泛型消灭any的同时保持 DRYDont Repeat Yourself。泛型约束Generic Constraints并非所有类型都适合某个泛型函数。用extends关键字可以限制允许传入的类型范围让编译器在类型层面替你拦截非法调用interface Lengthwise { length: number; } function logLengthT extends Lengthwise(arg: T): T { console.log(arg.length); return arg; } logLength(hello); // OK, string has .length logLength([1, 2, 3]); // OK, array has .length // logLength(42); // Error: number has no .length约束的意义在于函数体内可以安全地访问约束所声明的成员这里就是.length超出约束的类型在编译期直接报错而不是在运行时才暴露问题。泛型接口Generic Interfaces泛型可以作用于接口构造出灵活、可复用的数据结构契约。文档给出了一个典型的仓储Repository模式用RepositoryT定义通用的数据访问契约再用具体的User类型实现它interface RepositoryT { getById(id: string): PromiseT; getAll(): PromiseT[]; create(item: T): PromiseT; update(id: string, item: PartialT): PromiseT; delete(id: string): Promisevoid; } interface User { id: string; name: string; email: string; } class UserRepository implements RepositoryUser { private users: Mapstring, User new Map(); async getById(id: string): PromiseUser { const user this.users.get(id); if (!user) throw new Error(User ${id} not found); return user; } async getAll(): PromiseUser[] { return Array.from(this.users.values()); } async create(item: User): PromiseUser { this.users.set(item.id, item); return item; } async update(id: string, item: PartialUser): PromiseUser { const existing await this.getById(id); const updated { ...existing, ...item }; this.users.set(id, updated); return updated; } async delete(id: string): Promisevoid { this.users.delete(id); } }注意两个容易被忽视的类型细节update使用PartialT表示只更新部分字段delete返回Promisevoid表示不关心返回值。泛型接口让UserRepository、OrderRepository等实现共享同一套契约调用方无需关心具体实现类型。泛型类Generic Classes类同样可以使用类型参数构建类型安全的数据结构。文档给出了一个经典的栈实现class StackT { private items: T[] []; push(item: T): void { this.items.push(item); } pop(): T | undefined { return this.items.pop(); } peek(): T | undefined { return this.items[this.items.length - 1]; } get size(): number { return this.items.length; } } const numberStack new Stacknumber(); numberStack.push(1); numberStack.push(2); console.log(numberStack.pop()); // 2实例化时通过new Stacknumber()固定元素类型后push(字符串)会在编译期被拒绝。pop/peek返回T | undefined的处理方式也展示了泛型与联合类型配合时如何诚实地表达可能没有值。映射类型与泛型的组合Mapped Types with Generics泛型与映射类型mapped types结合可以对既有类型的每个属性进行统一变换这是类型层面最常见的元编程手段type ReadonlyT { readonly [P in keyof T]: T[P]; }; type OptionalT { [P in keyof T]?: T[P]; }; type NullableT { [P in keyof T]: T[P] | null; }; interface Config { host: string; port: number; debug: boolean; } type ReadonlyConfig ReadonlyConfig; type OptionalConfig OptionalConfig;keyof T取出T的全部属性名[P in keyof T]遍历这些属性名并为每个属性生成一个新的类型T[P]通过索引访问保留原属性类型。映射类型可叠加使用例如ReadonlyPartialConfig就是所有属性可选且只读的新类型——这正是许多配置对象在初始化完成后想要锁定的形态。条件类型Conditional Types条件类型让泛型具备了类型层面的分支逻辑配合infer关键字还能从复杂类型中提取内部类型type IsStringT T extends string ? yes : no; type A IsStringstring; // yes type B IsStringnumber; // no type ExtractPromiseT T extends Promiseinfer U ? U : T; type C ExtractPromisePromisestring; // string type D ExtractPromisenumber; // numberT extends U ? X : Y的语义是若T可赋值给U则结果类型为X否则为Y。infer U则声明一个待推断的类型变量U由编译器从Promise...内部反推出来。条件类型常用于编写ReturnTypeT、ParametersT这类工具类型或在strict模式下实现精确的窄化。综合实战泛型 API Client文档最后给出了一个把多种泛型模式组合在一起的真实示例——一个通用 API 客户端。ApiResponseT描述统一响应外壳PaginatedResponseT在T[]之上扩展分页字段ApiClient的方法借助泛型在调用点注入业务类型interface ApiResponseT { data: T; status: number; message: string; timestamp: string; } interface PaginatedResponseT extends ApiResponseT[] { total: number; page: number; pageSize: number; hasNext: boolean; } class ApiClient { constructor(private baseUrl: string) {} async getT(path: string): PromiseApiResponseT { const response await fetch(${this.baseUrl}${path}); return response.json(); } async getPaginatedT( path: string, page: number 1, pageSize: number 20, ): PromisePaginatedResponseT { const response await fetch( ${this.baseUrl}${path}?page${page}pageSize${pageSize}, ); return response.json(); } } const client new ApiClient(https://api.example.com); const users await client.getPaginatedUser(/users, 1, 10); console.log(users.data); // User[] console.log(users.hasNext); // booleangetPaginatedUser调用一次users.data即为User[]、users.hasNext即为boolean全程无需任何类型断言。这是泛型让调用点获得完整类型信息的典型收益。快速回顾表FeatureSyntaxUse CaseGeneric Functionfunction fnT(arg: T): TReusable functionsGeneric Interfaceinterface RepoTFlexible contractsGeneric Classclass StackTType-safe data structuresConstraintsT extends BaseRestrict allowed typesConditionalT extends U ? X : YType-level branchingMapped{ [P in keyof T]: ... }Transform existing types延伸泛型技术文章如何成为 wigolo 抽取基准泛型是编写类型安全、可复用 TypeScript 代码的基石它消除了对any的依赖同时保持代码 DRY。而在本仓库中这篇泛型教程还有另一重身份它是一份金标准golden数据。在 manifest.json 中article-001条目声明了category: article、expectedExtractor: defuddle其 HTML 源稿与 Markdown 金标准分别存放在 fixtures 目录下用于检验 HTML→Markdown 抽取器的还原质量。评测链路在 runner.ts 中每个条目读取 HTML fixture 后调用抽取流水线将得到的markdown与 golden 文档交给 metrics.ts 计算指标。度量方法值得留意——tokenizer.ts 先做normalizeText剥掉标题标记、列表标记、代码围栏、链接与图片语法再按字母数字边界切分成 token随后在 metrics.ts 中计算 token 级别的 Precision / Recall / F1并用最长公共子序列LCS计算 ROUGE-L还校验抽取结果的标题数与链接数是否与 golden 完全一致。正因为 golden 文章里同时含有内联代码、代码围栏、表格、链接和分级标题它天然覆盖了抽取器最容易失真的结构代码块是否完整保留、表格管道符是否被正确转换、链接文本与标题层级是否还原。这也解释了为什么技术教程类是抽取质量评测中不可缺少的样本类型。若想亲自复跑可参考 per-category.ts 的文件头注释在开发机上以RUN_EXTRACT_BENCH1 npx tsx benchmarks/extraction/per-category.ts运行分品类对比基准其质量门禁要求 v1 抽取器的聚合 F1 不低于 legacy 流水线、且单品类 F1 回退不超过 3%。结论从identityT这样最简单的泛型函数到RepositoryT、StackT这样的结构化复用再到映射类型与条件类型提供的类型级变换TypeScript 泛型构成了一条完整的能力阶梯。掌握它意味着你可以在编译期锁定数据契约、消灭重复代码并为 API 客户端这类真实业务组件提供端到端的类型推导。而 wigolo 的抽取基准告诉我们好的技术文档本身也应当结构清晰、代码与表格完整因为它既是面向开发者的知识载体也可能是衡量 AI 内容抽取与检索质量的高价值评测样本。【免费下载链接】wigoloThe go-to web for your AI coding agent — local-first search, fetch, crawl research over MCP. No API keys, no cloud, $0/query. Public beta.项目地址: https://gitcode.com/GitHub_Trending/wi/wigolo创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 深入 TypeScript 泛型从基础语法到企业级抽取基准中的类型实践【免费下载链接】wigoloThe go-to web for your AI coding agent — local-first search, fetch, crawl research over MCP. No API keys, no cloud, $0/query. Public beta.项目地址: https://gitcode.com/GitHub_Trending/wi/wigolo导读TypeScript 泛型Generics是构建一次编写、类型复用代码的关键机制。本文以 golden/article-001.md 这份金标准文档的完整内容为骨架系统讲解泛型函数、泛型约束、泛型接口、泛型类、映射类型与条件类型的进阶用法并附上一个可落地的 API Client 综合示例。与此同时本仓库 wigolo 恰好把这份文档作为 HTML→Markdown 抽取评测的金标准样例见 manifest.json因此文末会结合 runner.ts 与 metrics.ts 的源码说明用这类带代码块、表格、链接的技术文章衡量抽取器质量的真实工程场景。读完本文你既能掌握 TypeScript 泛型的完整知识链也能理解技术文档如何被当作结构化评测数据的底层逻辑。为什么需要泛型Why GenericsTypeScript 泛型提供了一种编写可与多种类型协同工作的复用组件的方式是类型系统中最强大的能力之一。如果没有泛型你会被迫在两种糟糕选择间二选一要么使用any彻底放弃类型安全要么为每个类型重复编写几乎相同的函数function identityString(arg: string): string { return arg; } function identityNumber(arg: number): number { return arg; }而使用泛型只需编写一个函数即可同时获得类型安全与代码复用function identityT(arg: T): T { return arg; } const str identitystring(hello); // type: string const num identitynumber(42); // type: numberT在这里是一个类型参数type parameter它把入参类型与返回值类型绑定为同一个类型调用时由 TypeScript 推断或用尖括号显式指定。这正体现了 golden 文档在标题里强调的核心理念用泛型消灭any的同时保持 DRYDont Repeat Yourself。泛型约束Generic Constraints并非所有类型都适合某个泛型函数。用extends关键字可以限制允许传入的类型范围让编译器在类型层面替你拦截非法调用interface Lengthwise { length: number; } function logLengthT extends Lengthwise(arg: T): T { console.log(arg.length); return arg; } logLength(hello); // OK, string has .length logLength([1, 2, 3]); // OK, array has .length // logLength(42); // Error: number has no .length约束的意义在于函数体内可以安全地访问约束所声明的成员这里就是.length超出约束的类型在编译期直接报错而不是在运行时才暴露问题。泛型接口Generic Interfaces泛型可以作用于接口构造出灵活、可复用的数据结构契约。文档给出了一个典型的仓储Repository模式用RepositoryT定义通用的数据访问契约再用具体的User类型实现它interface RepositoryT { getById(id: string): PromiseT; getAll(): PromiseT[]; create(item: T): PromiseT; update(id: string, item: PartialT): PromiseT; delete(id: string): Promisevoid; } interface User { id: string; name: string; email: string; } class UserRepository implements RepositoryUser { private users: Mapstring, User new Map(); async getById(id: string): PromiseUser { const user this.users.get(id); if (!user) throw new Error(User ${id} not found); return user; } async getAll(): PromiseUser[] { return Array.from(this.users.values()); } async create(item: User): PromiseUser { this.users.set(item.id, item); return item; } async update(id: string, item: PartialUser): PromiseUser { const existing await this.getById(id); const updated { ...existing, ...item }; this.users.set(id, updated); return updated; } async delete(id: string): Promisevoid { this.users.delete(id); } }注意两个容易被忽视的类型细节update使用PartialT表示只更新部分字段delete返回Promisevoid表示不关心返回值。泛型接口让UserRepository、OrderRepository等实现共享同一套契约调用方无需关心具体实现类型。泛型类Generic Classes类同样可以使用类型参数构建类型安全的数据结构。文档给出了一个经典的栈实现class StackT { private items: T[] []; push(item: T): void { this.items.push(item); } pop(): T | undefined { return this.items.pop(); } peek(): T | undefined { return this.items[this.items.length - 1]; } get size(): number { return this.items.length; } } const numberStack new Stacknumber(); numberStack.push(1); numberStack.push(2); console.log(numberStack.pop()); // 2实例化时通过new Stacknumber()固定元素类型后push(字符串)会在编译期被拒绝。pop/peek返回T | undefined的处理方式也展示了泛型与联合类型配合时如何诚实地表达可能没有值。映射类型与泛型的组合Mapped Types with Generics泛型与映射类型mapped types结合可以对既有类型的每个属性进行统一变换这是类型层面最常见的元编程手段type ReadonlyT { readonly [P in keyof T]: T[P]; }; type OptionalT { [P in keyof T]?: T[P]; }; type NullableT { [P in keyof T]: T[P] | null; }; interface Config { host: string; port: number; debug: boolean; } type ReadonlyConfig ReadonlyConfig; type OptionalConfig OptionalConfig;keyof T取出T的全部属性名[P in keyof T]遍历这些属性名并为每个属性生成一个新的类型T[P]通过索引访问保留原属性类型。映射类型可叠加使用例如ReadonlyPartialConfig就是所有属性可选且只读的新类型——这正是许多配置对象在初始化完成后想要锁定的形态。条件类型Conditional Types条件类型让泛型具备了类型层面的分支逻辑配合infer关键字还能从复杂类型中提取内部类型type IsStringT T extends string ? yes : no; type A IsStringstring; // yes type B IsStringnumber; // no type ExtractPromiseT T extends Promiseinfer U ? U : T; type C ExtractPromisePromisestring; // string type D ExtractPromisenumber; // numberT extends U ? X : Y的语义是若T可赋值给U则结果类型为X否则为Y。infer U则声明一个待推断的类型变量U由编译器从Promise...内部反推出来。条件类型常用于编写ReturnTypeT、ParametersT这类工具类型或在strict模式下实现精确的窄化。综合实战泛型 API Client文档最后给出了一个把多种泛型模式组合在一起的真实示例——一个通用 API 客户端。ApiResponseT描述统一响应外壳PaginatedResponseT在T[]之上扩展分页字段ApiClient的方法借助泛型在调用点注入业务类型interface ApiResponseT { data: T; status: number; message: string; timestamp: string; } interface PaginatedResponseT extends ApiResponseT[] { total: number; page: number; pageSize: number; hasNext: boolean; } class ApiClient { constructor(private baseUrl: string) {} async getT(path: string): PromiseApiResponseT { const response await fetch(${this.baseUrl}${path}); return response.json(); } async getPaginatedT( path: string, page: number 1, pageSize: number 20, ): PromisePaginatedResponseT { const response await fetch( ${this.baseUrl}${path}?page${page}pageSize${pageSize}, ); return response.json(); } } const client new ApiClient(https://api.example.com); const users await client.getPaginatedUser(/users, 1, 10); console.log(users.data); // User[] console.log(users.hasNext); // booleangetPaginatedUser调用一次users.data即为User[]、users.hasNext即为boolean全程无需任何类型断言。这是泛型让调用点获得完整类型信息的典型收益。快速回顾表FeatureSyntaxUse CaseGeneric Functionfunction fnT(arg: T): TReusable functionsGeneric Interfaceinterface RepoTFlexible contractsGeneric Classclass StackTType-safe data structuresConstraintsT extends BaseRestrict allowed typesConditionalT extends U ? X : YType-level branchingMapped{ [P in keyof T]: ... }Transform existing types延伸泛型技术文章如何成为 wigolo 抽取基准泛型是编写类型安全、可复用 TypeScript 代码的基石它消除了对any的依赖同时保持代码 DRY。而在本仓库中这篇泛型教程还有另一重身份它是一份金标准golden数据。在 manifest.json 中article-001条目声明了category: article、expectedExtractor: defuddle其 HTML 源稿与 Markdown 金标准分别存放在 fixtures 目录下用于检验 HTML→Markdown 抽取器的还原质量。评测链路在 runner.ts 中每个条目读取 HTML fixture 后调用抽取流水线将得到的markdown与 golden 文档交给 metrics.ts 计算指标。度量方法值得留意——tokenizer.ts 先做normalizeText剥掉标题标记、列表标记、代码围栏、链接与图片语法再按字母数字边界切分成 token随后在 metrics.ts 中计算 token 级别的 Precision / Recall / F1并用最长公共子序列LCS计算 ROUGE-L还校验抽取结果的标题数与链接数是否与 golden 完全一致。正因为 golden 文章里同时含有内联代码、代码围栏、表格、链接和分级标题它天然覆盖了抽取器最容易失真的结构代码块是否完整保留、表格管道符是否被正确转换、链接文本与标题层级是否还原。这也解释了为什么技术教程类是抽取质量评测中不可缺少的样本类型。若想亲自复跑可参考 per-category.ts 的文件头注释在开发机上以RUN_EXTRACT_BENCH1 npx tsx benchmarks/extraction/per-category.ts运行分品类对比基准其质量门禁要求 v1 抽取器的聚合 F1 不低于 legacy 流水线、且单品类 F1 回退不超过 3%。结论从identityT这样最简单的泛型函数到RepositoryT、StackT这样的结构化复用再到映射类型与条件类型提供的类型级变换TypeScript 泛型构成了一条完整的能力阶梯。掌握它意味着你可以在编译期锁定数据契约、消灭重复代码并为 API 客户端这类真实业务组件提供端到端的类型推导。而 wigolo 的抽取基准告诉我们好的技术文档本身也应当结构清晰、代码与表格完整因为它既是面向开发者的知识载体也可能是衡量 AI 内容抽取与检索质量的高价值评测样本。【免费下载链接】wigoloThe go-to web for your AI coding agent — local-first search, fetch, crawl research over MCP. No API keys, no cloud, $0/query. Public beta.项目地址: https://gitcode.com/GitHub_Trending/wi/wigolo创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考