vafast 0.5.5 → 0.5.7

package/README.md

@@ -8,21 +8,24 @@
 
 > Vafast 不只是框架，更是一种 **结构、清晰、可控** 的开发哲学。
 
-```typescript
-import { Server, createHandler } from 'vafast';
-
-const server = new Server([
-  { method: 'GET', path: '/', handler: createHandler(() => 'Hello Vafast!') }
-]);
+## 🚀 快速开始
 
-export default { port: 3000, fetch: server.fetch };
+```bash
+npx create-vafast-app
 ```
 
+按照提示输入项目名称，然后运行：
+
 ```bash
-# 启动服务器
-npx tsx index.ts
+cd my-vafast-app
+npm install
+npm run dev
 ```
 
+访问 [http://localhost:3000](http://localhost:3000) 即可看到 "Hello Vafast!"。
+
+> 💡 想要手动配置？查看 [安装](#-安装) 部分。
+
 ## ⚡ 性能
 
 | 框架 | RPS | 相对性能 |
@@ -37,10 +40,47 @@ npx tsx index.ts
 
 ## 📦 安装
 
+### 方式一：使用脚手架（推荐）
+
+使用官方脚手架快速创建项目：
+
+```bash
+npx create-vafast-app
+```
+
+### 方式二：手动安装
+
+在现有项目中安装：
+
 ```bash
 npm install vafast
 ```
 
+然后创建 `index.ts`：
+
+```typescript
+import { Server, defineRoute, defineRoutes, serve } from 'vafast';
+
+const routes = defineRoutes([
+  defineRoute({
+    method: 'GET',
+    path: '/',
+    handler: () => 'Hello Vafast!'
+  })
+]);
+
+const server = new Server(routes);
+serve({ fetch: server.fetch, port: 3000 }, (info) => {
+  console.log(`🚀 Server running at http://localhost:${info.port}`);
+});
+```
+
+运行：
+
+```bash
+npx tsx index.ts
+```
+
 ## 💡 设计哲学
 
 ### 结构即真相 — 无装饰器，无链式魔法
@@ -72,14 +112,25 @@ export default app;
 
 **Vafast 完整示例：**
 ```typescript
-import { Server, createHandler } from 'vafast';
-import type { Route } from 'vafast';
+import { Server, defineRoute, defineRoutes } from 'vafast';
 
-const routes: Route[] = [
-  { method: 'GET',  path: '/users',     handler: createHandler(() => 'list users') },
-  { method: 'POST', path: '/users',     handler: createHandler(({ body }) => body) },
-  { method: 'GET',  path: '/users/:id', handler: createHandler(({ params }) => `User ${params.id}`) },
-];
+const routes = defineRoutes([
+  defineRoute({
+    method: 'GET',
+    path: '/users',
+    handler: () => 'list users'
+  }),
+  defineRoute({
+    method: 'POST',
+    path: '/users',
+    handler: ({ body }) => body
+  }),
+  defineRoute({
+    method: 'GET',
+    path: '/users/:id',
+    handler: ({ params }) => `User ${params.id}`
+  }),
+]);
 
 const server = new Server(routes);
 export default { fetch: server.fetch };
@@ -110,22 +161,21 @@ export default app;
 
 **Vafast 完整示例：**
 ```typescript
-import { Server, createHandler, err } from 'vafast';
-import type { Route } from 'vafast';
+import { Server, defineRoute, defineRoutes, err } from 'vafast';
 
-const routes: Route[] = [
-  {
+const routes = defineRoutes([
+  defineRoute({
     method: 'GET',
     path: '/user',
-    handler: createHandler((ctx) => {
-      const name = ctx.query.name;
+    handler: ({ query }) => {
+      const name = query.name;
       if (!name) {
         throw err.badRequest('Missing name');  // ✨ 简洁！
       }
       return `Hello, ${name}`;
-    }),
-  },
-];
+    },
+  }),
+]);
 
 const server = new Server(routes);
 export default { fetch: server.fetch };
@@ -155,21 +205,29 @@ export default app;
 
 **Vafast 完整示例：**
 ```typescript
