TypeSpec 0.61 版本深度解析嵌套 Emitter 选项、流式响应模型与编译器 API 演进【免费下载链接】typespec项目地址: https://gitcode.com/GitHub_Trending/ty/typespec本篇基于官方发布说明 typespec-0-61.md2024 年 10 月发布系统梳理 TypeSpec 0.61 的破坏性变更、新特性与 Bug 修复清单并结合当前仓库源码深入剖析嵌套 Emitter 选项、Nodeexports字段、实验性 Type Mutators、HttpStream/JsonlStream流式响应等关键能力。读完本篇你将明确升级 0.61 时需处理的兼容性动作掌握新版配置写法与实验 API 的使用边界并能依据源码定位问题根因。版本概览与升级提示TypeSpec 0.61 于 2024-10-09 发布官方发布说明在版本起始处即标注了:::caution警示This release contains breaking changes这意味着 0.61 并非纯粹的增量版本升级前需要评估以下三类破坏性变更配置参数与 Emitter 选项的键名规则收紧不再允许包含.编译器 APIdecoratorArgMarshalling的默认行为切换编译器对入口点entrypoint路径形态的要求变为绝对路径。下文将逐项给出影响范围、报错表现与迁移方式。破坏性变更详解1. 配置参数与 Emitter 选项不能包含.变更内容从 0.61 起tspconfig.yaml中的配置参数与 Emitter 选项的键名key不允许再出现点号.。该限制与 0.61 同期新增的嵌套选项nested options支持直接相关——点号原本被用作扁平键的隐式分隔符现在必须显式通过嵌套结构表达层级对应 PR #4539。背景依据在编译器配置类型中Emitter 选项被定义为递归的键值结构见 packages/compiler/src/config/types.tsexport type EmitterOptions Recordstring, unknown { // 允许任意嵌套的对象值 }; // 每个 emitter 对应一份选项 options?: Recordstring, EmitterOptions;当选项支持任意嵌套对象后如果继续允许键名中出现.解析器将无法区分字面点号键与嵌套路径分隔符因此 0.61 选择直接禁止.。迁移时将原先写成emitter-name: { foo.bar: true }的配置改为嵌套对象emit: - typespec/openapi3 options: typespec/openapi3: foo: bar: true # 原先是 foo.bar: true2.decoratorArgMarshalling默认值从legacy切换为new变更内容编译器 API 中装饰器参数封送marshalling的默认模式由legacy改为new对应 PR #4500。legacy是历史遗留的参数传递方式new模式对装饰器参数的 JS 值处理更统一、更符合类型系统语义。该默认值通过包级标志package flags控制。回退方式官方明确给出了回退代码但强烈不推荐且该回退机制将在未来几个版本中被移除export const $flags definePackageFlags({ decoratorArgMarshalling: legacy, });实现位置definePackageFlags定义于 packages/compiler/src/core/library.ts其作用是接收一个PackageFlags对象并原样返回为库作者提供类型提示实际的标志读取与行为切换发生在编译器内部对装饰器参数的封送处理路径中。如果你的自定义库依赖legacy模式下装饰器参数以原始 AST 值传入的行为请尽快迁移到new模式并显式适配参数类型。3. 编译器要求入口点为绝对路径变更内容TypeSpec 编译器现在要求传给编译流程的入口文件entrypoint必须是绝对路径。此前某些自定义CompilerHost实现允许相对路径并自行解析但由于 0.61 新增了对 Nodeexports字段的支持见下文特性部分模块解析链路被重构相对入口不再受支持。影响范围使用默认NodeHost的命令行与 LSP 场景不受影响工具内部本就解析为绝对路径受影响的主要是自行实现CompilerHost、直接调用编译器 API 的嵌入方。迁移方式为在调用入口处使用path.resolve()或import.meta.url转绝对路径后再传入。核心新特性嵌套 Emitter 选项Nested Emitter Options0.61 正式支持 Emitter 选项的嵌套结构PR #4539。这是与上述破坏性变更 #1 配套的能力选项值不再局限于扁平的字符串/布尔/数字而可以包含任意层级的对象供 emitter 内部按命名空间组织配置。配置示例options: typespec/openapi3: emitter-output-dir: {project-root}/output emit-types: models: true operations: include: [list*]Emitter 端通过getEmitterOptions(program, emitterName)取回的选项即为此嵌套对象。编写自定义 emitter 时注意选项的 JSON Schema 校验同样遵循嵌套结构参见 library.ts 中createJSONSchemaValidator对lib.emitter.options的校验逻辑。支持 Nodeexports字段与typespec导出0.61 为库包引入对 Node.jsexports字段的支持PR #4606允许库作者精确声明哪些子路径可被 TypeSpec 导入。在标准的 Nodeexports映射基础上新增了typespec子字段用于指定该导出对应的.tsp源文件{ exports: { .: { typespec: ./lib/main.tsp }, ./named: { typespec: ./lib/named.tsp } } }解析规则当 TypeSpec 编译器解析import mylib/named时会优先读取exports[./named].typespec指向的.tsp文件而不是 JS 入口。这一机制解决了此前package.json中types/main字段无法同时服务 JS 与 TypeSpec 两套解析体系的问题也是上文入口点必须为绝对路径变更的直接动因——exports解析天然产出绝对路径。配套变更新增更精确的PackageJson类型PR #4595并弃用NodePackage。库作者应把类型标注从NodePackage迁移到PackageJson以获得与exports字段一致的完整类型提示。实验性 APIType Mutators0.61 引入实验性的Type MutatorsAPIPR #4290用于在类型图上声明式地克隆并改造类型适合 emitter 在输出前对类型做投影式转换。实现位于 packages/compiler/src/experimental/mutators.ts核心概念如下Mutator一个具名对象按类型kindModel、ModelProperty、Union、Scalar、Operation等注册对应的变更描述MutatorRecord三种形态之一——纯函数等价于mutate 无filter、{ mutate }就地修改克隆体、{ replace }用新实例替换克隆体均可选配filter谓词MutatorFlow控制流filter返回布尔值或标志位MutateAndRecur默认变更并递归子图、DoNotMutate跳过变更、DoNotRecur不递归子节点入口函数mutateSubgraph(program, mutators, type)与mutateSubgraphWithNamespace(program, mutators, namespace)返回{ realm, type }其中Realm是克隆体所在的新域experimental/realm.ts 一并导出。从源码看Mutator 引擎的关键设计约束值得注意只改克隆不改源类型——源码注释明确警告修改源类型会影响其他 emitter/库的观察结果且结果对应用顺序敏感编译器内置类型默认跳过——getLocationContext(program, type).type compiler且非模板实例的类型不会进入突变流程避免破坏类型检查器除非通过内部setAlwaysMutate强制去重与终止——seen缓存按Program维度WeakMapProgram, SeenCache记忆已克隆的类型与 mutator 组合保证循环/共享类型图只克隆一次同时避免模块级缓存导致类型图被长期钉在内存中。该 API 仍标记experimental接口可能随版本演进生产 emitter 使用前请关注后续版本变更说明。库诊断支持description与url0.61 允许库在定义诊断diagnostic时附带description和urlPR #4442分别用于给出更详细的问题说明与指向在线文档的链接。createTypeSpecLibrary的定义入口library.ts会透传这些字段IDE 悬浮提示与 CLI 输出可据此展示更友好的错误上下文const libDef { name: myLib, diagnostics: { my-code: { severity: error, messages: { default: Foo bar }, description: 详细说明..., url: https://example.com/docs/my-code, }, }, } as const;typespec/http新增HttpStream与JsonlStream流式模型0.61 为 HTTP 库引入流式响应的官方模型PR #4513定义位于 packages/http/lib/streams/main.tspimport typespec/streams; import ../main.tsp; using TypeSpec.Streams; namespace TypeSpec.Http.Streams; /** * 描述一个流协议类型数据由 Type 描述 * ContentType 与 BodyType 描述线上的编码方式。 */ doc() model HttpStream Type, ContentType extends valueof string, BodyType extends bytes | string string is StreamType { header contentType: typeof ContentType; body body: BodyType; } /** * 每行一个 JSON 对象、Content-Type 为 application/jsonl 的流。 */ doc() model JsonlStreamType is HttpStreamType, application/jsonl;用法示例来自该文件的 doc 注释model Message { id: string; text: string; } TypeSpec.Events.events union Events { Message, } op subscribe(): JsonlStreamEvents;要点HttpStream继承自typespec/streams库的StreamType抽象携带contentType头与body字段JsonlStreamType是HttpStreamType, application/jsonl的便捷别名Content-Type 固定为application/jsonl相关的 TS 实现与元数据提取逻辑位于 packages/http/src/experimental/streams.ts并有配套测试 streams.test.ts 与 get-stream-metadata.test.ts 验证元数据获取与模型解析行为。typespec/openapi3支持 Scalar 与 Object 作为默认类型0.61 允许default等场景下将Scalar与Object值用作默认类型PR #4423此前仅支持部分字面量形式。这使 OpenAPI 3 输出中默认值可以直接引用模型对象或标量实例减少了手写等价 JSON 的需要。typespec/json-schemaexample填充examples属性0.61 起example装饰器设置的示例值会写入 JSON Schema 输出的examples属性PR #4447model Pet { name: string; } example({ name: Fluffy }) model Example {}对应生成 JSON Schema 的examples: [{ name: Fluffy }]便于下游工具与文档系统直接消费示例数据。typespec-vscode编译任务、监视任务与 Web 兼容0.61 的 VS Code 扩展新增两类能力PR #4330Compile Task在编辑器中直接触发 TypeSpec 编译Watch Task启动tsp compile --watch监视模式保存即重编译。同时扩展实现了最小化的 Web 兼容PR #4498使依赖纯 Web 环境如 VSCode for Web的基础功能可用由于部分功能依赖 Node 运行时Web 模式下仅启用最小功能子集。Bug 修复清单0.61 的修复集中于编译器语义、示例序列化、LSP 缓存与平台兼容四类以下按库分组说明PR 编号见发布说明原文typespec/compiler语义遍历器修复exitTuple回调未被触发的问题——遍历 Tuple 节点时缺少对应的 exit 钩子PR #4513示例生成修复枚举嵌套在 union 中时example生成的示例不正确PR #4462修复向example传入模型类型的const值时的处理问题PR #4574示例的 JSON 序列化现在遵循encodedName即按编码后的属性名输出PR #4551数值解析修复 decimal 数值带多位前导0.0如0.00x时的解析错误PR #4514API 行为sourceModels属性在投影projection后能正确保持PR #4445补齐缺失的 exit 回调PR #4626使语义遍历的 enter/exit 配对完整配置与缓存修复 LSP 服务器中修改tspconfig.yaml后因缓存不生效的问题PR #4467tsp compile --watch现在会重新读取tspconfig.yaml的变更PR #4563。typespec/openapiinfo装饰器新增校验不允许提供不以x-开头的多余属性PR #4505保证 Info 对象符合 OpenAPI 规范info的termsOfService字段会校验为合法 URLPR #4483。typespec/internal-build-utils第三方声明third-party notice生成时忽略测试文件避免把测试依赖混入制品声明PR #4498。typespec-vscodeWindows 平台下执行.cmd文件如tsp-server.cmd时改用shell方式派生进程解决旧式spawn在部分 Windows 环境无法解析.cmd的问题PR #4430。升级路径与兼容性建议综合发布说明与源码0.61 升级清单可归纳为三步配置体检全局检索tspconfig.yaml与 emitter 选项中的键名凡含.的键改为嵌套对象写法避免编译器报错库作者适配若自定义库依赖旧装饰器参数封送行为临时导出definePackageFlags({ decoratorArgMarshalling: legacy })并尽快迁移该回退即将移除将NodePackage类型引用替换为PackageJson如需对外暴露.tsp子路径在package.json的exports中补typespec字段嵌入编译器 API 的场景确保传入的入口为绝对路径。尝鲜新能力流式接口HttpStream/JsonlStream、OpenAPI3 默认类型与 JSON Schemaexamples输出可直接用于新服务定义Type Mutators 属实验 API建议先在小范围验证再进入生产 emitter。本文所涉源码位置汇总编译器库定义、Type Mutators 实现、配置选项类型、HTTP 流式模型 及其 实现 与 测试可供深入研读。【免费下载链接】typespec项目地址: https://gitcode.com/GitHub_Trending/ty/typespec创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 TypeSpec 0.61 版本深度解析：嵌套 Emitter 选项、流式响应模型与编译器 API 演进
TypeSpec 0.61 版本深度解析嵌套 Emitter 选项、流式响应模型与编译器 API 演进【免费下载链接】typespec项目地址: https://gitcode.com/GitHub_Trending/ty/typespec本篇基于官方发布说明 typespec-0-61.md2024 年 10 月发布系统梳理 TypeSpec 0.61 的破坏性变更、新特性与 Bug 修复清单并结合当前仓库源码深入剖析嵌套 Emitter 选项、Nodeexports字段、实验性 Type Mutators、HttpStream/JsonlStream流式响应等关键能力。读完本篇你将明确升级 0.61 时需处理的兼容性动作掌握新版配置写法与实验 API 的使用边界并能依据源码定位问题根因。版本概览与升级提示TypeSpec 0.61 于 2024-10-09 发布官方发布说明在版本起始处即标注了:::caution警示This release contains breaking changes这意味着 0.61 并非纯粹的增量版本升级前需要评估以下三类破坏性变更配置参数与 Emitter 选项的键名规则收紧不再允许包含.编译器 APIdecoratorArgMarshalling的默认行为切换编译器对入口点entrypoint路径形态的要求变为绝对路径。下文将逐项给出影响范围、报错表现与迁移方式。破坏性变更详解1. 配置参数与 Emitter 选项不能包含.变更内容从 0.61 起tspconfig.yaml中的配置参数与 Emitter 选项的键名key不允许再出现点号.。该限制与 0.61 同期新增的嵌套选项nested options支持直接相关——点号原本被用作扁平键的隐式分隔符现在必须显式通过嵌套结构表达层级对应 PR #4539。背景依据在编译器配置类型中Emitter 选项被定义为递归的键值结构见 packages/compiler/src/config/types.tsexport type EmitterOptions Recordstring, unknown { // 允许任意嵌套的对象值 }; // 每个 emitter 对应一份选项 options?: Recordstring, EmitterOptions;当选项支持任意嵌套对象后如果继续允许键名中出现.解析器将无法区分字面点号键与嵌套路径分隔符因此 0.61 选择直接禁止.。迁移时将原先写成emitter-name: { foo.bar: true }的配置改为嵌套对象emit: - typespec/openapi3 options: typespec/openapi3: foo: bar: true # 原先是 foo.bar: true2.decoratorArgMarshalling默认值从legacy切换为new变更内容编译器 API 中装饰器参数封送marshalling的默认模式由legacy改为new对应 PR #4500。legacy是历史遗留的参数传递方式new模式对装饰器参数的 JS 值处理更统一、更符合类型系统语义。该默认值通过包级标志package flags控制。回退方式官方明确给出了回退代码但强烈不推荐且该回退机制将在未来几个版本中被移除export const $flags definePackageFlags({ decoratorArgMarshalling: legacy, });实现位置definePackageFlags定义于 packages/compiler/src/core/library.ts其作用是接收一个PackageFlags对象并原样返回为库作者提供类型提示实际的标志读取与行为切换发生在编译器内部对装饰器参数的封送处理路径中。如果你的自定义库依赖legacy模式下装饰器参数以原始 AST 值传入的行为请尽快迁移到new模式并显式适配参数类型。3. 编译器要求入口点为绝对路径变更内容TypeSpec 编译器现在要求传给编译流程的入口文件entrypoint必须是绝对路径。此前某些自定义CompilerHost实现允许相对路径并自行解析但由于 0.61 新增了对 Nodeexports字段的支持见下文特性部分模块解析链路被重构相对入口不再受支持。影响范围使用默认NodeHost的命令行与 LSP 场景不受影响工具内部本就解析为绝对路径受影响的主要是自行实现CompilerHost、直接调用编译器 API 的嵌入方。迁移方式为在调用入口处使用path.resolve()或import.meta.url转绝对路径后再传入。核心新特性嵌套 Emitter 选项Nested Emitter Options0.61 正式支持 Emitter 选项的嵌套结构PR #4539。这是与上述破坏性变更 #1 配套的能力选项值不再局限于扁平的字符串/布尔/数字而可以包含任意层级的对象供 emitter 内部按命名空间组织配置。配置示例options: typespec/openapi3: emitter-output-dir: {project-root}/output emit-types: models: true operations: include: [list*]Emitter 端通过getEmitterOptions(program, emitterName)取回的选项即为此嵌套对象。编写自定义 emitter 时注意选项的 JSON Schema 校验同样遵循嵌套结构参见 library.ts 中createJSONSchemaValidator对lib.emitter.options的校验逻辑。支持 Nodeexports字段与typespec导出0.61 为库包引入对 Node.jsexports字段的支持PR #4606允许库作者精确声明哪些子路径可被 TypeSpec 导入。在标准的 Nodeexports映射基础上新增了typespec子字段用于指定该导出对应的.tsp源文件{ exports: { .: { typespec: ./lib/main.tsp }, ./named: { typespec: ./lib/named.tsp } } }解析规则当 TypeSpec 编译器解析import mylib/named时会优先读取exports[./named].typespec指向的.tsp文件而不是 JS 入口。这一机制解决了此前package.json中types/main字段无法同时服务 JS 与 TypeSpec 两套解析体系的问题也是上文入口点必须为绝对路径变更的直接动因——exports解析天然产出绝对路径。配套变更新增更精确的PackageJson类型PR #4595并弃用NodePackage。库作者应把类型标注从NodePackage迁移到PackageJson以获得与exports字段一致的完整类型提示。实验性 APIType Mutators0.61 引入实验性的Type MutatorsAPIPR #4290用于在类型图上声明式地克隆并改造类型适合 emitter 在输出前对类型做投影式转换。实现位于 packages/compiler/src/experimental/mutators.ts核心概念如下Mutator一个具名对象按类型kindModel、ModelProperty、Union、Scalar、Operation等注册对应的变更描述MutatorRecord三种形态之一——纯函数等价于mutate 无filter、{ mutate }就地修改克隆体、{ replace }用新实例替换克隆体均可选配filter谓词MutatorFlow控制流filter返回布尔值或标志位MutateAndRecur默认变更并递归子图、DoNotMutate跳过变更、DoNotRecur不递归子节点入口函数mutateSubgraph(program, mutators, type)与mutateSubgraphWithNamespace(program, mutators, namespace)返回{ realm, type }其中Realm是克隆体所在的新域experimental/realm.ts 一并导出。从源码看Mutator 引擎的关键设计约束值得注意只改克隆不改源类型——源码注释明确警告修改源类型会影响其他 emitter/库的观察结果且结果对应用顺序敏感编译器内置类型默认跳过——getLocationContext(program, type).type compiler且非模板实例的类型不会进入突变流程避免破坏类型检查器除非通过内部setAlwaysMutate强制去重与终止——seen缓存按Program维度WeakMapProgram, SeenCache记忆已克隆的类型与 mutator 组合保证循环/共享类型图只克隆一次同时避免模块级缓存导致类型图被长期钉在内存中。该 API 仍标记experimental接口可能随版本演进生产 emitter 使用前请关注后续版本变更说明。库诊断支持description与url0.61 允许库在定义诊断diagnostic时附带description和urlPR #4442分别用于给出更详细的问题说明与指向在线文档的链接。createTypeSpecLibrary的定义入口library.ts会透传这些字段IDE 悬浮提示与 CLI 输出可据此展示更友好的错误上下文const libDef { name: myLib, diagnostics: { my-code: { severity: error, messages: { default: Foo bar }, description: 详细说明..., url: https://example.com/docs/my-code, }, }, } as const;typespec/http新增HttpStream与JsonlStream流式模型0.61 为 HTTP 库引入流式响应的官方模型PR #4513定义位于 packages/http/lib/streams/main.tspimport typespec/streams; import ../main.tsp; using TypeSpec.Streams; namespace TypeSpec.Http.Streams; /** * 描述一个流协议类型数据由 Type 描述 * ContentType 与 BodyType 描述线上的编码方式。 */ doc() model HttpStream Type, ContentType extends valueof string, BodyType extends bytes | string string is StreamType { header contentType: typeof ContentType; body body: BodyType; } /** * 每行一个 JSON 对象、Content-Type 为 application/jsonl 的流。 */ doc() model JsonlStreamType is HttpStreamType, application/jsonl;用法示例来自该文件的 doc 注释model Message { id: string; text: string; } TypeSpec.Events.events union Events { Message, } op subscribe(): JsonlStreamEvents;要点HttpStream继承自typespec/streams库的StreamType抽象携带contentType头与body字段JsonlStreamType是HttpStreamType, application/jsonl的便捷别名Content-Type 固定为application/jsonl相关的 TS 实现与元数据提取逻辑位于 packages/http/src/experimental/streams.ts并有配套测试 streams.test.ts 与 get-stream-metadata.test.ts 验证元数据获取与模型解析行为。typespec/openapi3支持 Scalar 与 Object 作为默认类型0.61 允许default等场景下将Scalar与Object值用作默认类型PR #4423此前仅支持部分字面量形式。这使 OpenAPI 3 输出中默认值可以直接引用模型对象或标量实例减少了手写等价 JSON 的需要。typespec/json-schemaexample填充examples属性0.61 起example装饰器设置的示例值会写入 JSON Schema 输出的examples属性PR #4447model Pet { name: string; } example({ name: Fluffy }) model Example {}对应生成 JSON Schema 的examples: [{ name: Fluffy }]便于下游工具与文档系统直接消费示例数据。typespec-vscode编译任务、监视任务与 Web 兼容0.61 的 VS Code 扩展新增两类能力PR #4330Compile Task在编辑器中直接触发 TypeSpec 编译Watch Task启动tsp compile --watch监视模式保存即重编译。同时扩展实现了最小化的 Web 兼容PR #4498使依赖纯 Web 环境如 VSCode for Web的基础功能可用由于部分功能依赖 Node 运行时Web 模式下仅启用最小功能子集。Bug 修复清单0.61 的修复集中于编译器语义、示例序列化、LSP 缓存与平台兼容四类以下按库分组说明PR 编号见发布说明原文typespec/compiler语义遍历器修复exitTuple回调未被触发的问题——遍历 Tuple 节点时缺少对应的 exit 钩子PR #4513示例生成修复枚举嵌套在 union 中时example生成的示例不正确PR #4462修复向example传入模型类型的const值时的处理问题PR #4574示例的 JSON 序列化现在遵循encodedName即按编码后的属性名输出PR #4551数值解析修复 decimal 数值带多位前导0.0如0.00x时的解析错误PR #4514API 行为sourceModels属性在投影projection后能正确保持PR #4445补齐缺失的 exit 回调PR #4626使语义遍历的 enter/exit 配对完整配置与缓存修复 LSP 服务器中修改tspconfig.yaml后因缓存不生效的问题PR #4467tsp compile --watch现在会重新读取tspconfig.yaml的变更PR #4563。typespec/openapiinfo装饰器新增校验不允许提供不以x-开头的多余属性PR #4505保证 Info 对象符合 OpenAPI 规范info的termsOfService字段会校验为合法 URLPR #4483。typespec/internal-build-utils第三方声明third-party notice生成时忽略测试文件避免把测试依赖混入制品声明PR #4498。typespec-vscodeWindows 平台下执行.cmd文件如tsp-server.cmd时改用shell方式派生进程解决旧式spawn在部分 Windows 环境无法解析.cmd的问题PR #4430。升级路径与兼容性建议综合发布说明与源码0.61 升级清单可归纳为三步配置体检全局检索tspconfig.yaml与 emitter 选项中的键名凡含.的键改为嵌套对象写法避免编译器报错库作者适配若自定义库依赖旧装饰器参数封送行为临时导出definePackageFlags({ decoratorArgMarshalling: legacy })并尽快迁移该回退即将移除将NodePackage类型引用替换为PackageJson如需对外暴露.tsp子路径在package.json的exports中补typespec字段嵌入编译器 API 的场景确保传入的入口为绝对路径。尝鲜新能力流式接口HttpStream/JsonlStream、OpenAPI3 默认类型与 JSON Schemaexamples输出可直接用于新服务定义Type Mutators 属实验 API建议先在小范围验证再进入生产 emitter。本文所涉源码位置汇总编译器库定义、Type Mutators 实现、配置选项类型、HTTP 流式模型 及其 实现 与 测试可供深入研读。【免费下载链接】typespec项目地址: https://gitcode.com/GitHub_Trending/ty/typespec创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考