久滴直播电商平台 · 技术博客系列 第 8 篇 标签OpenAPIOrval前端SDKTypeScript前言前后端协作中最让人头疼的事情之一就是API 对接后端改了字段名前端不知道、TypeScript 类型定义和实际响应不一致、手写的 API 调用函数重复且容易出错……久滴直播电商平台引入了一套基于OpenAPI 3.0 Orval的自动生成方案——从后端导出一份openapi.json自动生成 Admin 管理后台和 UniApp 移动端两套 TypeScript API Client。本文将详细介绍这套方案的配置、使用和实践经验。目录手写 API 调用的痛点Orval 配置解析tags-split 模式按 Tag 自动拆分自定义 MutatorAdmin 用 axiosUniApp 桥接 luch-request一键生成与 CI 校验生成代码 vs 手写代码的共存策略1. 手写 API 调用的痛点先看一个典型的手写 API 调用// ❌ 手写 API 调用的问题exportconstgetProductList(params:any){returnget(/product/spu/list,params)}这段代码有几个明显的问题params类型是any完全丧失 TypeScript 的类型保护路径/product/spu/list硬编码后端改了路由前端不会报错返回值类型未知使用时需要手动断言当项目有上百个 API 时这些问题会被放大百倍。2. Orval 配置解析久滴平台使用 Orval 作为 OpenAPI SDK 生成工具配置文件orval.config.ts定义了两套输出import{defineConfig}fromorval;exportdefaultdefineConfig({// Admin 管理后台输出 admin:{input:{target:./openapi.json,},output:{target:./apps/web-antd/src/api/generated/index.ts,mode:tags-split,client:axios,override:{mutator:{path:./apps/web-antd/src/api/generated/mutator.ts,name:customInstance,},},},},// UniApp 移动端输出 uniapp:{input:{target:./openapi.json,},output:{target:../jiudi-live-mall-uniapp/src/api/generated/endpoints.ts,mode:tags-split,client:axios,override:{mutator:{path:../jiudi-live-mall-uniapp/src/api/generated/mutator.ts,name:customInstance,},},},},});关键配置解读配置项含义input.targetOpenAPI spec 文件路径同一份openapi.jsonoutput.target生成文件的输出路径output.modetags-split模式下文详述output.clientHTTP 客户端类型override.mutator自定义请求拦截器3. tags-split 模式按 Tag 自动拆分Orval 的tags-split模式会根据 OpenAPI spec 中每个接口的 Tag 自动拆分到不同文件src/api/generated/ ├── index.ts # 汇总导出 ├── mutator.ts # 自定义请求拦截器 ├── product.ts # Tag: Product 相关接口 ├── order.ts # Tag: Order 相关接口 ├── promotion.ts # Tag: Promotion 相关接口 ├── member.ts # Tag: Member 相关接口 ├── live.ts # Tag: Live 相关接口 └── system.ts # Tag: System 相关接口每个生成的文件包含请求函数带完整 TypeScript 类型的 API 调用函数类型定义请求参数和响应数据的 TypeScript 接口JSDoc 注释从 OpenAPI spec 中提取的接口描述// 自动生成示例product.ts/** * 获取商品 SPU 分页列表 * summary 商品分页 */exportconstgetProductSpuPage(params:ProductSpuPageReqVO){returncustomInstancePageResultProductSpuRespVO({url:/product/spu/page,method:GET,params,});};4. 自定义 MutatorAdmin 用 axiosUniApp 桥接 luch-requestOrval 的mutator机制允许自定义底层的 HTTP 请求实现。久滴平台利用这个特性让两个端使用不同的 HTTP 客户端但共享同一套 API 函数签名。Admin 端 mutatorAdmin 管理后台使用 axiosmutator 封装了 token 注入和错误处理// apps/web-antd/src/api/generated/mutator.tsimportaxiosfromaxios;import{useUserStore}from/store;exportconstcustomInstanceasyncT(config:any):PromiseT{constuserStoreuseUserStore();consttokenuserStore.getToken;constinstanceaxios.create({baseURL:import.meta.env.VITE_API_BASE_URL,timeout:10000,});// 注入 Authorization 头if(token){instance.defaults.headers.common[Authorization]Bearer${token};}constresponseawaitinstance(config);// 统一响应格式解包if(response.data.code0){returnresponse.data.data;}thrownewError(response.data.msg);};UniApp 端 mutatorUniApp 端使用luch-request基于uni.request封装mutator 负责桥接// src/api/generated/mutator.tsexportconstcustomInstanceasyncT(config:any):PromiseT{consttokenuni.getStorageSync(token);constresponseawaituni.$uv.http.request({url:config.url,method:config.method,data:config.data||config.params,header:{Authorization:token?Bearer${token}:,},});// 统一响应解包if(response.data.code0){returnresponse.data.dataasT;}thrownewError(response.data.msg);};通过 mutator两个端可以各自使用自己习惯的 HTTP 客户端但 API 调用代码完全一致。5. 一键生成与 CI 校验久滴平台定义了两个 npm script{scripts:{gen:api:orval --config orval.config.ts,check:api:orval --config orval.config.ts --watch false git diff --exit-code src/api/generated/}}生成流程# 1. 后端导出 openapi.json运行中的后端 /swagger 接口curlhttp://localhost:48080/v3/api-docsopenapi.json# 2. 一键生成两端 SDKpnpmgen:apiCI 校验在 CI 流水线中加入check:api步骤确保前端提交的生成代码与后端 spec 一致# CI 流水线步骤-name:Check API SDK consistencyrun:pnpm check:api如果开发者改了后端接口但忘了重新生成前端 SDKCI 会自动报错拦截。6. 生成代码 vs 手写代码的共存策略实际项目中不是所有 API 都适合自动生成。久滴平台的策略是src/api/ ├── generated/ # Orval 自动生成不要手动修改 │ ├── index.ts │ ├── product.ts │ └── ... ├── custom/ # 手写 API复杂逻辑、特殊处理 │ ├── live-custom.ts │ └── upload.ts └── index.ts # 统一导出原则generated/目录下的文件由 Orval 管理不要手动修改需要特殊处理的 API如文件上传、WebSocket放在custom/目录统一从index.ts导出业务代码不需要关心 API 来自哪个目录总结本文介绍了久滴直播电商平台的前端 API SDK 自动生成方案Orval OpenAPI 3.0一份openapi.json自动生成 Admin UniApp 两端 SDKtags-split 模式按 Tag 自动拆分 API 文件目录结构清晰自定义 mutatorAdmin 用 axiosUniApp 桥接 luch-request两端共享类型定义CI 校验pnpm check:api确保生成代码与后端接口一致防止遗漏共存策略generated 目录自动生成custom 目录手写特殊逻辑下一篇我们将深入工程架构看看 30 Maven 模块如何组织成 Open Core 双仓架构。久滴直播电商平台是一个基于 Spring Boot 3 Vue3 UniApp 的全栈开源直播电商解决方案。 giteehttps://gitee.com/live-mall-pro/communityCommunity 版如果觉得本文对你有帮助欢迎 Star ⭐ 支持