TypeSpec C 服务端代码生成实战：从 TypeSpec 定义到可运行的 ASP.NET Core 服务

TypeSpec C# 服务端代码生成实战从 TypeSpec 定义到可运行的 ASP.NET Core 服务【免费下载链接】typespec项目地址: https://gitcode.com/GitHub_Trending/ty/typespecTypeSpec 的代码生成能力允许你仅凭一份 TypeSpec 定义快速搭建出可工作的 API 服务。本指南以当前仓库的typespec/http-server-csharp服务端发射器emitter为核心带你走完从安装 TypeSpec、初始化项目、脚手架生成scaffolding到定制业务逻辑的完整流程并深入到仓库源码与快照测试剖析生成代码的分层结构与 ASP.NET Core 依赖注入机制。读完本文你将掌握用tsp定义接口、用hscs-scaffold一键生成 .NET 9 服务骨架、在不丢失业务逻辑的前提下持续演进 API 的完整实战方案。前置条件在开始之前请确认你的环境满足以下要求.NET 9 已安装C# 服务端代码生成会产出一个 .NET 9 项目运行dotnet run需要对应 SDK仓库快照中的生成项目均面向 .NET 9Node.js 与 npm用于全局安装 TypeSpec 编译器也用于执行npx hscs-scaffold脚手架命令该命令通过 npm 包typespec/http-server-csharp提供见 package.json 中的bin字段TypeSpec 基础认知了解model、interface、route、get等基本语法。1. 安装 TypeSpecTypeSpec 编译器以 npm 包形式发布全局安装即可获得tsp命令行工具npm install -g typespec/compilerlatest安装完成后tsp命令即可全局可用。后续所有编译、发射动作都围绕该命令展开。2. 创建 TypeSpec 项目2.1 初始化目录mkdir myproject cd myproject2.2 交互式初始化tsp init按提示选择模板选择Generic REST API创建标准 REST API 项目输入项目名或接受默认值在 emitter 选项中勾选C# Server Stubs。初始化完成后项目结构包含三类关键文件文件作用main.tspTypeSpec 定义文件内含一个示例服务tspconfig.yamlemitter 的配置文件package.json项目依赖清单3. 理解默认的 TypeSpec 服务初始化生成的main.tsp包含一个默认的 Widget Service 示例定义了完整的 CRUD 与一个特殊分析操作import typespec/http; using TypeSpec.Http; service(#{ title: Widget Service }) namespace DemoService; model Widget { id: string; weight: int32; color: red | blue; } model WidgetList { items: Widget[]; } error model Error { code: int32; message: string; } model AnalyzeResult { id: string; analysis: string; } route(/widgets) tag(Widgets) interface Widgets { /** List widgets */ get list(): WidgetList | Error; /** Read widgets */ get read(path id: string): Widget | Error; /** Create a widget */ post create(body body: Widget): Widget | Error; /** Update a widget */ patch update(path id: string, body body: Widget): Widget | Error; /** Delete a widget */ delete delete(path id: string): void | Error; /** Analyze a widget */ route({id}/analyze) post analyze(path id: string): AnalyzeResult | Error; }这段定义声明了Widget模型包含id、weight、color三个属性一套标准 REST CRUD 操作list / read / create / update / delete一个针对单个 widget 的analyze特殊操作POST /widgets/{id}/analyze通过| Error联合类型表达错误响应error装饰器标记的模型会被识别为错误模型。3.1 tspconfig.yaml发射器配置emit: - typespec/openapi3 - typespec/http-server-csharp options: typespec/openapi3: emitter-output-dir: {output-dir}/schema openapi-versions: - 3.1.0 typespec/http-server-csharp: emitter-output-dir: {output-dir}/server/generated该配置的作用将 OpenAPI 3.1.0 schema 生成到tsp-output/schema目录{output-dir}的默认值是tsp-output将 C# 服务端代码生成到tsp-output/server/generated目录。这里配置的emitter-output-dir显式覆盖了发射器的默认输出位置——不配置时typespec/http-server-csharp默认输出到{output-dir}/typespec/http-server-csharp见 README.md 中emitter-output-dir选项说明。4. 脚手架生成Scaffolding你的服务下一步是从 TypeSpec 定义生成服务端代码这一步称为scaffolding脚手架生成npx hscs-scaffold . --use-swaggerui --overwrite关于npx的说明npx会优先执行项目本地node_modules中的二进制。当你在多个 TypeSpec 项目间切换、且各项目依赖不同版本时这能保证你使用的是当前项目安装的脚手架工具版本。--use-swaggerui标志会在生成的服务中附加一个 Swagger UI 端点。开发阶段可直接在浏览器中调用 API非常方便。执行后控制台会打印生成位置、运行方式与 Swagger UI 访问地址类似Your project was successfully created at tsp-output/server/aspnet You can build and start the project using dotnet run --project tsp-output/server/aspnet You can browse the swagger UI to test your service using start https://localhost:7348/swagger/从源码看hscs-scaffold实际是tsp compile的封装cli.ts 会拼装tsp compile spec --emit typespec/http-server-csharp并注入emit-mocksmocks-and-project-files、project-name等 emitter 选项当传入--use-swaggerui时还会追加typespec/openapi3发射器并设置use-swaggeruitrue见 cli.ts。5. 运行你的服务生成的是一个完整可编译的 .NET 9 项目直接运行dotnet run --project tsp-output/server/aspnet服务启动后在浏览器访问https://localhost:port/swaggerport为控制台打印的端口上例为7348即可看到 Swagger UI 界面该界面允许你查看全部可用 API 端点直接测试每个 API 操作查看请求与响应的数据格式。6. 理解生成的代码结构脚手架的产物分为两大类理解二者的边界是后续演进 API 的关键。6.1 generated 目录生成文件不要直接修改这些文件位于generated目录每次重新编译 TypeSpec 都会被重新生成并就地替换Controllers控制器面向 HTTP 前端的 API 入口负责接收请求。示例WidgetsController.cs处理/widgets路由控制器中的每个方法都对应 TypeSpec interface 中的一个操作。仓库快照 PetsController.cs 展示了典型形态类上标注[ApiController]方法上使用[HttpGet]、[Route(/pets/{id})]、[ProducesResponseType(...)]等特性方法体只做一件事——调用业务接口并把结果包装成IActionResult。Operations interfaces业务逻辑接口业务逻辑的定义。示例IWidgets.cs定义了ListWidgetsAsync()等方法每个 TypeSpecinterface或包含操作但未显式声明 interface 的 namespace会对应一个业务逻辑接口见 usage.md。快照中的 IPets.cs 将query、path参数映射为 C# 方法参数int? skip、long id把PetListResult | Error之类的返回类型收敛为单个返回类型。Models模型请求/响应数据结构。示例Widget.cs、WidgetList.cs直接对应 TypeSpec 中定义的模型模型是partial类允许你在generated目录之外通过 partial 类扩展内部使用的成员见 usage.md 的 Models 一节。此外generated目录还包含一个lib子目录一组支撑模型与控制器的库文件例如HttpServiceException.cs、HttpServiceExceptionFilter.cs、JsonSerializationProvider.cs、Base64UrlJsonConverter.cs、TimeSpanDurationConverter.cs等见 快照目录。HttpServiceException是错误模型的基类用于封装错误细节并支持抛出与捕获error标记的模型会被生成为继承HttpServiceException的异常模型。6.2 可定制文件你的实现领地这些文件专供你修改承载业务实现Implementation classes实现类业务逻辑接口的 Mock 实现。示例Widgets.cs是你添加业务逻辑的地方发射器生成的 Mock 实现会返回语法正确的响应调用IInitializer.InitializeT()构造默认实例见快照 Pets.cs重新编译时这些文件不会被覆盖你的业务逻辑得以保留。Program.cs应用入口与服务配置。快照 Program.cs 展示了完整结构AddControllersWithViews注册HttpServiceExceptionFilter过滤器、调用MockRegistration.Register(builder)注册依赖、启用 HTTPS 重定向与静态文件、配置请求体缓冲并映射默认路由。MockRegistration.cs依赖注入配置。该文件把你的实现类与控制器接口连接起来如果你创建了自定义服务类就在这里注册。快照 MockRegistration.cs 中可以看到builder.Services.AddScopedIPets, Pets()这样的一一注册模式以及AddHttpContextAccessor()、IInitializer、多部分表单支持等配套注册。7. 理解依赖注入系统生成的 C# 服务借助 ASP.NET Core 内置的依赖注入容器把控制器与业务逻辑连接起来链路如下generated目录中的控制器依赖接口类型如IWidgets通过构造函数注入获取实例——见 PetsController.cs 的构造函数注入写法你的实现类如Widgets实现这些接口MockRegistration.cs在启动时把实现注册进依赖注入容器请求到达时控制器调用你的实现完成业务再返回 HTTP 响应。如果你需要注册额外的服务或依赖只需在MockRegistration.cs中追加注册代码。这一机制保证控制器与实现解耦换实现不改控制器改控制器不碰业务代码。8. 添加业务逻辑定位服务的实现文件如Widgets.cs用真实业务逻辑替换 Mock 实现例如public async TaskWidget[] ListAsync() { // Replace the mock implementation with your actual database query return new Widget[] { new Widget { Id 1, Weight 10, Color red }, new Widget { Id 2, Weight 15, Color blue } }; }重新编译 TypeSpec 时该实现文件不会被覆盖业务逻辑得以保留。从仓库的设计意图看Mock 实现除了返回合规响应外还示范了如何通过IHttpContextAccessor访问请求/响应细节Mock 构造函数注入IInitializer与IHttpContextAccessor见 Pets.cs你的真实实现同样可以沿用这一模式获取 HTTP 上下文信息usage.md 的 Business Logic Interfaces 一节对此有明确说明。9. 演进你的 APIAPI 会持续演化正确姿势是改 TypeSpec → 重新编译 → 增量脚手架。修改 TypeSpec 定义新增模型或操作重新编译以更新生成代码tsp compile .这会更新 generated 目录下的控制器、接口与模型但保留你的实现文件。若新增了全新资源、需要新的实现文件再跑一次脚手架npx hscs-scaffold main.tsp例如新增一个Categoriesinterfaceroute(/categories) tag(Categories) interface Categories { /** List categories */ get list(): CategoryList | Error; // More operations... }再次执行脚手架后为新的Categoriesinterface 创建新文件CategoriesController.cs、ICategories.cs、CategoriesImpl.cs不会覆盖已包含自定义业务逻辑的Widgets.cs因此你可以增量添加新资源而不会丢失既有实现。仓库测试对此有完整印证快照样例 sample-service.tsp 定义了Pets与Dogs两个 interface对应生成PetsController.cs/IPets.cs/Pets.cs与DogsController.cs/IDogs.cs/Dogs.cs两套文件验证了一个 interface 一套文件的增量生成模型。10. 高级定制选项脚手架 CLI 提供丰富的定制参数npx hscs-scaffold main.tsp --help常用选项参数定义见 cli.ts选项说明默认值--project-name name设置生成的项目名ServiceProject--http-port port设置本地 HTTP 端口未指定时在 5000-5999 范围内自动探测空闲端口自动--https-port port设置本地 HTTPS 端口未指定时在 7000-7999 范围内自动探测空闲端口自动--output path把项目生成到其他位置影响 emitter 与 openapi 输出目录默认 tsp-output--use-swaggerui附带 OpenAPI 生成与 Swagger UI 端点要求项目依赖typespec/openapi3false--overwrite覆盖已存在的实现与项目文件。注意CLI 层该选项默认开启cli.ts而直接作为 emitter 选项使用时默认关闭见 README.md。想保留手写实现时请谨慎使用如需把实现重置回 Mock 版本再显式开启CLI:true/ emitter:false--collection-type type集合类型array或enumerablearray除 CLI 参数外直接使用 emitter 时还可以通过tspconfig.yaml的options段配置更多选项完整清单见 docs/emitter.md 与 README.mdemitter-output-dirabsolutePath发射器输出目录默认{output-dir}/typespec/http-server-csharpskip-formatboolean默认false跳过 C# 文件的格式化——默认情况下生成的 C# 文件会使用dotnet format格式化output-typemodels | all默认all选择只发射模型models还是全部产物emit-mocksmocks-and-project-files | mocks-only | none默认none发射 Mock 业务实现、启动代码与项目文件让服务在真实实现交付前即可响应请求mocks-and-project-files正是hscs-scaffold内部注入的模式use-swaggeruiboolean默认false在开发配置中启用 Swagger UI 端点openapi-pathstring指定 Swagger UI 读取的 OpenAPI 文件路径启用use-swaggerui时默认指向openapi/openapi.yaml。下一步方向阅读生成项目docs文件夹内附带的 README 与使用文档发射器本身也会生成对应文档见 packages/http-server-csharp/docs为服务添加认证机制实现数据校验与错误处理HttpServiceException与HttpServiceExceptionFilter已为你铺好错误处理的基础设施把实现连接到真实数据库。参考资源发射器核心源码packages/http-server-csharp/src控制器、接口、模型、序列化、脚手架等组件的渲染逻辑脚手架 CLI 实现cli.ts发射器选项文档docs/emitter.md生成结构说明docs/usage.md完整快照样例PetStore 示例test/snapshots/sample-service【免费下载链接】typespec项目地址: https://gitcode.com/GitHub_Trending/ty/typespec创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考