Rust中使用Salvo自动生成API服务、TypeScript和Dart
内容提要
该项目使用Rust的Salvo框架生成API服务，并能自动生成Swagger架构。使用Salvo可以避免手动工作，如指定OpenAPI属性。通过Salvo生成的API可以用于TypeScript和Dart项目。文章还介绍了如何使用SvelteKit生成TypeScript前端客户端，并使用自动生成的TypeScript API进行测试。此外，文章还介绍了如何使用swagger_dart_code_generator工具生成Dart代码，并在Flutter应用程序中使用生成的API。
延伸解读
为何选择 Salvo 自动生成 Swagger
文章指出，团队在对比 GraphQL、tRPC、gRPC 等技术后，发现它们常缺少错误类型、返回类型，或将所有字段设为可选，导致客户端类型不准确。Salvo 能自动将 Rust 结构转换为完整的 Swagger 架构，包括返回类型和错误枚举，无需手动编写 OpenAPI 属性。这减少了手动维护 API 文档的工作量，并提升了客户端与服务端之间类型的一致性。
TypeScript 客户端的生成与使用
在 SvelteKit 项目中，通过 npm 脚本调用 openapi-generator-cli，从本地 Swagger 端点生成 typescript-fetch 客户端。生成的代码包含自动完成、参数、错误类型和输入/输出类型，可直接在页面中导入并使用。文章强调，生成过程不依赖特定前端框架，React、Vue 等同样适用，这为 TypeScript 项目提供了可复用的 API 集成方式。
Dart 代码生成工具的选择
文章提到，尝试多个 Dart 自动生成工具后，发现不少工具存在缺陷或遗漏关键部分（如返回类型）。最终选用 swagger_dart_code_generator，它能生成类型、枚举和复杂对象。配置 build.yaml 后，运行 build_runner 即可下载 openapi.json 并生成 Dart 代码。在 Flutter 应用中，通过生成的 Openapi 类发起请求，并处理返回的字符串或复杂对象。
跨语言 API 一致性的实践价值
文章的核心动机是解决跨 API 团队中客户端与服务端对象、类型和类不一致的问题。通过 Salvo 自动生成 Swagger，并利用同一份规范生成 TypeScript 和 Dart 客户端，可以减少手动编写服务代码的错误和更新成本。文章还提到，完整版支持错误枚举和状态代码字符串，帮助开发者明确处理异常，这体现了自动化生成在维护多端一致性上的实际作用。
Q&A
为什么选择Salvo框架来自动生成API服务？
Salvo可以自动生成完整的Swagger架构，包括返回类型、错误枚举等，无需手动指定OpenAPI属性。它解决了其他技术（如GraphQL、gRPC）缺少自动客户端转换、错误类型和返回类型等问题，确保客户端和服务之间的对象、类型和类保持准确。
如何用Salvo设置一个简单的Rust API项目？
首先创建项目目录和Rust项目，在Cargo.toml中添加salvo（启用oapi和cors特性）、tokio和tracing等依赖。然后在main.rs中编写端点（如hello函数），配置路由、OpenApi文档和Swagger UI，并设置CORS。运行cargo run即可启动服务，访问http://127.0.0.1:5800/ui/查看Swagger UI。
如何从Salvo生成的Swagger为TypeScript前端生成API客户端？
在SvelteKit项目的package.json中添加脚本，使用@openapitools/openapi-generator-cli命令，指定输入为Salvo的OpenAPI JSON地址（如http://127.0.0.1:5800/api-doc/openapi.json），生成器为typescript-fetch，输出到./src/api/。运行npm run gen-api即可生成TypeScript客户端代码，然后在页面中导入并使用。
在Flutter中如何自动生成Dart API代码？
使用swagger_dart_code_generator工具。在pubspec.yaml中添加依赖，创建build.yaml配置输入文件夹和OpenAPI URL，然后运行dart run build_runner build。这会下载OpenAPI规范并生成Dart代码到指定目录。之后在main.dart中导入生成的API，创建客户端实例并调用方法。
自动生成的API客户端有哪些好处？
自动生成的客户端提供准确的类型、自动完成、参数和错误类型，确保客户端与服务端一致，减少手动编写服务的工作量和错误。它支持复杂类型返回、验证和错误枚举，提升开发效率和代码可靠性。
Salvo生成的API支持哪些高级功能？
Salvo生成的API支持复杂类型返回、验证、错误枚举和状态代码字符串，使开发者能清楚处理各种情况。这些功能通过自动生成的Swagger架构体现，无需手动指定OpenAPI属性。
