必须用 protoc-gen-typescript-http 而非 OpenAPI 工具，因其直读 proto AST，精准支持 oneof、map、Timestamp 等语义；而 OpenAPI 工具经 swagger 中转易丢字段、错枚举、漏嵌套。
用 Kratos 框架自动生成前端 TypeScript 请求接口，核心路径是：**写好 .proto 文件 → 用 protoc + protoc-gen-typescript-http 插件生成代码**。不需要 Swagger、不依赖运行时拉取、不手动维护类型——只要 proto 定义不变，生成的 TS 接口就绝对对齐后端。
为什么必须用 protoc-gen-typescript-http 而不是 OpenAPI 工具
Kratos 默认走 gRPC/REST 双协议，但它的契约源头是 Protobuf，不是 OpenAPI。后端改一个字段名，只动 user.proto 就够了；如果硬套 OpenAPI 流程（比如先从 gRPC gateway 导出 swagger.json，再用 openapi-typescript-codegen），中间多了一层转换，极易丢字段、错枚举、漏嵌套结构。更关键的是：protoc-gen-typescript-http 直接读取 proto AST，能精确还原 oneof、map<string, User>、google.protobuf.Timestamp 等语义，而 OpenAPI 工具普遍对这些支持薄弱或需额外注解。
protoc-gen-typescript-http 的安装与基础命令
确保已安装 protoc 和 Go 环境（Kratos 生态工具链强依赖 Go）：
- 全局安装插件：
go install github.com/go-kratos/kratos/cmd/protoc-gen-typescript-http@latest - 确认插件在 PATH 中：
protoc-gen-typescript-http --version应输出版本号 - 生成命令示例（假设 proto 在
api/user/v1/user.proto）：protoc -I . --typescript-http_out=service=true,client=true,import_style=module:./src/api api/user/v1/user.proto
注意参数含义：service=true 生成服务类（含方法调用），client=true 生成 HTTP 客户端实例，import_style=module 避免 CommonJS 导入冲突（尤其在 Vite/Vitest 环境下）。
完整的Galileo AI平台 TypeScript/JS SDK 参考，用于评估、观察和保护 GenAI 应用。适用于构建 Node.js 或 TypeScript 项目。
立即学习“前端免费学习笔记（深入）”；
生成结果里哪些文件必须保留，哪些可以删
默认生成目录结构类似：./src/api/user/v1/user_http.ts（含请求函数和类型）、./src/api/user/v1/user.ts（纯类型定义）。实际项目中建议：
- 保留
*_http.ts：它封装了fetch调用、URL 拼接、JSON 序列化逻辑，且每个方法都带完整泛型签名（如getUser(id: string): Promise<User>） - 保留
*.ts（纯类型）：供业务组件直接 import 类型，比如import { User } from '@/api/user/v1/user' - 可删
index.ts（如果存在）：它通常只是 re-export，容易和团队模块规范冲突，手写index.ts控制导出更可控 - 别删
google/protobuf/*.ts：这些是 timestamp、duration 等内置类型的映射，删了会导致编译报错
常见报错和绕过方式
生成失败大多卡在三个地方：
-
protoc-gen-typescript-http: program not found or is not executable：说明protoc找不到插件，检查$GOPATH/bin是否在 PATH 中，或改用绝对路径：--typescript-http_out=...:$GOPATH/bin/protoc-gen-typescript-http - 生成的请求 URL 缺少 base path（如本该是
/v1/users却生成了/users）：在 proto 的option (google.api.http)里显式写全路径，例如get: "/v1/users/{id}"，不要依赖 gateway 的自动前缀拼接 - 枚举值生成为数字而非字符串（如
status: number而非status: 'active' | 'disabled'）：在 proto 中给枚举加option (ts_type) = "string"，这是protoc-gen-typescript-http支持的扩展选项
最易被忽略的一点：生成的客户端默认用 fetch，但如果你项目里全局拦截器（如 token 注入、错误统一处理）是基于 Axios 的，不能直接把生成的函数当 Axios 实例用——要么改生成模板，要么在外层包一层适配器。强行混用会导致拦截器失效、loading 状态失控、错误码无法捕获。
