@kevisual/router 0.2.12 → 0.2.14

package/README.md

@@ -60,10 +60,10 @@ import { App } from '@kevisual/router/browser';
 
 | 方法                                | 参数                                      | 说明                                         |
 | ----------------------------------- | ----------------------------------------- | -------------------------------------------- |
-| `ctx.call(msg, ctx?)`               | `{ path, key?, payload?, ... } \| { rid }` | 调用其他路由，返回完整 context               |
-| `ctx.run(msg, ctx?)`                | `{ path, key?, payload? }`                | 调用其他路由，返回 `{ code, data, message }` |
+| `ctx.run(msg, ctx?)`                | `{ path, key?, payload?, ... } \| { rid }`          | 调用其他路由，返回 `{ code, data, message }` |
 | `ctx.forward(res)`                  | `{ code, data?, message? }`               | 设置响应结果                                 |
 | `ctx.throw(code?, message?, tips?)` | -                                         | 抛出自定义错误                               |
+| `ctx.safeParseAsync(data?, opts?)`  | `{ schema?, zodOptions?, stop? }`         | 校验路由参数，失败时返回 issues 或自动抛出 422 错误 |
 
 ## 完整示例
 
@@ -162,18 +162,26 @@ app
 
 ```ts
 import { App } from '@kevisual/router';
+import { z } from 'zod';
 const app = new App();
 
 app
-  .router({
+  .route({
     path: 'dog',
     key: 'info',
     description: '获取小狗的信息',
     metadata: {
+      // args: 定义请求参数的 zod schema，用于参数校验和类型推断
       args: {
         name: z.string().describe('小狗的姓名'),
         age: z.number().describe('小狗的年龄'),
       },
+      // returns: 定义响应数据的 zod schema，用于返回结果类型推断
+      returns: {
+        content: z.string().describe('小狗的信息描述'),
+      },
+      // check: true 会在路由执行前自动校验 args，失败时返回 422
+      check: true,
     },
   })
   .define(async (ctx) => {
@@ -185,20 +193,169 @@ app
   .addTo(app);
 ```
 
-## 注意事项
+### metadata 字段说明
 
-1. **path 和 key 的组合是路由的唯一标识**，同一个 path+key 只能添加一个路由，后添加的会覆盖之前的。
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| `args` | `Record<string, z.ZodTypeAny> \| z.ZodObject` | 请求参数的 zod schema，用于参数校验和类型推断 |
+| `returns` | `Record<string, z.ZodTypeAny> \| z.ZodObject` | 响应数据的 zod schema，用于返回值类型推断 |
+| `check` | `boolean` | 设为 `true` 时，路由执行前自动校验 `args`，校验失败返回 422 |
 
-2. `ctx.run` 返回 `{ code, data, message }` 格式，data 即 body
+### metadata.args 参数说明
 
-3. **ctx.throw 会自动结束执行**，抛出自定义错误。
+`args` 是一个 zod schema 对象，用于定义路由的请求参数结构。每个字段的 key 对应请求时传入的参数名，value 为 zod 的类型定义。
 
