TypeSpec 类型信息提供器（$provideTypeInfo）实战：为 IDE 悬停与工具链贡献领域专属类型信息

TypeSpec 类型信息提供器（$provideTypeInfo）实战：为 IDE 悬停与工具链贡献领域专属类型信息

【免费下载链接】typespec项目地址: https://gitcode.com/GitHub_Trending/ty/typespec

导读

TypeSpec 语言本身只描述类型结构，而领域语义（如某个op的 HTTP 路由、响应状态码）通常由@typespec/http等库在编译期另行推导。为了让这些"语言之外的领域信息"也能被 IDE 悬停提示和 AI Agent 等工具查询到，TypeSpec 编译器提供了一套实验性的type-info-provider特性：库可以通过导出$provideTypeInfo函数，按需为任意类型贡献一段 Markdown 内容。阅读完本文，你将掌握如何在自己的 TypeSpec 库中注册该提供器、如何正确发布包含tspconfig.yaml的包，以及如何通过program.getTypeInfo在工具侧统一查询所有库贡献的信息。

本文对应仓库文档为 providing-type-info.md，源码证据分布在 compiler 核心类型定义、library.ts、program.ts 以及 @typespec/http 的真实实现 中。

为什么需要"类型信息提供器"

TypeSpec 的核心语言只提供类型、操作、命名空间等语法设施。当用户编写一个op时，编译器并不知道它对应的 HTTP 方法、路径模板或响应状态码——这些语义由@typespec/http这样的库通过装饰器与编译期推导得出，属于"领域专属信息"，天然不包含在核心语言的类型体系里。

过去，这些信息只存在于编译产物（如 OpenAPI 文档）中，开发者在 IDE 里悬停一个操作时无法直接看到。type-info-provider特性正是为了解决这个缺口：它允许库为类型贡献额外的、领域化的信息，这些信息会：

• 显示在 IDE 悬停（hover）提示中，附加在类型签名与文档注释之后；
• 通过program.getTypeInfo被工具（包括 AI Agent）编程式查询。

在 @typespec/http 的官方实现 中，一个 Operation 会贡献出HTTP Route（方法 + URI 模板）以及Responses（状态码列表），这就是"额外信息"的典型例子。

实验性特性与库侧开启方式

该特性目前处于实验阶段，且开启（opt-in）粒度是"声明提供器的库自身"：库作者必须在自己库的tspconfig.yaml中启用type-info-provider编译器特性，而使用该库的消费者无需任何额外配置即可看到贡献的信息。

在库的tspconfig.yaml中加入：

kind: project features: - type-info-provider

该特性名称与说明在 compiler 的 features.ts 中登记，官方描述为：启用实验性的$provideTypeInfo提供器，允许库为类型贡献额外信息，供 IDE 悬停与工具（通过program.getTypeInfo查询）使用。同文件还列出了其他实验特性（如function-declarations、auto-decorators），说明features是编译器统一的实验开关机制。

发布时必须带上 tspconfig.yaml

由于 opt-in 标记是从已发布的包中读取的，务必确认tspconfig.yaml真的被打包发布，否则库从 registry 安装后提供器会被静默忽略。需要在库的package.json的files字段中显式包含它：

{ "files": ["lib/**/*.tsp", "tspconfig.yaml", "dist/**"] }

如果tspconfig.yaml缺失或未列入files，编译不会报错，但$provideTypeInfo不会被注册——这种"静默失效"是发布阶段最容易踩的坑。

核心 API：$provideTypeInfo与defineTypeInfoProvider

库从主入口文件导出一个$provideTypeInfo函数即可注册提供器。推荐使用defineTypeInfoProvider辅助函数来获得完整的类型标注（它本身只是一个恒等函数，仅提供类型帮助，见 library.ts）。

提供器接收一个TypeInfoContext，包含：

• program：当前的Program实例，用于读取编译期状态；
• target：当前被查询的类型（Type）。

返回一个TypeInfo对象（目前只有一个content字段：要展示的 Markdown 内容），当该提供器对该类型没有可贡献的内容时返回undefined。

官方文档示例：

import { defineTypeInfoProvider } from "@typespec/compiler"; import { getHttpOperation } from "./operations.js"; export const $provideTypeInfo = defineTypeInfoProvider(({ program, target }) => { if (target.kind !== "Operation") { return undefined; } const [operation] = getHttpOperation(program, target); if (!operation) { return undefined; } return { content: `\`HTTP Route\`: \`${operation.verb.toUpperCase()} ${operation.uriTemplate}\``, }; });

对应的类型定义见 types.ts：TypeInfo接口只有只读的content: string字段；TypeInfoContext由program与target组成；TypeInfoProvider是(context) => TypeInfo | undefined的函数类型。

官方实现参考：@typespec/http

@typespec/http是仓库内最直接的实现范例（packages/http/src/type-info.ts），其逻辑比文档示例更进一步：