-import { Server, createHandler } from 'vafast';
-import type { Route, Middleware } from 'vafast';
+import { Server, defineRoute, defineRoutes, defineMiddleware } from 'vafast';
 
-const authMiddleware: Middleware = async (req, next) => {
+const authMiddleware = defineMiddleware(async (req, next) => {
   const token = req.headers.get('Authorization');
   if (!token) return new Response('Unauthorized', { status: 401 });
   return next();
-};
+});
 
-const routes: Route[] = [
+const routes = defineRoutes([
   // 无中间件
-  { method: 'GET', path: '/public', handler: createHandler(() => 'public') },
+  defineRoute({
+    method: 'GET',
+    path: '/public',
+    handler: () => 'public'
+  }),
   // 仅 auth
-  { method: 'GET', path: '/api/users', middleware: [authMiddleware], handler: createHandler(() => 'users') },
-];
+  defineRoute({
+    method: 'GET',
+    path: '/api/users',
+    middleware: [authMiddleware],
+    handler: () => 'users'
+  }),
+]);
 
 const server = new Server(routes);
 export default { fetch: server.fetch };
@@ -177,6 +235,69 @@ export default { fetch: server.fetch };
 
 **对比：Vafast 的中间件直接声明在路由上，一目了然。**
 
+### 扩展字段 — 声明式元数据，赋能业务逻辑
+
+**其他框架的问题：**
+- 路由定义和元数据分离，难以统一管理
+- 需要额外的配置文件或装饰器来存储 webhook、权限、计费等信息
+- 元数据查询需要遍历路由或维护独立映射表
+
+**Vafast 完整示例：**
+```typescript
+import { Server, defineRoute, defineRoutes, getRouteRegistry, defineMiddleware } from 'vafast';
+
+// 计费中间件（基于路由元数据）
+const billingMiddleware = defineMiddleware(async (req, next) => {
+  const route = getRouteRegistry().get(req.method, new URL(req.url).pathname);
+  
+  // 从路由元数据读取计费配置
+  if (route?.billing) {
+    const { price, currency } = route.billing;
+    // 执行计费逻辑
+    await chargeUser(req, price, currency);
+  }
+  
+  return next();
+});
+
+const routes = defineRoutes([
+  defineRoute({
+    method: 'POST',
+    path: '/ai/generate',
+    name: 'AI 生成',
+    description: '生成 AI 内容',
+    // ✨ 扩展字段：计费配置
+    billing: { price: 0.01, currency: 'USD' },
+    // ✨ 扩展字段：Webhook 事件
+    webhook: { eventKey: 'ai.generate', enabled: true },
+    // ✨ 扩展字段：权限要求
+    permission: 'ai.generate',
+    middleware: [billingMiddleware],
+    handler: async ({ body }) => {
+      const result = await generateAI(body.prompt);
+      return { result };
+    }
+  }),
+  defineRoute({
+    method: 'GET',
+    path: '/users',
+    // 免费 API，无需计费
+    handler: () => ({ users: [] })
+  }),
+]);
+
+const server = new Server(routes);
+
+// 查询所有需要计费的 API
+const paidRoutes = getRouteRegistry().filter('billing');
+// 查询所有 Webhook 事件
+const webhookRoutes = getRouteRegistry().filter('webhook');
+// 按权限筛选
+const aiRoutes = getRouteRegistry().filterBy(r => r.permission?.startsWith('ai.'));
+```
+
+**对比：Vafast 的扩展字段让路由定义成为单一数据源，元数据查询、中间件配置、业务逻辑都基于声明式配置。**
+
 ### 类型注入 — 跨文件不丢失
 
 **Hono 跨文件类型问题：**