-4. **payload 会自动合并到 query**，调用 `ctx.run({ path, key, payload })` 时，payload 会合并到 query。
+| 参数名 | 类型 | 必填 | 说明 |
+|--------|------|------|------|
+| `name` | `z.string()` | 是 | 小狗的姓名，字符串类型 |
+| `age` | `z.number()` | 是 | 小狗的年龄，数字类型 |
+
+**调用示例：**
+```ts
+// 调用 dog/info 路由
+const res = await app.run({
+  path: 'dog',
+  key: 'info',
+  payload: { name: '旺财', age: 3 }
+});
+// res.data.content => "这是一只3岁的小狗，名字是旺财"
+```
+
+### metadata.returns 返回值说明
+
+`returns` 是一个 zod schema 对象，用于定义路由响应的数据结构。主要用于：
+1. 类型安全：配合 `runAction` 方法进行返回值的类型推断
+2. 文档化：自动生成 API 文档
+
+| 返回字段 | 类型 | 说明 |
+|----------|------|------|
+| `content` | `z.string()` | 小狗的信息描述，字符串类型 |
+
+**返回结构：**
+```ts
+{
+  code: 200,                    // HTTP 状态码
+  data: {                      // 返回的数据，类型由 returns schema 推断
+    content: "这是一只3岁的小狗，名字是旺财"
+  },
+  message: "success"            // 响应消息
+}
+```
+
+### 配合 runAction 使用
+
+当你使用 `runAction` 方法调用路由时，`args` 和 `returns` 会参与类型推断：
+
+```ts
+import { App } from '@kevisual/router';
+import { z } from 'zod';
+
+const app = new App();
+
+// 定义 API 结构
+const dogAPI = {
+  path: 'dog',
+  key: 'info',
+  metadata: {
+    args: {
+      name: z.string(),
+      age: z.number(),
+    },
+    returns: {
+      content: z.string(),
+    }
+  }
+} as const;
+
+// runAction 会根据 metadata.args 推断 payload 类型
+// 根据 metadata.returns 推断返回数据的类型
+const res = await app.runAction(dogAPI, { name: '旺财', age: 3 });
+// res.data.content 会被正确推断为 string 类型
+```
+
+## 参数校验
+
+框架集成了 [Zod](https://zod.dev/) v4 进行参数校验，提供两种使用方式。
 
-5. **nextQuery 用于传递给 nextRoute**，在当前路由中设置 `ctx.nextQuery`，会在执行 nextRoute 时合并到 query。
+### 自动校验（metadata.check）
 
-6. **避免 nextRoute 循环调用**，默认最大深度为 40 次，超过会返回 500 错误。
+在路由定义中设置 `metadata.check: true`，框架会在路由函数执行前自动校验 `metadata.args` 中定义的参数。校验失败时自动返回 HTTP 422，`body` 为 zod issues 数组。
 
-7. **needSerialize 默认为 true**，会自动对 body 进行 JSON 序列化和反序列化。
+```ts
+app
+  .route({
+    path: 'user',
+    key: 'create',
+    metadata: {
+      args: {
+        name: z.string(),
+        age: z.number(),
+      },
+      check: true, // 开启自动校验
+    },
+  })
+  .define(async (ctx) => {
+    // 走到这里时参数已通过校验
+    const { name, age } = ctx.query;
+    ctx.body = { name, age };
+  })
+  .addTo(app);
+
+// 校验失败时响应示例：
+// { code: 422, message: 'Validation Error:...', data: [{ code: 'invalid_type', path: ['age'], message: '...' }] }
+```
+
+### 手动校验（ctx.safeParseAsync）
+
+在路由函数内部手动调用 `ctx.safeParseAsync()` 进行校验，可以更灵活地处理校验结果。
+
+```ts
+app
+  .route({
+    path: 'user',
+    key: 'update',
+    metadata: {
+      args: {
+        id: z.string(),
+        name: z.string().optional(),
+      },
+    },
+  })
+  .define(async (ctx) => {
+    // stop: true（默认）时校验失败会自动 throw 422
+    // stop: false 时返回结果由你自行处理
+    const res = await ctx.safeParseAsync(null, { stop: false });
+    if (!res.success) {
+      // res.error.issues 为 zod v4 的错误列表（注意：zod v4 用 issues，不再是 errors）
+      const { fieldErrors } = res.error.flatten();
+      ctx.code = 422;
+      ctx.body = { fieldErrors };
+      return;
+    }
+    ctx.body = { ok: true };
+  })
+  .addTo(app);
+```
+
+**`ctx.safeParseAsync` 参数说明：**
+
+| 参数 | 类型 | 默认值 | 说明 |
+|------|------|--------|------|
+| `data` | `any` | `null` | 额外合并到校验数据中（会与 `ctx.query` 合并） |
+| `opts.schema` | `Record<string, z.ZodTypeAny>` | - | 额外追加的 zod schema 字段 |
+| `opts.zodOptions` | `any` | - | 透传给 zod `safeParseAsync` 的选项 |
+| `opts.stop` | `boolean` | `true` | 校验失败时是否自动 throw 422，`false` 时由调用方自行处理 |
+
+> **注意：** 项目使用 Zod v4，错误信息字段为 `res.error.issues`
+
+## 注意事项
+
+1. **path 和 key 的组合是路由的唯一标识**，同一个 path+key 只能添加一个路由，后添加的会覆盖之前的。
+
+2. `ctx.run` 返回 `{ code, data, message }` 格式，data 即 body。
+
+3. **ctx.throw 会自动结束执行**，抛出自定义错误。支持传入 `data` 字段，错误时 `ctx.body` 会被设为该值。
+
+4. **payload 会自动合并到 query**，调用 `ctx.run({ path, key, payload })` 时，payload 会合并到 query。
 
-8. **progress 记录执行路径**，可用于调试和追踪路由调用链。
+5. **校验失败响应**：`metadata.check: true` 或 `ctx.safeParseAsync` 默认 stop 模式下，校验失败返回 `code: 422`，`body` 为 zod issues 数组，可直接用于前端表单错误展示。

package/package.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://json.schemastore.org/package",
   "name": "@kevisual/router",
-  "version": "0.2.12",
+  "version": "0.2.14",
   "description": "",
   "type": "module",
   "main": "./dist/router.js",
@@ -27,19 +27,19 @@
     "@kevisual/dts": "^0.0.4",
     "@kevisual/js-filter": "^0.0.6",
     "@kevisual/local-proxy": "^0.0.8",
-    "@kevisual/query": "^0.0.56",
+    "@kevisual/query": "^0.0.58",
     "@kevisual/remote-app": "^0.0.7",
     "@kevisual/use-config": "^1.0.30",
-    "@opencode-ai/plugin": "^1.14.30",
-    "@types/bun": "^1.3.13",
+    "@opencode-ai/plugin": "^1.15.13",
+    "@types/bun": "^1.3.14",
     "@types/crypto-js": "^4.2.2",
-    "@types/node": "^25.6.0",
+    "@types/node": "^25.9.1",
     "@types/send": "^1.2.1",
     "@types/ws": "^8.18.1",
     "@types/xml2js": "^0.4.14",
-    "commander": "^14.0.3",
+    "commander": "^15.0.0",
     "crypto-js": "^4.2.0",
-    "es-toolkit": "^1.46.1",
+    "es-toolkit": "^1.47.0",
     "eventemitter3": "^5.0.4",
     "fast-glob": "^3.3.3",
     "nanoid": "^5.1.11",
@@ -54,7 +54,7 @@
     "url": "git+https://github.com/abearxiong/kevisual-router.git"
   },
   "dependencies": {
-    "zod": "^4.4.1"
+    "zod": "^4.4.3"
   },
   "publishConfig": {
     "access": "public"

package/src/result/error.ts

@@ -1,6 +1,7 @@
 export type CustomErrorOptions = {
   cause?: Error | string;
   code?: number;
+  data?: any;
   message?: string;
 }
 /** 自定义错误 */
@@ -19,6 +20,9 @@ export class CustomError extends Error {
     this.name = 'RouterError';
     let codeNum = opts?.code || (typeof code === 'number' ? code : undefined);
     this.code = codeNum ?? 500;
+    if (opts.data) {
+      this.data = opts.data;
+    }
     this.message = message!;
     // 这一步可不写，默认会保存堆栈追踪信息到自定义错误构造函数之前，
     // 而如果写成 `Error.captureStackTrace(this)` 则自定义错误的构造函数也会被保存到堆栈追踪信息

package/src/route.ts

@@ -1,7 +1,7 @@
 import { CustomError, throwError } from './result/error.ts';
 import { pick } from './utils/pick.ts';
 import { listenProcess, MockProcess } from './utils/listen-process.ts';
-import { z } from 'zod';
+import { z, ZodError } from 'zod';
 import { hashIdMd5Sync, randomId } from './utils/random.ts';
 import * as schema from './validator/schema.ts';
 import type { RunActionPayload, RunActionReturns } from './types/index.ts'
@@ -57,6 +57,11 @@ export type RouteContext<T = { code?: number }, U extends SimpleObject = {}, S =
    * 进度
    */
   progress?: [string, string][];
+  safeParseAsync?: (data?: any, opts?: {
+    schema?: { [key: string]: z.ZodTypeAny },
+    zodOptions?: any,
+    stop?: boolean, // 如果验证失败，是否停止后续的 route 执行，默认 true
+  }) => Promise<{ success: boolean; data?: any; error?: any }>;
   // onlyForNextRoute will be clear after next route
   nextQuery?: { [key: string]: any };
   // end
@@ -93,7 +98,7 @@ export type RouteOpts<U = {}, T = SimpleObject> = {
   run?: Run<U>;
   nextRoute?: NextRoute; // route to run after this route
   description?: string;
-  metadata?: T;
+  metadata?: Metadata<T>;
   middleware?: RouteMiddleware[]; // middleware
   type?: 'route' | 'middleware' | 'compound'; // compound表示这个 route 作为一个聚合体，没有实际的 run，而是一个 router 的聚合列表
   isDebug?: boolean;
@@ -129,12 +134,16 @@ export const createSkill = <T = SimpleObject>(skill: Skill<T>): Skill<T> => {
 }
 
 export type RouteInfo = Pick<Route, (typeof pickValue)[number]>;
-
+export type Metadata<T = SimpleObject> = {
+  args?: Record<string, z.ZodTypeAny> | z.ZodObject<any>;
+  returns?: Record<string, z.ZodTypeAny> | z.ZodObject<any>;
+  check?: boolean;
+} & T;
 /**
  * @M 是 route的 metadate的类型，默认是 SimpleObject
  * @U 是 RouteContext 里 state的类型
  */
-export class Route<M extends SimpleObject = SimpleObject, U extends SimpleObject = SimpleObject> implements throwError {
+export class Route<M extends Metadata = Metadata, U extends SimpleObject = SimpleObject> implements throwError {
   /**
    * 一级路径
    */
@@ -315,6 +324,21 @@ export class QueryRouter<T extends SimpleObject = SimpleObject> implements throw
   removeById(uniqueId: string) {
     this.routes = this.routes.filter((r) => r.rid !== uniqueId);
   }
+  safeParseAsyncRoute(data: any, opts: { route: RouteInfo, schema?: { [key: string]: z.ZodTypeAny }, zodOptions?: any }): Promise<{ success: boolean; data?: any; error?: any }> {
+    const route = opts.route;
+    const argZod = route.metadata?.args as Record<string, z.ZodTypeAny>;
+    const schemaZod = opts.schema || {};
+    const zodOptions = opts.zodOptions;
+    const keys = Object.keys(argZod || {});
+    if (argZod && keys.length > 0) {
+      const mgZod = z.object({
+        ...argZod,
+        ...schemaZod
+      });
+      return mgZod.safeParseAsync(data, zodOptions);
+    }
+    return Promise.resolve({ success: true, data });
+  }
   /**
    * 执行route
    * @param path
@@ -332,6 +356,21 @@ export class QueryRouter<T extends SimpleObject = SimpleObject> implements throw
     ctx.currentRoute = route;
     ctx.index = (ctx.index || 0) + 1;
     const progress = [path, key] as [string, string];
+    ctx.safeParseAsync = async (data?: any, opts?: { schema?: { [key: string]: z.ZodTypeAny }, zodOptions?: any, stop?: boolean }) => {
+      const stop = opts?.stop ?? true;
+      const _query = { ...ctx.query, ...data };
+      const res = await this.safeParseAsyncRoute(_query, { route: route, ...opts });
+      if (!res.success && stop) {
+        const issues = res.error.issues;
+        ctx.throw({
+          // Unprocessable Entity
+          code: 422,
+          data: issues,
+          message: 'Validation Error:' + JSON.stringify(issues, null, 2),
+        })
+      }
+      return res;
+    }
     if (ctx.progress) {
       ctx.progress.push(progress);
     } else {
@@ -406,7 +445,7 @@ export class QueryRouter<T extends SimpleObject = SimpleObject> implements throw
             if (e instanceof CustomError || e?.code) {
               ctx.code = e.code;
               ctx.message = e.message;
-              ctx.body = null;
+              ctx.body = e.data;
             } else {
               console.error(`[router error] fn:${route.path}-${route.key}:${route.rid}`);
               console.error(`[router error] middleware:${middleware.path}-${middleware.key}:${middleware.rid}`);
@@ -427,6 +466,9 @@ export class QueryRouter<T extends SimpleObject = SimpleObject> implements throw
     if (route) {
       if (route.run) {
         try {
+          if (route.metadata?.check) {
+            await ctx.safeParseAsync(null, { stop: true });
+          }
           await route.run(ctx as Required<RouteContext<T>>);
         } catch (e) {
           if (route?.isDebug) {
@@ -437,13 +479,14 @@ export class QueryRouter<T extends SimpleObject = SimpleObject> implements throw
           if (e instanceof CustomError || e?.code) {
             ctx.code = e.code;
             ctx.message = e.message;
+            ctx.body = e.data;
           } else {
             console.error(`[router error] fn:${route.path}-${route.key}:${route.rid}`);
             console.error(`[router error] error`, e);
             ctx.code = 500;
             ctx.message = 'Internal Server Error';
+            ctx.body = null;
           }
-          ctx.body = null;
           return ctx;
         }
         if (ctx.end) {

package/src/test/route-ts.ts

@@ -1,15 +1,29 @@
 import { QueryRouterServer } from "@/route.ts";
 import z from "zod";
+import { tr } from "zod/v4/locales";
 
 const router = new QueryRouterServer()
 
 router.route({
+  path: 'test',
   metadata: {
     args: {
       a: z.string(),
-    }
+    },
+    check: true,
   },
 }).define(async (ctx) => {
-  const argA: string = ctx.args.a;
+  const argZod = ctx.currentRoute.metadata.args as Record<string, z.ZodTypeAny>;
+  const mgZod = z.object(argZod);
+  // console.log('argZod', argZod);
+  // const argA: string = ctx.args.a;
+  // const res = await ctx.safeParseAsync(null, { stop: true });
+  // // console.log('argA', argA);
+  // if (!res.success) {
+  //   console.log('res===', res.error.issues);
+  // }
   ctx.body = '1';
-}).addTo(router);
+}).addTo(router);
+
+const res = await router.run({ path: 'test', payload: { a: 'abc' } });
+console.log('res', res);