@vafast/cli 0.1.3 → 0.1.5

package/README.md

@@ -32,6 +32,18 @@ npx vafast sync --url http://localhost:3000 --endpoint /api/contract
 | `--url <url>` | 服务端地址（必填） | - |
 | `--out <path>` | 输出文件路径 | `src/api.generated.ts` |
 | `--endpoint <path>` | 契约接口路径 | `/__contract__` |
+| `--strip-prefix <prefix>` | 去掉路径前缀 | - |
+
+**示例：**
+
+```bash
+# 去掉 /restfulApi 前缀
+npx vafast sync \
+  --url http://localhost:9002 \
+  --endpoint /restfulApi/api-spec \
+  --out src/types/api/ones.generated.ts \
+  --strip-prefix /restfulApi
+```
 
 ## 工作流程
 
@@ -66,13 +78,23 @@ npx vafast sync --url http://localhost:3000
 ### 3. 使用生成的类型
 
 ```typescript
-import { eden } from '@vafast/api-client'
-import type { Api } from './api.generated'
+import { createClient } from '@vafast/api-client'
+import { createApiClient } from './api.generated'
 
-const api = eden<Api>('http://localhost:3000')
+// 创建底层客户端
+const client = createClient({
+  baseURL: 'http://localhost:3000',
+  timeout: 30000
+})
 
-// 类型安全的调用
+// 创建类型安全的 API 客户端
+const api = createApiClient(client)
+
+// 类型安全的调用（错误路径会被 TypeScript 检测）
 const { data, error } = await api.users.get({ page: 1 })
+
+// ❌ TypeScript 会报错
+// api.nonExistent.get()  // Error: Property 'nonExistent' does not exist
 ```
 
 ## 自动化
@@ -82,9 +104,12 @@ const { data, error } = await api.users.get({ page: 1 })
 ```json
 {
   "scripts": {
-    "sync": "vafast sync --url $API_URL",
-    "dev": "npm run sync && vite",
-    "build": "npm run sync && vite build"
+    "sync:auth": "vafast sync --url http://localhost:9003 --endpoint /authRestfulApi/api-spec --out src/types/api/auth.generated.ts --strip-prefix /authRestfulApi",
+    "sync:ones": "vafast sync --url http://localhost:9002 --endpoint /restfulApi/api-spec --out src/types/api/ones.generated.ts --strip-prefix /restfulApi",
+    "sync:billing": "vafast sync --url http://localhost:9004 --endpoint /billingRestfulApi/api-spec --out src/types/api/billing.generated.ts --strip-prefix /billingRestfulApi",
+    "sync:types": "npm run sync:auth && npm run sync:billing && npm run sync:ones",
+    "dev": "vite",
+    "build": "npm run sync:types && vite build"
   }
 }
 ```
@@ -113,28 +138,57 @@ const { data, error } = await api.users.get({ page: 1 })
 生成的类型：
 
 ```typescript
+import type { ApiResponse, RequestConfig, Client, EdenClient } from '@vafast/api-client'
+import { eden } from '@vafast/api-client'
+
+/** API 契约类型 */
 export type Api = {
   users: {
     get: {
       query: { page?: number }
-      return: unknown
+      return: any
     }
     post: {
       body: { name?: string }
-      return: unknown
+      return: any
     }
   }
 }
+
+/** API 客户端类型别名 */
+export type ApiClientType = EdenClient<Api>
+
+/**
+ * 创建类型安全的 API 客户端
+ */
+export function createApiClient(client: Client): EdenClient<Api> {
+  return eden<Api>(client)
+}
+```
+
+**使用方式：**
+
+```typescript
+import { createClient } from '@vafast/api-client'
+import { createApiClient } from './api.generated'
+
+const client = createClient({ baseURL: '/api', timeout: 30000 })
+const api = createApiClient(client)
+
+// 完整的类型安全
+const { data, error } = await api.users.post({ name: 'John' })
 ```
 
 ## 注意事项
 
-1. **返回类型**：当前契约不包含返回类型信息，生成的类型中返回值为 `unknown`。如需完整类型推断，建议使用 monorepo 共享路由定义。
+1. **返回类型**：如果后端未定义 `response` schema，生成的返回类型为 `any`（渐进式类型安全）。建议后端添加 `response` schema 获得完整类型检查。
 
 2. **服务器必须运行**：执行 `sync` 命令时，服务端必须在运行并暴露契约接口。
 
 3. **不要手动修改**：生成的文件会被覆盖，请勿手动修改。
 
