企业官网建设流程全解析

深入 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 Generics）

TypeScript 泛型提供了一种编写"可与多种类型协同工作"的复用组件的方式，是类型系统中最强大的能力之一。如果没有泛型，你会被迫在两种糟糕选择间二选一：要么使用any彻底放弃类型安全，要么为每个类型重复编写几乎相同的函数：

function identityString(arg: string): string { return arg; } function identityNumber(arg: number): number { return arg; }

而使用泛型，只需编写一个函数，即可同时获得类型安全与代码复用：

function identity<T>(arg: T): T { return arg; } const str = identity<string>("hello"); // type: string const num = identity<number>(42); // type: number

T在这里是一个类型参数（type parameter），它把"入参类型"与"返回值类型"绑定为同一个类型，调用时由 TypeScript 推断或用尖括号显式指定。这正体现了 golden 文档在标题里强调的核心理念：用泛型消灭any的同时保持 DRY（Don't Repeat Yourself）。

泛型约束（Generic Constraints）

并非所有类型都适合某个泛型函数。用extends关键字可以限制允许传入的类型范围，让编译器在类型层面替你拦截非法调用：

interface Lengthwise { length: number; } function logLength<T 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）模式，用Repository<T>定义通用的数据访问契约，再用具体的User类型实现它：

interface Repository<T> { getById(id: string): Promise<T>; getAll(): Promise<T[]>; create(item: T): Promise<T>; update(id: string, item: Partial<T>): Promise<T>; delete(id: string): Promise<void>; } interface User { id: string; name: string; email: string; } class UserRepository implements Repository<User> { private users: Map<string, User> = new Map(); async getById(id: string): Promise<User> { const user = this.users.get(id); if (!user) throw new Error(`User ${id} not found`); return user; } async getAll(): Promise<User[]> { return Array.from(this.users.values()); } async create(item: User): Promise<User> { this.users.set(item.id, item); return item; } async update(id: string, item: Partial<User>): Promise<User> { const existing = await this.getById(id); const updated = { ...existing, ...item }; this.users.set(id, updated); return updated; } async delete(id: string): Promise<void> { this.users.delete(id); } }

注意两个容易被忽视的类型细节：update使用Partial<T>表示"只更新部分字段"；delete返回Promise<void>表示"不关心返回值"。泛型接口让UserRepository、OrderRepository等实现共享同一套契约，调用方无需关心具体实现类型。

泛型类（Generic Classes）

类同样可以使用类型参数，构建类型安全的数据结构。文档给出了一个经典的栈实现：

class Stack<T> { 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 Stack<number>(); numberStack.push(1); numberStack.push(2); console.log(numberStack.pop()); // 2

实例化时通过new Stack<number>()固定元素类型后，push(字符串)会在编译期被拒绝。pop/peek返回T | undefined的处理方式，也展示了泛型与联合类型配合时如何诚实地表达"可能没有值"。

映射类型与泛型的组合（Mapped Types with Generics）

泛型与映射类型（mapped types）结合，可以对既有类型的每个属性进行统一变换，这是类型层面最常见的"元编程"手段：

type Readonly<T> = { readonly [P in keyof T]: T[P]; }; type Optional<T> = { [P in keyof T]?: T[P]; }; type Nullable<T> = { [P in keyof T]: T[P] | null; }; interface Config { host: string; port: number; debug: boolean; } type ReadonlyConfig = Readonly<Config>; type OptionalConfig = Optional<Config>;

keyof T取出T的全部属性名，[P in keyof T]遍历这些属性名并为每个属性生成一个新的类型，T[P]通过索引访问保留原属性类型。映射类型可叠加使用，例如Readonly<Partial<Config>>就是"所有属性可选且只读"的新类型——这正是许多配置对象在初始化完成后想要锁定的形态。

条件类型（Conditional Types）

条件类型让泛型具备了"类型层面的分支逻辑"，配合infer关键字还能从复杂类型中"提取"内部类型：

type IsString<T> = T extends string ? "yes" : "no"; type A = IsString<string>; // "yes" type B = IsString<number>; // "no" type ExtractPromise<T> = T extends Promise<infer U> ? U : T; type C = ExtractPromise<Promise<string>>; // string type D = ExtractPromise<number>; // number

T extends U ? X : Y的语义是：若T可赋值给U，则结果类型为X，否则为Y。infer U则声明一个待推断的类型变量U，由编译器从Promise<...>内部反推出来。条件类型常用于编写ReturnType<T>、Parameters<T>这类工具类型，或在strict模式下实现精确的窄化。

综合实战：泛型 API Client

文档最后给出了一个把多种泛型模式组合在一起的真实示例——一个通用 API 客户端。ApiResponse<T>描述统一响应外壳，PaginatedResponse<T>在T[]之上扩展分页字段，ApiClient的方法借助泛型在调用点注入业务类型：

interface ApiResponse<T> { data: T; status: number; message: string; timestamp: string; } interface PaginatedResponse<T> extends ApiResponse<T[]> { total: number; page: number; pageSize: number; hasNext: boolean; } class ApiClient { constructor(private baseUrl: string) {} async get<T>(path: string): Promise<ApiResponse<T>> { const response = await fetch(`${this.baseUrl}${path}`); return response.json(); } async getPaginated<T>( path: string, page: number = 1, pageSize: number = 20, ): Promise<PaginatedResponse<T>> { 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.getPaginated<User>("/users", 1, 10); console.log(users.data); // User[] console.log(users.hasNext); // boolean

getPaginated<User>调用一次，users.data即为User[]、users.hasNext即为boolean，全程无需任何类型断言。这是"泛型让调用点获得完整类型信息"的典型收益。

快速回顾表

延伸：泛型技术文章如何成为 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_BENCH=1 npx tsx benchmarks/extraction/per-category.ts运行分品类对比基准，其质量门禁要求 v1 抽取器的聚合 F1 不低于 legacy 流水线、且单品类 F1 回退不超过 3%。

结论

从identity<T>这样最简单的泛型函数，到Repository<T>、Stack<T>这样的结构化复用，再到映射类型与条件类型提供的类型级变换，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