ts-proto-client 1.0.3 → 1.0.5

package/README.md

@@ -1,217 +1,232 @@
-# ts-proto-client
-
-基于 Proto 文件自动生成 TypeScript 类型和 API 请求代码的 CLI 工具。
-
-## 功能
-
-* 根据 `.proto` 文件生成 TypeScript 类型
-* 根据 Service 定义生成 API 请求方法
-* 支持自定义 Proto 根目录
-* 支持自定义类型输出目录
-* 支持自定义 API 输出目录
-
----
-
-## 安装前准备
-
-本工具依赖 `protoc`，请先安装 Protocol Buffers 编译器。
-
-### macOS
-
-安装：
-
-```bash
-brew install protobuf
-```
-
-验证：
-
-```bash
-protoc --version
-```
-
-输出示例：
-
-```text
-libprotoc 35.1
-```
-
----
-
-### Windows
-
-1. 打开 Protocol Buffers Releases 页面
-
-https://github.com/protocolbuffers/protobuf/releases
-
-2. 下载对应版本
-
-```text
-protoc-35.1-win64.zip
-```
-
-3. 解压到目录，例如：
-
-```text
-D:\protoc
-```
-
-目录结构：
-
-```text
-D:\protoc
-├─ bin
-│  └─ protoc.exe
-├─ include
-└─ readme.txt
-```
-
-4. 将以下目录添加到系统环境变量：
-
-```text
-D:\protoc\bin
-```
-
-5. 打开新的终端验证：
-
-```bash
-protoc --version
-```
-
-输出示例：
-
-```text
-libprotoc 35.1
-```
-
----
-
-## 使用方式
-
-### 生成代码
-
-```bash
-npx proto-gen generate \
-  --file ./account.proto \
-  --root ../protos \
-  --type-output src/protos/type \
-  --api-output src/protos/api/account
-```
-
-### 参数说明
-
-| 参数              | 必填 | 说明                        |
-| --------------- | -- | ------------------------- |
-| `--file`        | 是  | Proto 文件路径（相对于 Proto 根目录） |
-| `--root`        | 是  | Proto 根目录                 |
-| `--type-output` | 是  | TypeScript 类型输出目录         |
-| `--api-output`  | 是  | API 文件输出目录                |
-
----
-
-## 示例
-
-目录结构：
-
-```text
-project
-├─ src
-├─ protos
-│  ├─ hospital
-│  │  └─ account.proto
-│  └─ third_party
-└─ package.json
-```
-
-执行：
-
-```bash
-npx proto-gen generate \
-  --file hospital/account.proto \
-  --root ./protos \
-  --type-output src/protos/type \
-  --api-output src/protos/api/account
-```
-
-生成：
-
-```text
-src
-└─ protos
-    ├─ type
-    │  └─ account.ts
-    └─ api
-        └─ account.ts
-```
-
----
-
-## 本地开发
-
-启动开发模式：
-
-```bash
-pnpm dev generate \
-  --file hospital/account.proto \
-  --root ../protos \
-  --type-output src/protos/type \
-  --api-output src/protos/api/account
-```
-
----
-
-## 常见问题
-
-### protoc: command not found
-
-请确认已经正确安装 protoc，并配置到环境变量：
-
-```bash
-protoc --version
-```
-
-能够正常输出版本号。
-
----
-
-### File does not reside within any path specified using --proto_path
-
-请检查：
-
-```bash
---file
-```
-
-指定的文件是否位于：
-
-```bash
---root
-```
-
-指定的目录之下。
-
-例如：
-
-```bash
---root ./protos
---file hospital/account.proto
-```
-
-则实际文件应存在：
-
-```text
-./protos/hospital/account.proto
-```
-
----
-
-## 环境要求
-
-* Node.js >= 18
-* protoc >= 35
-
----
-
-## License
-
-MIT
+# ts-proto-client
+
+基于 Proto 文件自动生成 TypeScript 类型声明和 API 请求函数的 CLI 工具。
+
+## 功能
+
+- **类型生成** — 调用 `protoc` + `ts-proto` 插件，将 `.proto` 文件编译为 TypeScript 类型声明
+- **API 生成** — 解析 Proto 中的 `service` 定义及 HTTP 注解（`google.api.http`），自动生成类型安全的 API 请求函数
+- **自动识别 Proto 根目录** — 从文件路径中自动定位 `protos` 目录，无需手动配置
+- **灵活的输出路径** — 支持自定义 TypeScript 类型和 API 代码的输出目录
+
+---
+
+## 原理
+
+工具将 `.proto` 文件拆分为两个产物：
+
+| 产物 | 生成方式 | 说明 |
+| --- | --- | --- |
+| **TypeScript 类型** (`.ts`) | 调用 `protoc` + `ts-proto` 插件 | 将 proto message 编译为 TS interface/type |
+| **API 请求函数** (`.ts`) | 使用 `protobufjs` 解析 proto，提取 `service` + HTTP 注解 | 生成调用 `service()` 的函数，入参与返回值均有类型约束 |
+
+生成的 API 函数依赖项目中的 `service` 工具函数（需由使用者自行实现），函数签名示例：
+
+```ts
+import { service } from "../..";
+
+import type {
+  HelloRequest,
+  HelloResponse,
+} from "@/protos/type/hello";
+
+// 登录
+export function Login(data: HelloRequest) {
+  return service<HelloResponse["data"]>({
+    url: "/hello",
+    method: "post",
+    data
+  })
+}
+```
+
+---
+
+## 环境要求
+
+- **Node.js** >= 18
+- **protoc** >= 3.15（需支持 `--ts_proto_out`）
+- **pnpm**（推荐，也可使用 npm / yarn）
+
+---
+
+## 安装
+
+```bash
+# 安装本工具
+pnpm add -D ts-proto-client
+
+# 安装 ts-proto 依赖（本工具通过 protoc 调用 ts-proto 插件）
+pnpm add -D ts-proto
+```
+
+---
+
+## protoc 安装
+
+本工具依赖 `protoc`（Protocol Buffers 编译器），请先安装。
+
+### macOS
+
+```bash
+brew install protobuf
+protoc --version  # 验证安装
+```
+
+### Windows
+
+1. 从 [Protocol Buffers Releases](https://github.com/protocolbuffers/protobuf/releases) 下载 `protoc-<version>-win64.zip`
+2. 解压到目标目录（如 `D:\protoc`）
+3. 将 `D:\protoc\bin` 添加到系统环境变量 `PATH`
+4. 验证：`protoc --version`
+
+---
+
+## 使用方式
+
+```bash
+# 基本用法
+npx proto-gen generate --file <proto 文件路径>
+
+# 自定义输出路径
+npx proto-gen generate \
+  --file <proto 文件路径> \
+  --type-path <类型输出目录> \
+  --api-path <API 输出目录>
+```
+
+### 示例
+
+```bash
+npx proto-gen generate \
+  --file ./src/data/protos/xishan-guiyuan/ruralVisualization.proto
+```
+
+---
+
+## 参数说明
+
+| 参数 | 必填 | 默认值 | 说明 |
+| --- | --- | --- | --- |
+| `--file` | 是 | — | Proto 文件的完整路径 |
+| `--type-path` | 否 | `src/protos/type` | TypeScript 类型声明的输出目录 |
+| `--api-path` | 否 | `src/protos/api` | API 请求函数的输出目录 |
+
+---
+
+## 目录约定
+
+工具会在 `--file` 的文件路径中自动查找 **`protos`** 目录，并将其作为 Proto 根目录。
+
+### 示例目录结构
+
+```text
+src
+└─ data
+   └─ protos              ← 工具自动识别此目录为 Proto Root
+      ├─ hospital
+      │  └─ account.proto
+      └─ xishan-guiyuan
+         └─ ruralVisualization.proto
+```
+
+### 生成结果
+
+执行：
+
+```bash
+npx proto-gen generate \
+  --file ./src/data/protos/xishan-guiyuan/ruralVisualization.proto
+```
+
+输出：
+
+```text
+src
+└─ protos
+   ├─ type                       ← TypeScript 类型（默认）
+   │  └─ xishan-guiyuan
+   │     └─ ruralVisualization.ts
+   └─ api                        ← API 请求函数（默认）
+      └─ ruralVisualization.ts
+```
+
+生成的目录结构会保持 proto 文件在 `protos` 下的相对路径。
+
+---
+
+## Proto 文件要求
+
+工具依赖 Proto 文件中的 **HTTP 注解**来生成 API 函数，需要你的 `.proto` 文件包含：
+
+1. **`google.api.http` 选项** — 定义 HTTP 方法和路径
+2. **`openapiv2_operation.summary` 选项** — 作为生成函数的注释（可选）
+
+示例：
+
+```protobuf
+import "google/api/annotations.proto";
+
+service UserService {
+  rpc GetUser(GetUserRequest) returns (GetUserResponse) {
+    option (google.api.http) = {
+      get: "/api/user/{id}"
+    };
+    option (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_operation) = {
+      summary: "获取用户信息"
+    };
+  }
+}
+```
+
+> 需要第三方 proto 文件（`google/api/annotations.proto` 等），请将它们放置在 `protos/third_party/googleapis/` 目录下。
+
+---
+
+## 本地开发
+
+```bash
+# 开发模式（直接运行 TS 源码）
+pnpm dev generate --file <proto 文件路径>
+
+# 构建
+pnpm build
+```
+
+---
+
+## 常见问题
+
+### protoc: command not found
+
+`protoc` 未安装或未添加到 PATH，请参考上方 [protoc 安装](#protoc-安装) 章节。
+
+### protoc-gen-ts_proto: command not found
+
+`ts-proto` 未安装，执行：
+
+```bash
+pnpm add -D ts-proto
+```
+
+### 未找到 protos 根目录
+
+工具通过查找路径中的 `protos` 目录来确定 Proto 根目录。如果你的目录名不是 `protos`（例如 `protobuf`），将无法自动识别。
+
+正确示例：
+
+```bash
+--file ./src/data/protos/hospital/account.proto  ✅
+```
+
+无法识别：
+
+```bash
+--file ./src/data/protobuf/hospital/account.proto ❌
+```
+
+---
+
+## License
+
+MIT

package/dist/index.js

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
-import{Command as q}from"commander";import R from"fs";import b from"path";import y from"fs";import j from"path";import{Root as x,Service as P}from"protobufjs";import u from"path";import C from"fs";var g=["get","post","put","delete","patch"];function w(t){let o=[t,u.join(t,"/third_party/googleapis")],e=new x;return e.resolvePath=(n,p)=>{for(let s of o){let i=u.join(s,p);if(C.existsSync(i))return i}return p},e}function h(t,o=[]){if(!t.nested)return o;for(let e of Object.values(t.nested))e instanceof P&&o.push(e),h(e,o);return o}function A(t){let o=t.parsedOptions?.find(n=>n["(google.api.http)"])?.["(google.api.http)"];if(!o)return null;let e=g.find(n=>o[n]);return e?{method:e,url:o[e],summary:t.options?.["(grpc.gateway.protoc_gen_openapiv2.options.openapiv2_operation).summary"]}:null}function O(t,o){let e=u.resolve(process.cwd(),t),n=w(e);n.loadSync(u.join(e,o));let p=h(n),s={};for(let i of p){let a=[];for(let r of Object.values(i.methods)){let m=A(r);m&&a.push({name:r.name,requestType:r.requestType,responseType:r.responseType,...m})}s[i.name]=a}return s}function v(t,o){let e=[];for(let[n,p]of Object.entries(t)){let s=new Set,i=[];for(let r of p){s.add(r.requestType),s.add(r.responseType);let m=r.method==="get"?"params: data":"data",d=[];r.summary&&d.push(`// ${r.summary}`),d.push(`export function ${r.name}(data: ${r.requestType}) {`,`  return service<${r.responseType}>({`,`    url: "${r.url.replace("/api","")}",`,`    method: "${r.method}",`,`    ${m}`,"  })","}"),i.push(d.join(`
-`))}let a=[...s].sort();e.push({[n]:['import { service } from "@/plugins";',"","import type {",`  ${a.join(`,
-  `)}`,`} from "${o}";`,"",i.join(`
+import{Command as M}from"commander";import k from"fs";import R from"path";import E from"fs";import l from"fs";import j from"path";import{Root as D,Service as H}from"protobufjs";import a from"path";import z from"fs";var g=["get","post","put","delete","patch"],h="(grpc.gateway.protoc_gen_openapiv2.options.openapiv2_operation).summary",d="(google.api.http)";function T(t){let r=a.normalize(t).split(a.sep).indexOf("protos");if(r===-1)throw new Error("\u672A\u627E\u5230 protos \u6839\u76EE\u5F55");return r}function I(t){let o=[t,a.join(t,"third_party/googleapis")],e=new D;return e.resolvePath=(r,p)=>{for(let n of o){let s=a.join(n,p);if(z.existsSync(s))return s}return p},e}function v(t,o=[]){if(!t.nested)return o;for(let e of Object.values(t.nested))e instanceof H&&o.push(e),v(e,o);return o}function b(t){let e=t.parsedOptions?.find(n=>n[d])?.[d];if(!e)return null;let r=g.find(n=>e[n]);if(!r)return null;let p=e[r];return p?{method:r,url:p,summary:t.options?.[h]??""}:null}function O(t){let o=I(t.root);o.loadSync(t.file);let e=v(o),r={};for(let p of e){let n=[];for(let s of Object.values(p.methods)){let f=b(s);f&&n.push({name:s.name,requestType:s.requestType,responseType:s.responseType,hasData:!!s.resolvedResponseType?.fields.data,...f})}n.length>0&&(r[p.name]=n)}return r}function x(t,o){let e={};for(let[r,p]of Object.entries(t)){let n=new Set,s=[];for(let i of p){n.add(i.requestType),i.hasData&&n.add(i.responseType);let u=[],w=i.method==="get"?"params: data":"data";i.summary&&u.push(`// ${i.summary}`);let A=i.hasData?`<${i.responseType}["data"]>`:"";u.push(`export function ${i.name}(data: ${i.requestType}) {`,`  return service${A}({`,`    url: "${i.url.replace("/api","")}",`,`    method: "${i.method}",`,`    ${w}`,"  })","}"),s.push(u.join(`
+`))}if(s.length===0)continue;let f=[...n].sort();e[r]=['import { service } from "../..";',"","import type {",`  ${f.join(`,
+  `)}`,`} from "${o}";`,"",s.join(`
 
 `)].join(`
-`)})}return e}function T(t,o){let e=o.replace(/\\/g,"/").replace(/^\.?\//,"").replace(/\.proto$/,"");return u.join(t,e)}function _(t){let o=j.resolve(process.cwd(),t.apiOutput);y.existsSync(o)||y.mkdirSync(o,{recursive:!0});let e=O(t.root,t.file),n=T(t.typeOutput,t.file),p=j.relative(t.apiOutput,n).replace(/\\/g,"/"),s=v(e,p);for(let i of s)for(let[a,r]of Object.entries(i))y.writeFileSync(`${o}/${a}.ts`,r,"utf8");console.log("\u2705 Generate Success")}import{execSync as H}from"child_process";import f from"fs";import c from"path";function S(t){let o=c.resolve(process.cwd(),t.typeOutput);f.existsSync(o)||f.mkdirSync(o,{recursive:!0});let e=c.resolve(process.cwd(),t.root),n=["protoc",`--ts_proto_out=${o}`,"--ts_proto_opt=onlyTypes=true","--ts_proto_opt=useOptionals=messages","--ts_proto_opt=esModuleInterop=true",`--proto_path=${e}`,`--proto_path=${c.join(e,"/third_party/googleapis")}`,c.join(e,t.file)],p={...process.env,PATH:`${c.join(process.cwd(),"node_modules",".bin")};${process.env.PATH}`};H(n.join(" "),{stdio:"inherit",env:p}),f.rmSync(c.join(o,"google"),{recursive:!0,force:!0}),f.rmSync(c.join(o,"common.ts"),{force:!0})}async function $(t){if(!R.existsSync(b.resolve(process.cwd(),t.root))){console.log(`proto \u9879\u76EE\u4E0D\u5B58\u5728(${t.root})`);return}S(t),_(t)}var l=new q;l.name("proto-gen").description("proto code generator").version("1.0.0");l.command("generate").option("--file, --file <path>").option("--root, --root <path>").option("--type-output, --typeOutput <path>").option("--api-output, --apiOutput <path>").action(t=>{if(t.file===void 0){console.log("proto file \u4E0D\u80FD\u4E3A\u7A7A, \u8BF7\u8F93\u5165 --file ./account.proto");return}if(t.root===void 0){console.log("proto \u6587\u4EF6\u7684\u6839\u8DEF\u5F84\u4E0D\u80FD\u4E3A\u7A7A, \u8BF7\u8F93\u5165 --root ../protos");return}t.typeOutput===void 0&&(t.typeOutput="src/protos/type"),t.apiOutput===void 0&&(t.apiOutput="src/protos/api"),$(t)});l.parse();
+`)}return e}function P(t){let e=a.normalize(t).split(a.sep),r=T(t);return e.slice(0,r+1).join(a.sep)}function S(t){let e=a.normalize(t.file).split(a.sep),r=T(t.file),p=e.slice(r+1).join(a.sep),n=a.join(t.typeOutput,p.replace(/\.proto$/,""));return a.relative(t.apiOutput,n).replace(/\\/g,"/")}function _(t){let o=j.resolve(process.cwd(),t.apiOutput);l.existsSync(o)||l.mkdirSync(o,{recursive:!0});let e=O(t),r=S(t),p=x(e,r);for(let[n,s]of Object.entries(p))l.writeFileSync(j.join(o,`${n}.ts`),s,"utf8");console.log("\u2705 Generate Success")}import{execSync as q}from"child_process";import m from"fs";import c from"path";function $(t){let o=c.resolve(process.cwd(),"node_modules/ts-proto/package.json");if(!m.existsSync(o))throw new Error("\u672A\u5B89\u88C5 ts-proto\uFF0C\u8BF7\u6267\u884C\uFF1Apnpm add -D ts-proto");let e=c.resolve(process.cwd(),t.typeOutput);m.existsSync(e)||m.mkdirSync(e,{recursive:!0});let r=["protoc",`--ts_proto_out=${e}`,"--ts_proto_opt=onlyTypes=true","--ts_proto_opt=useOptionals=optional","--ts_proto_opt=esModuleInterop=true",`--proto_path=${t.root}`,`--proto_path=${c.join(t.root,"third_party/googleapis")}`,c.resolve(t.file)];q(r.join(" "),{stdio:"inherit"}),m.rmSync(c.join(e,"google"),{recursive:!0,force:!0}),m.rmSync(c.join(e,"common.ts"),{force:!0})}function C(t){if(!E.existsSync(t.root)){console.log(`proto \u9879\u76EE\u4E0D\u5B58\u5728(${t.root})`);return}$(t),_(t)}var y=new M;y.name("proto-gen").description("proto code generator").version("1.0.4");y.command("generate").requiredOption("--file <path>","proto \u6587\u4EF6\u8DEF\u5F84").option("--api-path <path>","API \u4EE3\u7801\u8F93\u51FA\u76EE\u5F55").option("--type-path <path>","TypeScript \u7C7B\u578B\u8F93\u51FA\u76EE\u5F55").action(t=>{if(!k.existsSync(t.file)){console.log(`\u274C ${t.file} \u6587\u4EF6\u4E0D\u5B58\u5728\uFF0C\u8BF7\u68C0\u67E5\u6587\u4EF6\u8DEF\u5F84`);return}let o=R.parse(t.file).name,e=P(t.file),r={file:t.file,root:R.resolve(process.cwd(),e),typeOutput:t.typePath||"src/protos/type",apiOutput:t.apiPath?`${t.apiPath}${o?"/"+o:""}`:`src/protos/api${o?"/"+o:""}`};C(r)});y.parse();

package/package.json

@@ -1,12 +1,11 @@
 {
   "name": "ts-proto-client",
-  "version": "1.0.3",
+  "version": "1.0.5",
   "type": "module",
   "description": "",
   "scripts": {
     "dev": "tsx src/index.ts",
-    "build": "tsup src/index.ts --format esm --clean",
-    "release": "pnpm build && npm publish"
+    "build": "tsup src/index.ts --format esm --clean"
   },
   "bin": {
     "proto-gen": "./dist/index.js"
@@ -20,11 +19,11 @@
   "packageManager": "pnpm@10.14.0",
   "dependencies": {
     "commander": "^15.0.0",
-    "protobufjs": "^8.6.3",
-    "ts-proto": "^2.11.8"
+    "protobufjs": "^8.6.3"
   },
   "devDependencies": {
     "@types/node": "^25.9.3",
+    "ts-proto": "^2.11.8",
     "tsup": "^8.5.1",
     "tsx": "^4.22.4",
     "typescript": "^6.0.3"