router

一个轻量级的路由框架，支持链式调用、中间件、嵌套路由等功能。

快速开始

import { App } from '@kevisual/router';

const app = new App();
app.listen(4002);

app
  .route({ path: 'demo', key: '02' })
  .define(async (ctx) => {
    ctx.body = '02';
  })
  .addTo(app);

app
  .route({ path: 'demo', key: '03' })
  .define(async (ctx) => {
    ctx.body = '03';
  })
  .addTo(app);

核心概念

RouteContext 属性说明

在 route handler 中，你可以通过 ctx 访问以下属性：

属性	类型	说明
query	object	请求参数，会自动合并 payload
body	number | string | Object	响应内容
code	number	响应状态码，默认为 200
message	string	响应消息
state	any	状态数据，可在路由间传递
appId	string	应用标识
currentId	string	当前路由ID
currentPath	string	当前路由路径
currentKey	string	当前路由 key
currentRoute	Route	当前 Route 实例
progress	[string, string][]	路由执行路径记录
nextQuery	object	传递给下一个路由的参数
end	boolean	是否提前结束路由执行
app	QueryRouter	路由实例引用
error	any	错误信息
index	number	当前路由执行深度
needSerialize	boolean	是否需要序列化响应数据

上下文方法

方法	参数	说明
ctx.call(msg, ctx?)	{ path, key?, payload?, ... } | { id }	调用其他路由，返回完整 context
ctx.run(msg, ctx?)	{ path, key?, payload? }	调用其他路由，返回 { code, data, message }
ctx.forward(res)	{ code, data?, message? }	设置响应结果
ctx.throw(code?, message?, tips?)	-	抛出自定义错误

完整示例

import { App } from '@kevisual/router';
import z from 'zod';
const app = new App();
app.listen(4002);

// 基本路由
app
  .route({ path: 'user', key: 'info', id: 'user-info' })
  .define(async (ctx) => {
    // ctx.query 包含请求参数
    const { id } = ctx.query;
    // 使用 state 在路由间传递数据
    ctx.state.orderId = '12345';
    ctx.body = { id, name: '张三' };
    ctx.code = 200;
  })
  .addTo(app);

app
  .route({ path: 'order', key: 'pay', middleware: ['user-info'] })
  .define(async (ctx) => {
    // 可以获取前一个路由设置的 state
    const { orderId } = ctx.state;
    ctx.body = { orderId, status: 'paid' };
  })
  .addTo(app);

// 调用其他路由
app
  .route({ path: 'dashboard', key: 'stats' })
  .define(async (ctx) => {
    // 调用 user/info 路由
    const userRes = await ctx.run({ path: 'user', key: 'info', payload: { id: 1 } });
    // 调用 product/list 路由
    const productRes = await ctx.run({ path: 'product', key: 'list' });

    ctx.body = {
      user: userRes.data,
      products: productRes.data,
    };
  })
  .addTo(app);

// 使用 throw 抛出错误
app
  .route({ path: 'admin', key: 'delete' })
  .define(async (ctx) => {
    const { id } = ctx.query;
    if (!id) {
      ctx.throw(400, '缺少参数', 'id is required');
    }
    ctx.body = { success: true };
  })
  .addTo(app);

中间件

import { App, Route } from '@kevisual/router';

const app = new App();

// 定义中间件
app
  .route({
    id: 'auth-example',
    description: '权限校验中间件',
  })
  .define(async (ctx) => {
    const token = ctx.query.token;
    if (!token) {
      ctx.throw(401, '未登录', '需要 token');
    }
    // 验证通过，设置用户信息到 state
    ctx.state.tokenUser = { id: 1, name: '用户A' };
  })
  .addTo(app);

// 使用中间件（通过 id 引用）
app
  .route({ path: 'admin', key: 'panel', middleware: ['auth-example'] })
  .define(async (ctx) => {
    // 可以访问中间件设置的 state
    const { tokenUser } = ctx.state;
    ctx.body = { tokenUser };
  })
  .addTo(app);

一个丰富的router示例

import { App } from '@kevisual/router';
const app = new App();

app
  .router({
    path: 'dog',
    key: 'info',
    description: '获取狗的信息',
    metedata: {
      args: {
        owner: z.string().describe('狗主人姓名'),
        age: z.number().describe('狗的年龄'),
      },
    },
  })
  .define(async (ctx) => {
    const { owner, age } = ctx.query;
    ctx.body = {
      content: `这是一只${age}岁的狗，主人是${owner}`,
    };
  })
  .addTo(app);

注意事项

1. path 和 key 的组合是路由的唯一标识，同一个 path+key 只能添加一个路由，后添加的会覆盖之前的。

2. ctx.call vs ctx.run：

   • call 返回完整 context，包含所有属性
   • run 返回 { code, data, message } 格式，data 即 body

3. ctx.throw 会自动结束执行，抛出自定义错误。

4. payload 会自动合并到 query，调用 ctx.run({ path, key, payload }) 时，payload 会合并到 query。

5. nextQuery 用于传递给 nextRoute，在当前路由中设置 ctx.nextQuery，会在执行 nextRoute 时合并到 query。

6. 避免 nextRoute 循环调用，默认最大深度为 40 次，超过会返回 500 错误。

7. needSerialize 默认为 true，会自动对 body 进行 JSON 序列化和反序列化。

8. progress 记录执行路径，可用于调试和追踪路由调用链。

9. 中间件找不到会返回 404，错误信息中会包含找不到的中间件列表。