+4. **类型安全**：生成的 `createApiClient` 返回 `EdenClient<Api>`，TypeScript 会检测错误的 API 路径。
+
 ## License
 
 MIT

package/dist/cli.js

@@ -1,9 +1,9 @@
-import { syncTypes } from "./sync-Bokzgg9Z.js";
+import { syncTypes } from "./sync-CS1-nDMt.js";
 import { cac } from "cac";
 
 //#region src/cli.ts
 const cli = cac("vafast");
-cli.command("sync", "从服务端同步 API 类型定义").option("--url <url>", "服务端地址（必填）").option("--out <path>", "输出文件路径", { default: "src/api.generated.ts" }).option("--endpoint <path>", "API Spec 接口路径", { default: "/api-spec" }).action(async (options) => {
+cli.command("sync", "从服务端同步 API 类型定义").option("--url <url>", "服务端地址（必填）").option("--out <path>", "输出文件路径", { default: "src/api.generated.ts" }).option("--endpoint <path>", "API Spec 接口路径", { default: "/api-spec" }).option("--strip-prefix <prefix>", "从路径中去掉的前缀（如 /billingRestfulApi）").action(async (options) => {
 	if (!options.url) {
 		console.error("❌ 请指定服务端地址：--url <url>");
 		process.exit(1);
@@ -11,7 +11,8 @@ cli.command("sync", "从服务端同步 API 类型定义").option("--url <url>",
 	await syncTypes({
 		url: options.url,
 		output: options.out,
-		endpoint: options.endpoint
+		endpoint: options.endpoint,
+		stripPrefix: options.stripPrefix
 	});
 });
 cli.help();

package/dist/commands/sync.d.ts

@@ -7,6 +7,7 @@ interface SyncOptions {
     url: string;
     output: string;
     endpoint: string;
+    stripPrefix?: string;
 }
 /**
  * 同步 API 类型

package/dist/index.js

@@ -1,3 +1,3 @@
-import { schemaToType, syncTypes } from "./sync-Bokzgg9Z.js";
+import { schemaToType, syncTypes } from "./sync-CS1-nDMt.js";
 
 export { schemaToType, syncTypes };

package/dist/{sync-Bokzgg9Z.js → sync-CS1-nDMt.js}

@@ -74,7 +74,7 @@ function objectToType(schema) {
 * 同步 API 类型
 */
 async function syncTypes(options) {
-	const { url, output, endpoint } = options;
+	const { url, output, endpoint, stripPrefix } = options;
 	console.log(`🔄 正在从 ${url}${endpoint} 获取契约...`);
 	const contractUrl = new URL(endpoint, url).toString();
 	let contract;
@@ -88,7 +88,8 @@ async function syncTypes(options) {
 		process.exit(1);
 	}
 	console.log(`✅ 获取到 ${contract.routes.length} 个路由`);
-	const typeContent = generateTypeDefinition(contract);
+	if (stripPrefix) console.log(`🔧 去掉路径前缀: ${stripPrefix}`);
+	const typeContent = generateTypeDefinition(contract, stripPrefix);
 	const outputDir = dirname(output);
 	mkdirSync(outputDir, { recursive: true });
 	writeFileSync(output, typeContent, "utf-8");
@@ -102,7 +103,7 @@ async function syncTypes(options) {
 /**
 * 生成类型定义文件内容
 */
-function generateTypeDefinition(contract) {
+function generateTypeDefinition(contract, stripPrefix) {
 	const lines = [];
 	lines.push("/**");
 	lines.push(" * 自动生成的 API 类型定义");
@@ -112,20 +113,97 @@ function generateTypeDefinition(contract) {
 	lines.push(" * ⚠️ 请勿手动修改此文件，使用 `vafast sync` 重新生成");
 	lines.push(" */");
 	lines.push("");
-	const routeTree = buildRouteTree(contract.routes);
+	lines.push("import type { ApiResponse, RequestConfig, Client, EdenClient } from '@vafast/api-client'");
+	lines.push("import { eden } from '@vafast/api-client'");
+	lines.push("");
+	const routeTree = buildRouteTree(contract.routes, stripPrefix);
+	lines.push("/** API 契约类型 */");
 	lines.push("export type Api = {");
 	lines.push(generateRouteTreeType(routeTree, 1));
 	lines.push("}");
 	lines.push("");
+	lines.push("/** API 客户端类型（提供完整的 IDE 智能提示） */");
+	lines.push("export interface ApiClient {");
+	lines.push(generateClientType(routeTree, 1));
+	lines.push("}");
+	lines.push("");
+	lines.push("/** API 客户端类型别名（基于 EdenClient 推断，提供完整类型检查） */");
+	lines.push("export type ApiClientType = EdenClient<Api>");
+	lines.push("");
+	lines.push("/**");
+	lines.push(" * 创建类型安全的 API 客户端");
+	lines.push(" * ");
+	lines.push(" * @example");
+	lines.push(" * ```typescript");
+	lines.push(" * import { createClient } from '@vafast/api-client'");
+	lines.push(" * import { createApiClient } from './api.generated'");
+	lines.push(" * ");
+	lines.push(" * const client = createClient('/api').use(authMiddleware)");
+	lines.push(" * const api = createApiClient(client)");
+	lines.push(" * ");
+	lines.push(" * // 完整的 IDE 智能提示和类型检查");
+	lines.push(" * const { data, error } = await api.users.find.post({ current: 1, pageSize: 10 })");
+	lines.push(" * // ❌ 错误路径会被 TypeScript 检测到");
+	lines.push(" * // api.nonExistent.post() // Error: Property 'nonExistent' does not exist");
+	lines.push(" * ```");
+	lines.push(" */");
+	lines.push("export function createApiClient(client: Client): EdenClient<Api> {");
+	lines.push("  return eden<Api>(client)");
+	lines.push("}");
+	lines.push("");
+	return lines.join("\n");
+}
+/**
+* 生成客户端接口类型（带完整方法签名，IDE 友好）
+*/
+function generateClientType(tree, indent) {
+	const lines = [];
+	const pad = "  ".repeat(indent);
+	for (const [key, node] of tree) {
+		const needsQuotes = /[^a-zA-Z0-9_$]/.test(key) || /^\d/.test(key);
+		const propName = needsQuotes ? `'${key}'` : key;
+		lines.push(`${pad}${propName}: {`);
+		for (const [method, route] of node.methods) {
+			if (route.description) lines.push(`${pad}  /** ${route.description} */`);
+			const methodSig = generateMethodSignature(route, method);
+			lines.push(`${pad}  ${method}: ${methodSig}`);
+		}
+		if (node.children.size > 0) {
+			const childContent = generateClientType(node.children, indent + 1);
+			if (childContent) lines.push(childContent);
+		}
+		lines.push(`${pad}}`);
+	}
 	return lines.join("\n");
 }
 /**
+* 生成方法签名（函数类型）
+*/
+function generateMethodSignature(route, method) {
+	const params = [];
+	if (route.schema?.body) {
+		const bodyType = schemaToType(route.schema.body);
+		params.push(`body: ${bodyType}`);
+	}
+	if (route.schema?.query) {
+		const queryType = schemaToType(route.schema.query);
+		params.push(`query?: ${queryType}`);
+	}
+	params.push("config?: RequestConfig");
+	const returnType = route.schema?.response ? schemaToType(route.schema.response) : "any";
+	return `(${params.join(", ")}) => Promise<ApiResponse<${returnType}>>`;
+}
+/**
 * 构建路由树
 */
-function buildRouteTree(routes) {
+function buildRouteTree(routes, stripPrefix) {
 	const root = /* @__PURE__ */ new Map();
+	const normalizedPrefix = stripPrefix ? "/" + stripPrefix.replace(/^\/+|\/+$/g, "") : void 0;
 	for (const route of routes) {
-		const segments = route.path.split("/").filter(Boolean);
+		let path = route.path;
+		if (normalizedPrefix && path.startsWith(normalizedPrefix)) path = path.slice(normalizedPrefix.length) || "/";
+		const segments = path.split("/").filter(Boolean);
+		if (segments.length === 0) continue;
 		let current = root;
 		for (let i = 0; i < segments.length; i++) {
 			const segment = segments[i];
@@ -183,7 +261,10 @@ function generateMethodType(route) {
 		const paramsType = schemaToType(route.schema.params);
 		parts.push(`params: ${paramsType}`);
 	}
-	parts.push("return: unknown");
+	if (route.schema?.response) {
+		const responseType = schemaToType(route.schema.response);
+		parts.push(`return: ${responseType}`);
+	} else parts.push("return: any");
 	if (parts.length === 1) return `{ ${parts[0]} }`;
 	return `{\n      ${parts.join("\n      ")}\n    }`;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vafast/cli",
-  "version": "0.1.3",
+  "version": "0.1.5",
   "description": "Vafast CLI - 类型同步和开发工具",
   "type": "module",
   "bin": {