export const $provideTypeInfo = defineTypeInfoProvider(({ program, target }) => { if (target.kind !== "Operation") { return undefined; } const [operation] = getHttpOperation(program, target); if (!operation) { return undefined; } const lines = [`\`HTTP Route\`: \`${operation.verb.toUpperCase()} ${operation.uriTemplate}\``]; const statusCodes = operation.responses.map((response) => formatStatusCode(response.statusCodes)); if (statusCodes.length > 0) { lines.push(`\`Responses\`: ${statusCodes.map((code) => `\`${code}\``).join(", ")}`); } return { content: lines.join("\n\n") }; });

值得注意的实现细节：

• 它通过target.kind !== "Operation"快速短路，对非 Operation 类型直接返回undefined；
• 使用getHttpOperation(program, target)解析出操作的路由与响应，若解析失败同样返回undefined；
• formatStatusCode统一了三种状态码形态：数字（204）、通配符（*）、区间（200-299，输出为start-end形式）；
• 多行内容用\n\n连接，与program.getTypeInfo中的合并策略一致。

IDE 中的展示方式

在 IDE 中，提供器贡献的内容被追加在类型签名与文档注释之后，并用一条水平分隔线与类型自身的 doc 注释区分开：

op read(id: string): void Reads a pet. --- `HTTP Route`: `GET /pets/{id}` `Responses`: `204`

即：第一段是类型签名与文档，---之后是来自$provideTypeInfo的领域信息。这种布局让悬停提示既保留原有文档，又能清晰呈现库补充的语义（如 HTTP 路由）。

重要约束：懒执行、只读、无顺序竞争

文档特别强调了$provideTypeInfo与$onValidate（该文档位于 website/src/content/docs/docs/extending-typespec/diagnostics.md）生命周期钩子的关键区别：

1. 编译期绝不执行。提供器是懒加载、按需调用的（例如语言服务器计算悬停文档时、工具查询时），不会拖慢正常编译流程。
2. 不得修改类型图。提供器只能读取 program 并回答关于它的问题，任何变更类型图的行为都是禁止的。

正是因为不改变类型图，库之间不存在执行顺序或竞态问题——每个库贡献的content只是被简单地拼接（concatenate）在一起。

编程式查询：program.getTypeInfo

工具侧可以通过program.getTypeInfo(target)查询某个类型上所有已注册提供器的贡献结果，返回值是合并后的单个TypeInfo；当没有任何提供器贡献内容时返回undefined：

const info = program.getTypeInfo(type); // { content: "`HTTP Route`: `GET /pets/{id}`\n\n`Responses`: `204`" }

源码级的合并与容错机制

getTypeInfo的实现在 program.ts，其中包含几个文档未展开的关键细节：

getTypeInfo(target) { if (typeInfoProviders.length === 0) { return undefined; } const contents: string[] = []; const context: TypeInfoContext = { program, target }; for (const provider of typeInfoProviders) { let result: TypeInfo | undefined; try { result = provider.callback(context); } catch (error: any) { // 懒执行发生在编译结束后很久，崩溃的提供器不得污染 program 的诊断 if (options.designTimeBuild) { trace( "info-provider.crash", `Library "${provider.metadata.name ?? "<unnamed>"}" $provideTypeInfo crashed: ${error.stack}`, ); continue; } else { throw new ExternalError({ kind: "info", metadata: provider.metadata, error }); } } if (result) { contents.push(result.content); } } return contents.length > 0 ? { content: contents.join("\n\n") } : undefined; }

从该实现可以确认三点行为：

• 异常隔离：在设计时构建（designTimeBuild，即语言服务器场景）中，某个库的提供器抛异常会被 trace 到info-provider.crash并跳过，不会让悬停或补全功能整体挂掉；非设计时构建中则抛出ExternalError。这正是"懒执行、晚于编译"这一约束在工程上的体现——此时再往program里塞诊断已经没有意义。
• 贡献合并：多个库的content以\n\n连接（与@typespec/http内部多行拼接方式一致），最终合并为单个TypeInfo。
• 空结果语义：无提供器或无内容时返回undefined，调用方需要处理这一情况。

完整落地清单

要在自己的 TypeSpec 库中启用并提供类型信息，按以下步骤操作：

1. 在库的tspconfig.yaml中开启特性：

   kind: project features: - type-info-provider

2. 在库主入口导出$provideTypeInfo，用defineTypeInfoProvider包裹，对无关类型返回undefined，必要时借助getHttpOperation等编译期 API 解析领域语义（参考 @typespec/http 实现）。
3. 确认发布配置：在package.json的files中包含tspconfig.yaml，避免从 registry 安装后被静默忽略。
4. 验证：在 IDE 中悬停目标类型查看追加内容，或通过program.getTypeInfo(type)编程式断言输出（可参考 compiler 的 types.ts 中TypeInfo/TypeInfoContext的接口形态编写类型安全的测试）。

小结

type-info-provider为 TypeSpec 的库生态打开了一条"领域语义 → IDE/工具"的低成本通道：库作者只需导出一个纯函数式、只读的提供器，即可把 HTTP 路由、状态码等编译期推导结果注入悬停提示，供开发者与 AI Agent 查询。其设计约束（懒执行、不可变、无竞争）使它天然适合叠加多个库的贡献；而program.getTypeInfo的异常隔离与内容合并机制，则保证了即便某个库的实现存在缺陷，也不会拖垮整个设计时体验。

【免费下载链接】typespec项目地址: https://gitcode.com/GitHub_Trending/ty/typespec