TypeSpec 在伦敦证券交易所集团LSEG的实践统一异构 API 与多语言 SDK 生成【免费下载链接】typespec项目地址: https://gitcode.com/GitHub_Trending/ty/typespec本文基于 TypeSpec 官方博客中微软与 LSEGLondon Stock Exchange Group合作案例的完整记录还原金融级 API 平台如何用 TypeSpec 解决“多套设计来源、多语言 SDK”的一致性与效率问题并结合当前仓库中的 emitter 包、版本化库与 VS Code 扩展源码给出可复制的工程实践方案。读完后你将理解为什么.tsp文件可以作为 API 定义的唯一事实来源、TypeSpec 的 emitter 可插拔架构如何驱动 OpenAPI 与 TypeScript/Python SDK 生成以及versioned版本化装饰器体系如何支撑 API 的版本演进。背景异构 API 集成的挑战LSEG 面对的核心难题是需要集成大量源自不同设计规范的 API。原文档指出一个组织陷入这种局面的原因是多方面的——API 可能在不同时期、由不同团队、为不同目的例如开发用户界面或以文件形式交付数据而构建也可能来自企业收购。这种不一致性带来了两个直接后果LSEG 难以为客户提供统一体验的 API客户将这些 API 集成进自身工作流的自由度受到限制。因此 LSEG 选择了微软推出的 API 设计语言 TypeSpec目标是用它带来 API 与 SDK 开发的一致性和效率。合作从双方核心人员的第一轮讨论开始LSEG 的明确目标是发布一版使用 TypeSpec 定义的 API并据此生成 OpenAPI 规范以及 TypeScript 和 Python 的 SDK供内部和外部客户使用。这个“一份定义、多路产出”的管线正是 TypeSpec 的核心能力后文将结合仓库源码逐一展开。TypeSpec 的价值LSEG 视角的四大收益跨 API 一致性单一事实来源在 TypeSpec 出现之前LSEG 维持多份 OpenAPI 规范之间的一致性依赖的是容易出错的复制粘贴和冗长的评审会议而且很少能完全成功。引入 TypeSpec 后API 可以用高层模板以统一方式构建重复性工作和错误都被大幅压缩。对于 API 来源多样的 LSEG 而言这一点尤为关键TypeSpec 充当 API 定义的单一事实来源single source of truth同时提升了规范的一致性与质量。从源码结构看这种“一份定义多路产出”的能力由编译器中的 emitter 机制承载。packages/compiler/src/core/program.ts 中程序状态显式持有emitters: EmitterRef[]列表见 L111 与 L266即一次编译可以同时挂载多个发射器把同一份编译后的 API 定义投影成 OpenAPI、SDK 等不同的目标产物——这与 LSEG“一份.tsp定义同时生成 OpenAPI TypeScript/Python SDK”的诉求完全对应。效率与速度十行.tsp换百行 OpenAPI原文档提到最受 LSEG 欢迎的收益之一定义 API 所需的代码量显著减少。对 LSEG 而言API 设计师因此可以把精力放到其他关键任务上从而加快开发节奏。一个直观的量级描述是十行的 TypeSpec 代码片段可以生成一百行的 OpenAPI 规范。这种高层抽象用类似高级语言的构造简化了 API 设计同时改善了代码组织。.tsp文件被当作 TypeScript 或 C# 源码一样管理——进版本库、走代码评审、享受语言工具链。以生成 OpenAPI 为例当前仓库中的 packages/openapi3/README.md 给出了标准用法npm install typespec/openapi3tsp compile . --emittypespec/openapi3或在tspconfig.yaml中声明emit: - typespec/openapi3 options: typespec/openapi3: option: value其中output-file选项支持{service-name}、{version}、{file-type}等插值占位符默认输出形如{service-name-if-multiple}.{version}.openapi.yaml——也就是说版本化的 API 会自动按版本拆分为多份 OpenAPI 文档这对 LSEG 这种按版本演进 API 的场景非常实用。增强型工具链错误左移TypeSpec 自带的高级工具能在早期捕获错误从而得到更健壮的 API。这种主动的错误检测对维持高标准的 API 质量至关重要也压缩了调试与返工的时间。此外Visual Studio 与 VS Code 的扩展提供了语法高亮、IntelliSense 等常用能力。当前仓库中 packages/typespec-vscode/README.md 列出了 VS Code 扩展的完整能力与博客描述一一对应IntelliSense 与自动补全、代码格式化与折叠、语法高亮实时诊断与快速修复即博客所说的“早期捕获错误”重构工具重命名、跳转到定义项目脚手架创建与 emitter 配置从现有 OpenAPI 3 定义导入 TypeSpec直接从.tsp文件触发代码发射OpenAPI 规范、服务端桩、客户端 SDK上下文菜单或TypeSpec: Emit From TypeSpec命令即可调用。前置条件是安装 Node.js 与 TypeSpec CLInpm install -g typespec/compiler。可及性非技术人员也能参与 API 评审TypeSpec 紧凑的体积加上熟悉的 JavaScript 风格语法使得非技术干系人也能参与 API 的评审与设计过程。这种包容性确保 API 设计吸收了组织中多种角色的视角最终得到更以用户为中心、更完善的 API 设计。对 LSEG 这类服务金融专业人士与客户机构的组织让业务方进入评审环节正是“十行代码生成百行规范”这种低门槛抽象带来的直接红利。高度定制的 SDK 生成emitter 可插拔架构博客明确指出TypeSpec 通过“emitters”发射器提供可插拔的生成架构用于提供定制化输出。LSEG 与微软 Industry Solutions EngineeringISE团队合作针对 LSEG 的需求构建了定制 emitter可以自动为不同类型的用户金融开发者、数据科学家生成易用 SDK产出语言为 TypeScript 和 Python。这一做法对 LSEG 的多元化用户群既有资深开发者也有编码经验有限的金融专业人士尤其有益。自动生成方式还大幅缩短了 SDK 发布时间同时保证了 LSEG API 在各环境间的能力对等functional parity既加速开发也让维护更容易。在仓库层面SDK 生成的官方实现对应两个包packages/http-client-jstypespec/http-client-js发射 JavaScript/TypeScript 客户端库packages/http-client-pythontypespec/http-client-python发射 Python SDK。二者的使用方式一致——命令行--emitemitter或配置文件中声明——例如 Python 侧的 emitter 选项就包含了 LSEG 这类多版本服务会用到的api-version默认取最新版本支持latest/all多服务场景可为每个服务命名空间单独指定版本、package-name、generate-packaging-files、generation-subdir把生成代码与手写定制代码隔离重新生成时只覆盖子目录、保留定制内容等。这些参数正是“定制 emitter”思路在官方包中的落地形态LSEG 的 ISE 定制 emitter 与官方 emitter 遵循同一套插件契约。克服的挑战版本化、API-First 与客户反馈命名空间与版本化语言特性与 emitter 落地的差距博客坦诚指出TypeSpec 的命名空间与版本化装饰器是防止 LSEG 庞大 API 版图出现命名冲突的关键特性但当时现有 emitter原文指 AutoRest for Python 和 TypeScript 一系的生成器对它们的支持并不一致双方正在协同解决。当前仓库中版本化能力的语言侧已经相当完整参见 packages/versioning/README.mdversioned标记命名空间由某个枚举定义版本enum Versions { v1, v2, v3 }added/removed标记类型、属性、操作、枚举等在某版本被新增/移除madeOptional/madeRequired跟踪属性必填性变化renamedFrom/typeChangedFrom/returnTypeChangedFrom跟踪重命名、属性类型与返回类型演进useDependency声明某服务版本依赖的库版本。对 emitter 而言版本化不是简单地“过滤代码”而是与编译器的投影projection机制配合使用buildVersionProjections(program, serviceNamespace)返回各版本对应的投影projectProgram(program, projection.projections)得到“该版本下的服务表示”若需要跨版本的完整演进视图则可用getAddedOn、getRemovedOn等装饰器访问器直接取元数据。这套机制意味着“为每个版本生成独立 OpenAPI/SDK”在语言层面是一等公民能力——也解释了为何博客把 emitter 对版本化的支持列为首要攻坚项。拥抱 API-First从技术项目到产品战略迁移到 TypeSpec 不只是技术项目。作为转型的一部分LSEG 采用了API-First 开发方法把 API 置于产品战略的核心。原文档强调的目标是保证原生 Web API 与 Python/TypeScript SDK 之间的功能对等同时提供各目标环境特有的功能与工作流让客户完全掌控其使用 API 的方式。客户反馈驱动迭代原文档预期 LSEG 客户在使用新 API 与 SDK 后会提供宝贵反馈用于指导后续迭代。LSEG 已在第三季度Q3发布了 TypeSpec 生成 API 的首个早期访问版本并正在与用户接触、收集反馈、规划后续迭代。路径展望与结论面向未来博客给出的计划是持续增强 TypeSpec——按需添加新特性、解决出现的问题目标是不断改进 TypeSpec 语言与工具链为 API 开发者提供尽可能好的体验。结论层面TypeSpec 对 LSEG 是一次转变性的工具升级为 API 与 SDK 开发带来一致性、效率与易用性。借助 TypeSpecLSEG 精简了开发流程、减少了手工劳动并为客户提供了更一致、更友好的体验。关于 LSEG 与微软的合作LSEG 与微软已启动为期 10 年的战略合作共同开发下一代数据与分析解决方案及云基础设施目标是在金融市场加速价值创造为金融服务组织提供可互操作、安全、合规的解决方案从而变革数据、分析与工作流体验。延伸阅读仓库内可核对的实现路径主题仓库内对应资源案例原文website/src/content/blog/2024-11-04-typespec-at-lseg/blog.mdemitter 可插拔机制packages/compiler/src/core/program.ts 中的emitters: EmitterRef[]OpenAPI 3 生成packages/openapi3/README.mdTypeScript/JS SDK 生成packages/http-client-js/README.mdPython SDK 生成packages/http-client-python/README.md版本化装饰器与投影机制packages/versioning/README.mdVS Code 工具链packages/typespec-vscode/README.md需要说明的前提博客所述合作与时间线以 2024-11-04 的发布内容为准如“Q3 发布早期访问版本”仓库内各包的当前选项与接口以后续版本演进为准本文引用的参数说明均来自当前仓库对应 README。【免费下载链接】typespec项目地址: https://gitcode.com/GitHub_Trending/ty/typespec创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考