@@ -205,33 +326,37 @@ export function setupRoutes(app: Hono) {
 export type AuthContext = { user: { id: string; role: string } };
 
 // -------- file: middleware/auth.ts --------
-import type { Middleware } from 'vafast';
+import { defineMiddleware } from 'vafast';
+import type { AuthContext } from '../types';
 
-export const authMiddleware: Middleware = async (req, next) => {
+// 使用 defineMiddleware 定义带类型的中间件
+export const authMiddleware = defineMiddleware<AuthContext>(async (req, next) => {
   const user = await verifyToken(req.headers.get('Authorization'));
-  (req as any).__locals = { user };
-  return next();
-};
+  return next({ user });  // 通过 next 传递上下文
+});
 
 // -------- file: handlers/profile.ts --------
-import { createHandlerWithExtra } from 'vafast';
-import type { AuthContext } from '../types';
+import { defineRoute } from 'vafast';
+import { authMiddleware } from '../middleware/auth';
 
-// 类型在 Handler 级别定义，任意文件都能用！
-export const getProfile = createHandlerWithExtra<AuthContext>((ctx) => {
-  const user = ctx.user;  // ✅ 类型完整: { id: string; role: string }
-  return { profile: user, isAdmin: user.role === 'admin' };
+// 类型在路由级别定义，任意文件都能用！
+export const getProfileRoute = defineRoute({
+  method: 'GET',
+  path: '/profile',
+  middleware: [authMiddleware],
+  handler: ({ user }) => {
+    // ✅ user 自动有类型: { id: string; role: string }
+    return { profile: user, isAdmin: user.role === 'admin' };
+  }
 });
 
 // -------- file: routes.ts --------
-import { Server } from 'vafast';
-import type { Route } from 'vafast';
-import { authMiddleware } from './middleware/auth';
-import { getProfile } from './handlers/profile';
+import { Server, defineRoutes } from 'vafast';
+import { getProfileRoute } from './handlers/profile';
 
-const routes: Route[] = [
-  { method: 'GET', path: '/profile', middleware: [authMiddleware], handler: getProfile },
-];
+const routes = defineRoutes([
+  getProfileRoute,
+]);
 
 const server = new Server(routes);
 export default { fetch: server.fetch };
@@ -243,34 +368,49 @@ export default { fetch: server.fetch };
 
 **Bun 环境完整示例：**
 ```typescript
-import { Server, createHandler } from 'vafast';
+import { Server, defineRoute, defineRoutes } from 'vafast';
 
-const server = new Server([
-  { method: 'GET', path: '/', handler: createHandler(() => 'Hello Bun!') }
+const routes = defineRoutes([
+  defineRoute({
+    method: 'GET',
+    path: '/',
+    handler: () => 'Hello Bun!'
+  })
 ]);
 
+const server = new Server(routes);
 export default { port: 3000, fetch: server.fetch };
 ```
 
 **Cloudflare Workers 完整示例：**
 ```typescript
-import { Server, createHandler } from 'vafast';
+import { Server, defineRoute, defineRoutes } from 'vafast';
 
-const server = new Server([
-  { method: 'GET', path: '/', handler: createHandler(() => 'Hello Workers!') }
+const routes = defineRoutes([
+  defineRoute({
+    method: 'GET',
+    path: '/',
+    handler: () => 'Hello Workers!'
+  })
 ]);
 
+const server = new Server(routes);
 export default { fetch: server.fetch };
 ```
 
 **Node.js 完整示例：**
 ```typescript
-import { Server, createHandler, serve } from 'vafast';
+import { Server, defineRoute, defineRoutes, serve } from 'vafast';
 
-const server = new Server([
-  { method: 'GET', path: '/', handler: createHandler(() => 'Hello Node!') }
+const routes = defineRoutes([
+  defineRoute({
+    method: 'GET',
+    path: '/',
+    handler: () => 'Hello Node!'
+  })
 ]);
 
+const server = new Server(routes);
 serve({ fetch: server.fetch, port: 3000 }, () => {
   console.log('Server running on http://localhost:3000');
 });
@@ -287,9 +427,13 @@ nest new my-app  # 生成 20+ 文件
 # ❌ Express - 需要配置和样板代码
 npm init && npm install express && mkdir routes controllers...
 
-# ✅ Vafast - 一个文件搞定
-echo "import { Server } from 'vafast';
-const server = new Server([{ method: 'GET', path: '/', handler: () => 'Hi' }]);
+# ✅ Vafast - 使用脚手架一键创建
+npx create-vafast-app
+
+# ✅ 或手动创建 - 一个文件搞定
+echo "import { Server, defineRoute, defineRoutes } from 'vafast';
+const routes = defineRoutes([defineRoute({ method: 'GET', path: '/', handler: () => 'Hi' })]);
+const server = new Server(routes);
 export default { fetch: server.fetch };" > index.ts && bun index.ts
 ```
 
@@ -304,6 +448,9 @@ export default { fetch: server.fetch };" > index.ts && bun index.ts
 | **类型推断** | 优秀 | 良好 | **优秀 (TypeBox)** |
 | **跨文件类型** | ⚠️ 链断裂丢失 | ❌ 实例绑定丢失 | **✅ Handler 级独立** |
 | **类型定义位置** | 链式调用上下文 | App 实例泛型 | **Handler 泛型参数** |
+| **扩展字段** | ❌ 不支持 | ❌ 不支持 | **✅ 任意扩展字段** |
+| **元数据查询** | ❌ 需遍历 | ❌ 需遍历 | **✅ RouteRegistry API** |
+| **业务集成** | ⚠️ 需额外配置 | ⚠️ 需额外配置 | **✅ 声明式集成** |
 | **性能 (RPS)** | ~118K | ~56K | **~101K** |
 | **学习曲线** | 中等 | 简单 | **简单** |
 | **API 风格** | 函数式链 | Express-like | **配置式** |
@@ -317,8 +464,11 @@ export default { fetch: server.fetch };" > index.ts && bun index.ts
 | **需要路由一览表** | **✅ Vafast** |
 | **需要精确中间件控制** | **✅ Vafast** |
 | **需要结构化错误** | **✅ Vafast** |
+| **需要扩展字段（webhook、计费、权限）** | **✅ Vafast** |
+| **需要元数据查询和筛选** | **✅ Vafast (RouteRegistry)** |
 | **大型项目多文件拆分** | **✅ Vafast (类型不丢失)** |
 | **团队协作类型安全** | **✅ Vafast** |
+| **API 网关/微服务场景** | **✅ Vafast (声明式配置)** |
 | 从 Express 迁移 | Hono (API 相似) |
 
 ## 🎯 核心功能
@@ -335,25 +485,31 @@ export default { fetch: server.fetch };" > index.ts && bun index.ts
 Vafast 提供简洁、对称的响应 API：
 
 ```typescript
-import { createHandler, json, err } from 'vafast';
-
-// ==================== 成功响应 ====================
-return user                    // 200 + JSON（自动转换）
-return json(user, 201)         // 201 Created
-return json(user, 200, {       // 自定义头部
-  'X-Request-Id': 'abc123'
+import { defineRoute, json, err } from 'vafast';
+
+defineRoute({
+  method: 'POST',
+  path: '/users',
+  handler: ({ body }) => {
+    // ==================== 成功响应 ====================
+    return body                    // 200 + JSON（自动转换）
+    return json(body, 201)         // 201 Created
+    return json(body, 200, {       // 自定义头部
+      'X-Request-Id': 'abc123'
+    })
+    return 'Hello'                 // 200 + text/plain
+    return new Response(...)       // 完全控制
+
+    // ==================== 错误响应 ====================
+    throw err.badRequest('参数错误')     // 400
+    throw err.unauthorized('请先登录')   // 401
+    throw err.forbidden('无权限')        // 403
+    throw err.notFound('用户不存在')     // 404
+    throw err.conflict('用户名已存在')   // 409
+    throw err.internal('服务器错误')     // 500
+    throw err('自定义错误', 422, 'CUSTOM_TYPE')  // 自定义
+  }
 })
-return 'Hello'                 // 200 + text/plain
-return new Response(...)       // 完全控制
-
-// ==================== 错误响应 ====================
-throw err.badRequest('参数错误')     // 400
-throw err.unauthorized('请先登录')   // 401
-throw err.forbidden('无权限')        // 403
-throw err.notFound('用户不存在')     // 404
-throw err.conflict('用户名已存在')   // 409
-throw err.internal('服务器错误')     // 500
-throw err('自定义错误', 422, 'CUSTOM_TYPE')  // 自定义
 ```
 
 **API 速查表：**
@@ -372,20 +528,20 @@ throw err('自定义错误', 422, 'CUSTOM_TYPE')  // 自定义
 ### 类型安全的路由
 
 ```typescript
-import { Server, defineRoutes, createHandler, Type } from 'vafast';
+import { Server, defineRoute, defineRoutes, Type } from 'vafast';
 
 const routes = defineRoutes([
-  {
+  defineRoute({
     method: 'POST',
     path: '/users',
-    handler: createHandler(
-      { body: Type.Object({ name: Type.String(), email: Type.String() }) },
-      ({ body }) => {
-        // body.name 和 body.email 自动类型推断
-        return { success: true, user: body };
-      }
-    )
-  }
+    schema: {
+      body: Type.Object({ name: Type.String(), email: Type.String() })
+    },
+    handler: ({ body }) => {
+      // body.name 和 body.email 自动类型推断
+      return { success: true, user: body };
+    }
+  })
 ]);
 
 const server = new Server(routes);
@@ -395,32 +551,34 @@ export default { port: 3000, fetch: server.fetch };
 ### 路径参数
 
 ```typescript
-{
+defineRoute({
   method: 'GET',
   path: '/users/:id',
-  handler: createHandler(
-    { params: Type.Object({ id: Type.String() }) },
-    ({ params }) => ({ userId: params.id })
-  )
-}
+  schema: {
+    params: Type.Object({ id: Type.String() })
+  },
+  handler: ({ params }) => ({ userId: params.id })
+})
 ```
 
 ### 中间件
 
 ```typescript
-const authMiddleware = async (req, next) => {
+import { defineMiddleware } from 'vafast';
+
+const authMiddleware = defineMiddleware(async (req, next) => {
   const token = req.headers.get('Authorization');
   if (!token) return new Response('Unauthorized', { status: 401 });
-  return next(req);
-};
+  return next();
+});
 
 const routes = defineRoutes([
-  {
+  defineRoute({
     method: 'GET',
     path: '/protected',
     middleware: [authMiddleware],
-    handler: createHandler(() => ({ secret: 'data' }))
-  }
+    handler: () => ({ secret: 'data' })
+  })
 ]);
 ```
 
@@ -428,22 +586,42 @@ const routes = defineRoutes([
 
 ```typescript
 const routes = defineRoutes([
-  {
+  defineRoute({
     path: '/api',
     middleware: [apiMiddleware],
     children: [
-      { method: 'GET', path: '/users', handler: getUsers },
-      { method: 'POST', path: '/users', handler: createUser },
-      {
+      defineRoute({
+        method: 'GET',
+        path: '/users',
+        handler: getUsers
+      }),
+      defineRoute({
+        method: 'POST',
+        path: '/users',
+        handler: createUser
+      }),
+      defineRoute({
         path: '/users/:id',
         children: [
-          { method: 'GET', path: '/', handler: getUser },
-          { method: 'PUT', path: '/', handler: updateUser },
-          { method: 'DELETE', path: '/', handler: deleteUser },
+          defineRoute({
+            method: 'GET',
+            path: '/',
+            handler: getUser
+          }),
+          defineRoute({
+            method: 'PUT',
+            path: '/',
+            handler: updateUser
+          }),
+          defineRoute({
+            method: 'DELETE',
+            path: '/',
+            handler: deleteUser
+          }),
         ]
-      }
+      })
     ]
-  }
+  })
 ]);
 ```
 
@@ -509,7 +687,7 @@ precompileSchemas([UserSchema, PostSchema, CommentSchema]);
 Vafast 内置 30+ 常用 format 验证器，**导入框架时自动注册**，对标 Zod 的内置验证：
 
 ```typescript
-import { Type, createHandler } from 'vafast';
+import { defineRoute, defineRoutes, Type } from 'vafast';
 
 // 直接使用内置 format，无需手动注册
 const UserSchema = Type.Object({
@@ -520,9 +698,16 @@ const UserSchema = Type.Object({
   createdAt: Type.String({ format: 'date-time' }),
 });
 
-const handler = createHandler({ body: UserSchema }, ({ body }) => {
-  return { success: true, user: body };
-});
+const routes = defineRoutes([
+  defineRoute({
+    method: 'POST',
+    path: '/users',
+    schema: { body: UserSchema },
+    handler: ({ body }) => {
+      return { success: true, user: body };
+    }
+  })
+]);
 ```
 
 **支持的 Format 列表：**
@@ -551,52 +736,113 @@ registerFormat('order-id', (v) => /^ORD-\d{8}$/.test(v));
 const isEmail = Patterns.EMAIL.test('test@example.com');
 ```
 
-### 路由注册表 (RouteRegistry)
+### 路由注册表 (RouteRegistry) — 声明式元数据，赋能业务逻辑
 
-Vafast 提供 `RouteRegistry` 用于路由元信息的收集和查询，适用于 API 文档生成、Webhook 事件注册、权限检查等场景：
+Vafast 的声明式路由支持**任意扩展字段**，让路由定义成为业务逻辑的单一数据源。适用于 API 文档生成、Webhook 事件注册、权限检查、**按 API 计费**等场景：
 
 ```typescript
-import { Server, createRouteRegistry } from 'vafast';
-import type { Route } from 'vafast';
+import { Server, defineRoute, defineRoutes, getRouteRegistry, defineMiddleware } from 'vafast';
+
+// 计费中间件：基于路由元数据自动计费
+const billingMiddleware = defineMiddleware(async (req, next) => {
+  const registry = getRouteRegistry();
+  const url = new URL(req.url);
+  const route = registry.get(req.method, url.pathname);
+  
+  if (route?.billing) {
+    const { price, currency, unit } = route.billing;
+    const userId = getUserId(req);
+    
+    // 执行计费逻辑
+    await chargeUser(userId, {
+      api: `${req.method} ${url.pathname}`,
+      price,
+      currency,
+      unit, // 'request' | 'token' | 'minute'
+    });
+  }
+  
+  return next();
+});
 
 // 定义带扩展字段的路由
-const routes: Route[] = [
-  {
+const routes = defineRoutes([
+  defineRoute({
     method: 'POST',
     path: '/auth/signIn',
+    name: '用户登录',
+    description: '用户通过邮箱密码登录',
     handler: signInHandler,
-    name: '用户登录',                    // 扩展字段
-    description: '用户通过邮箱密码登录',   // 扩展字段
-    webhook: { eventKey: 'auth.signIn' }, // 自定义扩展
-  },
-  {
+    // ✨ 扩展字段：Webhook 事件
+    webhook: { eventKey: 'auth.signIn', enabled: true },
+  }),
+  defineRoute({
+    method: 'POST',
+    path: '/ai/generate',
+    name: 'AI 生成',
+    description: '生成 AI 内容',
+    // ✨ 扩展字段：按请求计费
+    billing: { price: 0.01, currency: 'USD', unit: 'request' },
+    // ✨ 扩展字段：权限要求
+    permission: 'ai.generate',
+    middleware: [billingMiddleware],
+    handler: async ({ body }) => {
+      return await generateAI(body.prompt);
+    }
+  }),
+  defineRoute({
+    method: 'POST',
+    path: '/ai/chat',
+    name: 'AI 对话',
+    // ✨ 扩展字段：按 token 计费
+    billing: { price: 0.0001, currency: 'USD', unit: 'token' },
+    permission: 'ai.chat',
+    middleware: [billingMiddleware],
+    handler: async ({ body }) => {
+      return await chatAI(body.message);
+    }
+  }),
+  defineRoute({
     method: 'GET',
     path: '/users',
     handler: getUsersHandler,
-    permission: 'users.read',            // 自定义扩展
-  },
-];
+    permission: 'users.read',
+    // 免费 API，无需计费配置
+  }),
+]);
 
 const server = new Server(routes);
 
-// 创建路由注册表
-const registry = createRouteRegistry(server.getRoutesWithMeta());
+// Server 创建时自动设置全局注册表，直接使用即可
+const registry = getRouteRegistry();
 
-// 查询路由
-const route = registry.get('POST', '/auth/signIn');
-console.log(route?.name);  // '用户登录'
+// 查询路由元信息
+const route = registry.get('POST', '/ai/generate');
+console.log(route?.name);        // 'AI 生成'
+console.log(route?.billing);     // { price: 0.01, currency: 'USD', unit: 'request' }
+console.log(route?.permission);  // 'ai.generate'
+
+// 筛选有特定字段的路由
+const webhookRoutes = registry.filter('webhook');      // 所有 Webhook 事件
+const paidRoutes = registry.filter('billing');         // 所有付费 API
+const aiRoutes = registry.filterBy(r => r.permission?.startsWith('ai.')); // AI 相关 API
 
 // 按分类获取
 const authRoutes = registry.getByCategory('auth');
-
-// 筛选有特定字段的路由
-const webhookRoutes = registry.filter('webhook');
-const permissionRoutes = registry.filter('permission');
+const aiCategoryRoutes = registry.getByCategory('ai');
 
 // 获取所有分类
-const categories = registry.getCategories();  // ['auth', 'users']
+const categories = registry.getCategories();  // ['auth', 'ai', 'users']
 ```
 
+**扩展字段的优势：**
+
+1. **单一数据源**：路由定义包含所有元数据，无需额外配置文件
+2. **类型安全**：扩展字段在 TypeScript 中完全类型化
+3. **运行时查询**：通过 `RouteRegistry` API 动态查询和筛选
+4. **业务集成**：中间件可直接读取路由元数据，实现计费、权限、审计等功能
+5. **API 网关友好**：声明式配置完美适配网关场景
+
 **Registry 实例方法：**
 
 | 方法 | 说明 |
@@ -612,52 +858,61 @@ const categories = registry.getCategories();  // ['auth', 'users']
 | `map(callback)` | 映射所有路由 |
 | `size` | 路由数量 |
 
-**全局便捷函数：**
+**全局便捷函数（Server 创建后自动可用）：**
 
 ```typescript
 import {
-  getRoute,
-  getAllRoutes,
-  filterRoutes,
-  getRoutesByMethod,
+  getRouteRegistry,  // 获取全局注册表实例
+  getRoute,          // 快速查询单个路由
+  getAllRoutes,      // 获取所有路由
+  filterRoutes,      // 按字段筛选
+  getRoutesByMethod, // 按 HTTP 方法获取
 } from 'vafast'
 
-// 获取单个路由
-const route = getRoute('POST', '/users')
+// 方式一：使用全局注册表实例
+const registry = getRouteRegistry()
+const route = registry.get('POST', '/users')
 
-// 获取所有路由
+// 方式二：使用便捷函数（推荐，更简洁）
+const route = getRoute('POST', '/users')
 const allRoutes = getAllRoutes()
-
-// 按字段筛选
 const webhookRoutes = filterRoutes('webhook')
-
-// 按 HTTP 方法获取
 const getRoutes = getRoutesByMethod('GET')
 const postRoutes = getRoutesByMethod('POST')
 
-// 按路径前缀筛选（自己 filter）
+// 按路径前缀筛选
 const authRoutes = getAllRoutes().filter(r => r.path.startsWith('/auth'))
 ```
 
+> 💡 **提示**：Server 创建时会自动设置全局 RouteRegistry，无需手动创建。在任意文件中导入 `getRouteRegistry()` 即可访问。
+
 ### API Spec 生成
 
 Vafast 提供 `getApiSpec` 用于生成 API 规范，支持跨仓库类型同步和 AI 工具函数生成：
 
 ```typescript
-import { Server, defineRoutes, getApiSpec } from 'vafast';
+import { Server, defineRoute, defineRoutes, getApiSpec } from 'vafast';
 
 const routes = defineRoutes([
-  { method: 'GET', path: '/users', handler: getUsers },
-  { method: 'POST', path: '/users', handler: createUser },
+  defineRoute({
+    method: 'GET',
+    path: '/users',
+    handler: getUsers
+  }),
+  defineRoute({
+    method: 'POST',
+    path: '/users',
+    handler: createUser
+  }),
+  // 添加 API Spec 接口
+  defineRoute({
+    method: 'GET',
+    path: '/api-spec',
+    handler: getApiSpec  // 直接作为 handler
+  }),
 ]);
 
-// 添加 API Spec 接口
-const allRoutes = [
-  ...routes,
-  { method: 'GET', path: '/api-spec', handler: getApiSpec }  // 直接作为 handler
-];
-
-const server = new Server(allRoutes);
+const server = new Server(routes);
 ```
 
 **三种使用方式：**