用途:为 TypeScript 项目建立类型安全的 API 客户端,适用于创建 API 集成或对接后端服务。
主要能力:架构分两层。全局 API 层(src/lib/api/)包含 api-client.ts(typedGet/Post/Put/Patch/Delete、apiRequestWrapper)、api.types.ts(ApiResult、ApiError、ErrorCode)、error-handler.ts(extractMessage、开发环境错误提示)、query-utils.ts(查询串与分页)、validation-utils.ts(Zod 校验辅助)。特性 API 层与所服务的功能同目录,如 src/mfes/items/api/items-api.ts,负责端点逻辑、Zod schema 与类型导出。
使用方式:每个 API 调用返回 ApiResult<T>,调用方检查 result.success 而不捕获异常。apiRequestWrapper 作为“抛异常世界”与“Result 世界”的边界,内部可抛错,wrapper 捕获后返回 ApiResult,并在开发模式通过 showDevErrorToast 弹提示。校验统一用 safeParse,失败由 handleZodValidationOrThrow 抛出 VALIDATION_ERROR,再被 wrapper 捕获。类型从 Zod schema 用 z.infer 推导,避免手写。请求体与响应数据都要校验,响应先以 typedGet<unknown> 获取原始数据再验证。查询参数用 buildQueryString。
代码生成:Orval 从 OpenAPI/Swagger 生成 Zod schema,配置在 scripts/api-codegen/config.ts,按 tag 过滤并输出到各特性的 generated 目录;命令为 pnpm api:gen items(单接口)或 pnpm api:gen(全部)。
适用场景:前后端分离、需要强类型与统一错误处理的 TypeScript 项目,尤其适合基于 Next.js 与 Zod 的代码库。
限制:资料仅覆盖上述模式与接口,未提供安装步骤、依赖版本、收费、性能与平台支持等信息,暂未提供。分类标识:编程与开发。