vafast 0.2.4 → 0.3.2

package/README.md

@@ -6,6 +6,8 @@
 
 **超高性能的 TypeScript Web 框架，类型安全、轻量、快速。**
 
+> Vafast 不只是框架，更是一种 **结构、清晰、可控** 的开发哲学。
+
 ```typescript
 import { Server, createHandler } from 'vafast';
 
@@ -44,6 +46,291 @@ npm install vafast
 bun add vafast
 ```
 
+## 💡 设计哲学
+
+### 结构即真相 — 无装饰器，无链式魔法
+
+**Elysia 完整示例：**
+```typescript
+import { Elysia } from 'elysia';
+
+const app = new Elysia()
+  .get('/users', () => 'list users')
+  .post('/users', ({ body }) => body)
+  .get('/users/:id', ({ params }) => `User ${params.id}`)
+  .use(somePlugin);  // 插件作用域？要看文档
+
+export default app;
+```
+
+**Hono 完整示例：**
+```typescript
+import { Hono } from 'hono';
+
+const app = new Hono();
+app.get('/users', (c) => c.text('list users'));
+app.post('/users', async (c) => c.json(await c.req.json()));
+app.get('/users/:id', (c) => c.text(`User ${c.req.param('id')}`));
+
+export default app;
+```
+
+**Vafast 完整示例：**
+```typescript
+import { Server, createHandler } from 'vafast';
+import type { Route } 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 server = new Server(routes);
+export default { fetch: server.fetch };
+```
+
+**对比：Vafast 的路由是一个数组，一眼看清所有 API 端点。**
+
+### 错误即数据 — 不是混乱，是契约
+
+**Hono 完整示例：**
+```typescript
+import { Hono } from 'hono';
+import { HTTPException } from 'hono/http-exception';
+
+const app = new Hono();
+
+app.get('/user', (c) => {
+  const name = c.req.query('name');
+  if (!name) {
+    throw new HTTPException(400, { message: 'Missing name' });
+    // 响应格式自己定，没有标准
+  }
+  return c.text(`Hello, ${name}`);
+});
+
+export default app;
+```
+
+**Vafast 完整示例：**
+```typescript
+import { Server, VafastError, createHandler } from 'vafast';
+import type { Route } from 'vafast';
+
+const routes: Route[] = [
+  {
+    method: 'GET',
+    path: '/user',
+    handler: createHandler((ctx) => {
+      const name = ctx.query.name;
+      if (!name) {
+        throw new VafastError('Missing name', {
+          status: 400,
+          type: 'bad_request',
+          expose: true,  // 控制是否暴露给客户端
+        });
+      }
+      return `Hello, ${name}`;
+    }),
+  },
+];
+
+const server = new Server(routes);
+export default { fetch: server.fetch };
+// 错误响应: { type: 'bad_request', message: 'Missing name' }
+```
+
+**对比：VafastError 有统一的 `type` + `status` + `expose` 契约。**
+
+### 组合优于约定 — 显式优于隐式
+
+**Hono 完整示例：**
+```typescript
+import { Hono } from 'hono';
+import { cors } from 'hono/cors';
+
+const app = new Hono();
+
+// 中间件作用域通过路径匹配，容易出错
+app.use('/*', cors());           // 全局
+app.use('/api/*', authMiddleware);  // /api/* 但 /api 本身呢？
+
+app.get('/public', (c) => c.text('public'));
+app.get('/api/users', (c) => c.text('users'));
+
+export default app;
+```
+
+**Vafast 完整示例：**
+```typescript
+import { Server, createHandler } from 'vafast';
+import type { Route, Middleware } from 'vafast';
+
+const authMiddleware: Middleware = async (req, next) => {
+  const token = req.headers.get('Authorization');
+  if (!token) return new Response('Unauthorized', { status: 401 });
+  return next();
+};
+
+const routes: Route[] = [
+  // 无中间件
+  { method: 'GET', path: '/public', handler: createHandler(() => 'public') },
+  // 仅 auth
+  { method: 'GET', path: '/api/users', middleware: [authMiddleware], handler: createHandler(() => 'users') },
+];
+
+const server = new Server(routes);
+export default { fetch: server.fetch };
+```
+
+**对比：Vafast 的中间件直接声明在路由上，一目了然。**
+
+### 类型注入 — 跨文件不丢失
+
+**Hono 跨文件类型问题：**
+```typescript
+// -------- file: app.ts --------
+import { Hono } from 'hono';
+
+type Env = { Variables: { user: { id: string; role: string } } };
+const app = new Hono<Env>();
+
+// -------- file: routes.ts --------
+import { Hono } from 'hono';
+
+// 类型参数丢失！
+export function setupRoutes(app: Hono) {
+  app.get('/profile', (c) => {
+    const user = c.get('user');  // ❌ 类型是 unknown
+    return c.json(user);
+  });
+}
+```
+
+**Vafast 跨文件类型完整：**
+```typescript
+// -------- file: types.ts --------
+export type AuthContext = { user: { id: string; role: string } };
+
+// -------- file: middleware/auth.ts --------
+import type { Middleware } from 'vafast';
+
+export const authMiddleware: Middleware = async (req, next) => {
+  const user = await verifyToken(req.headers.get('Authorization'));
+  (req as any).__locals = { user };
+  return next();
+};
+
+// -------- file: handlers/profile.ts --------
+import { createHandlerWithExtra } from 'vafast';
+import type { AuthContext } from '../types';
+
+// 类型在 Handler 级别定义，任意文件都能用！
+export const getProfile = createHandlerWithExtra<AuthContext>((ctx) => {
+  const user = ctx.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';
+
+const routes: Route[] = [
+  { method: 'GET', path: '/profile', middleware: [authMiddleware], handler: getProfile },
+];
+
+const server = new Server(routes);
+export default { fetch: server.fetch };
+```
+
+**对比：Vafast 的类型跟着 Handler 走，而不是跟着 App 实例走。**
+
+### 边缘原生 — 一行代码，任意运行时
+
+**Bun 环境完整示例：**
+```typescript
+import { Server, createHandler } from 'vafast';
+
+const server = new Server([
+  { method: 'GET', path: '/', handler: createHandler(() => 'Hello Bun!') }
+]);
+
+export default { port: 3000, fetch: server.fetch };
+```
+
+**Cloudflare Workers 完整示例：**
+```typescript
+import { Server, createHandler } from 'vafast';
+
+const server = new Server([
+  { method: 'GET', path: '/', handler: createHandler(() => 'Hello Workers!') }
+]);
+
+export default { fetch: server.fetch };
+```
+
+**Node.js 完整示例：**
+```typescript
+import { Server, createHandler } from 'vafast';
+import { serve } from '@vafast/node-server';
+
+const server = new Server([
+  { method: 'GET', path: '/', handler: createHandler(() => 'Hello Node!') }
+]);
+
+serve({ fetch: server.fetch, port: 3000 }, () => {
+  console.log('Server running on http://localhost:3000');
+});
+```
+
+**对比：同一套代码，只需改导出方式即可切换运行时。**
+
+### 零样板 — 一个文件，即刻运行
+
+```bash
+# ❌ NestJS - 需要脚手架和大量文件
+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' }]);
+export default { fetch: server.fetch };" > index.ts && bun index.ts
+```
+
+### 与 Elysia/Hono 详细对比
+
+| 特性 | Elysia | Hono | **Vafast** |
+|------|--------|------|------------|
+| **路由风格** | 链式 builder | 链式 builder | **声明式数组** |
+| **路由一览性** | 分散在链中 | 分散在链中 | **一个数组看全部** |
+| **中间件绑定** | .use() 隐式 | .use() 路径匹配 | **显式声明在路由上** |
+| **错误类型** | error() 函数 | HTTPException | **VafastError 契约** |
+| **类型推断** | 优秀 | 良好 | **优秀 (TypeBox)** |
+| **跨文件类型** | ⚠️ 链断裂丢失 | ❌ 实例绑定丢失 | **✅ Handler 级独立** |
+| **类型定义位置** | 链式调用上下文 | App 实例泛型 | **Handler 泛型参数** |
+| **性能 (RPS)** | ~118K | ~56K | **~101K** |
+| **学习曲线** | 中等 | 简单 | **简单** |
+| **API 风格** | 函数式链 | Express-like | **配置式** |
+
+### 为什么选择 Vafast？
+
+| 如果你... | 选择 |
+|----------|------|
+| 追求极致性能 | Elysia (~118K) > **Vafast (~101K)** > Hono (~56K) |
+| 喜欢链式 API | Elysia 或 Hono |
+| **需要路由一览表** | **✅ Vafast** |
+| **需要精确中间件控制** | **✅ Vafast** |
+| **需要结构化错误** | **✅ Vafast** |
+| **大型项目多文件拆分** | **✅ Vafast (类型不丢失)** |
+| **团队协作类型安全** | **✅ Vafast** |
+| 从 Express 迁移 | Hono (API 相似) |
+
 ## 🎯 核心功能
 
 - ⚡ **JIT 编译验证器** - Schema 验证器编译缓存，避免重复编译
@@ -194,10 +481,18 @@ serve({ fetch: server.fetch, port: 3000 });
 
 ## 📚 文档
 
+### 入门
 - [快速开始](./docs/getting-started/quickstart.md)
-- [API 参考](./docs/api/)
 - [示例代码](./examples/)
 
+### 架构设计
+- [路由设计与网关架构](./docs/router-design.md) - 声明式路由的设计哲学、AI 时代能力、网关优势
+- [本地工具模式](./docs/local-tools-mode.md) - 声明式路由作为 AI Tools，无需 HTTP 服务
+
+### 参考
+- [服务器优化](./docs/server-optimization.md)
+- [认证系统](./docs/auth.md)
+
 ## 🤝 贡献
 
 欢迎贡献！请查看 [贡献指南](./CONTRIBUTING.md)。

package/dist/index.d.ts

@@ -9,4 +9,6 @@ export * from "./auth/token";
 export * from "./middleware/auth";
 export * from "./defineRoute";
 export * from "./types/index";
+export { serve } from "./serve";
+export type { ServeOptions, ServeResult, FetchHandler } from "./serve";
 export { Type } from "@sinclair/typebox";

package/dist/index.js

@@ -9,5 +9,7 @@ export * from "./auth/token";
 export * from "./middleware/auth";
 export * from "./defineRoute";
 export * from "./types/index";
+// 统一的 serve 函数（自动适配 Bun/Node.js）
+export { serve } from "./serve";
 // 重新导出 Type 以便用户使用
 export { Type } from "@sinclair/typebox";

package/dist/node-server/index.d.ts

@@ -0,0 +1,22 @@
+/**
+ * @vafast/node-server
+ * Node.js 适配器 - 为 Vafast 提供高性能 Node.js 运行时支持
+ *
+ * @example
+ * ```ts
+ * import { serve } from "@vafast/node-server";
+ * import { Server } from "vafast";
+ *
+ * const app = new Server([
+ *   { method: "GET", path: "/", handler: () => "Hello World" },
+ * ]);
+ *
+ * serve({ fetch: app.fetch, port: 3000 }, () => {
+ *   console.log("Server running on http://localhost:3000");
+ * });
+ * ```
+ */
+export { serve, createAdaptorServer } from "./serve";
+export type { ServeOptions, ServeResult, FetchHandler } from "./serve";
+export { createProxyRequest } from "./request";
+export { writeResponse, writeResponseSimple } from "./response";

package/dist/node-server/index.js

@@ -0,0 +1,21 @@
+/**
+ * @vafast/node-server
+ * Node.js 适配器 - 为 Vafast 提供高性能 Node.js 运行时支持
+ *
+ * @example
+ * ```ts
+ * import { serve } from "@vafast/node-server";
+ * import { Server } from "vafast";
+ *
+ * const app = new Server([
+ *   { method: "GET", path: "/", handler: () => "Hello World" },
+ * ]);
+ *
+ * serve({ fetch: app.fetch, port: 3000 }, () => {
+ *   console.log("Server running on http://localhost:3000");
+ * });
+ * ```
+ */
+export { serve, createAdaptorServer } from "./serve";
+export { createProxyRequest } from "./request";
+export { writeResponse, writeResponseSimple } from "./response";

package/dist/node-server/request.d.ts

@@ -0,0 +1,11 @@
+/**
+ * 优化的 Request 代理
+ * 延迟创建真实 Request，减少不必要的对象分配
+ */
+import type { IncomingMessage } from "node:http";
+/**
+ * 创建代理 Request
+ * @param incoming Node.js IncomingMessage
+ * @param defaultHost 默认主机名
+ */
+export declare function createProxyRequest(incoming: IncomingMessage, defaultHost: string): Request;

package/dist/node-server/request.js

@@ -0,0 +1,157 @@
+/**
+ * 优化的 Request 代理
+ * 延迟创建真实 Request，减少不必要的对象分配
+ */
+import { Readable } from "node:stream";
+// 内部 Symbol
+const requestCache = Symbol("requestCache");
+const incomingKey = Symbol("incoming");
+const urlKey = Symbol("url");
+const headersKey = Symbol("headers");
+/**
+ * 从 rawHeaders 高效解析 Headers
+ */
+function parseHeaders(rawHeaders) {
+    const headers = new Headers();
+    for (let i = 0; i < rawHeaders.length; i += 2) {
+        const key = rawHeaders[i];
+        const value = rawHeaders[i + 1];
+        // 跳过 HTTP/2 伪头 (以 : 开头)
+        if (key.charCodeAt(0) !== 58) {
+            headers.append(key, value);
+        }
+    }
+    return headers;
+}
+/**
+ * 将 Node.js ReadableStream 转换为 Web 标准 ReadableStream
+ * Node.js 和 Web 标准的 ReadableStream 在运行时兼容，但 TypeScript 类型不同
+ */
+function toWebStream(nodeStream) {
+    // Node.js ReadableStream 和 Web ReadableStream 在运行时是兼容的
+    // 这里使用类型断言是安全的，因为 Node.js >= 18 的 stream/web 完全实现了 WHATWG Streams 标准
+    return nodeStream;
+}
+/**
+ * 创建真实的 Request 对象
+ */
+function createRealRequest(proxy) {
+    const incoming = proxy[incomingKey];
+    const method = incoming.method || "GET";
+    const init = {
+        method,
+        headers: proxy[headersKey] || parseHeaders(incoming.rawHeaders),
+    };
+    // 只有非 GET/HEAD 请求才有 body
+    if (method !== "GET" && method !== "HEAD") {
+        // 使用 Node.js 原生流转换，避免收集 chunks
+        const nodeWebStream = Readable.toWeb(incoming);
+        init.body = toWebStream(nodeWebStream);
+        init.duplex = "half";
+    }
+    return new Request(proxy[urlKey], init);
+}
+/**
+ * Request 代理原型
+ * 使用 Object.defineProperty 定义属性以支持 this 绑定
+ */
+const requestPrototype = {};
+// 定义 method 属性
+Object.defineProperty(requestPrototype, "method", {
+    get() {
+        const self = this;
+        return self[incomingKey].method || "GET";
+    },
+    enumerable: true,
+});
+// 定义 url 属性
+Object.defineProperty(requestPrototype, "url", {
+    get() {
+        const self = this;
+        return self[urlKey];
+    },
+    enumerable: true,
+});
+// 定义 headers 属性（延迟解析）
+Object.defineProperty(requestPrototype, "headers", {
+    get() {
+        const self = this;
+        if (!self[headersKey]) {
+            self[headersKey] = parseHeaders(self[incomingKey].rawHeaders);
+        }
+        return self[headersKey];
+    },
+    enumerable: true,
+});
+// 定义 _getRequest 方法（获取或创建真实 Request）
+Object.defineProperty(requestPrototype, "_getRequest", {
+    value: function () {
+        const self = this;
+        if (!self[requestCache]) {
+            self[requestCache] = createRealRequest(self);
+        }
+        return self[requestCache];
+    },
+    enumerable: false,
+});
+// 代理需要访问真实 Request 的属性
+const proxyGetters = [
+    "body",
+    "bodyUsed",
+    "signal",
+    "cache",
+    "credentials",
+    "destination",
+    "integrity",
+    "mode",
+    "redirect",
+    "referrer",
+    "referrerPolicy",
+    "keepalive",
+];
+proxyGetters.forEach((key) => {
+    Object.defineProperty(requestPrototype, key, {
+        get() {
+            const self = this;
+            return self._getRequest()[key];
+        },
+        enumerable: true,
+    });
+});
+// 代理需要调用真实 Request 的方法
+const proxyMethods = [
+    "arrayBuffer",
+    "blob",
+    "clone",
+    "formData",
+    "json",
+    "text",
+];
+proxyMethods.forEach((key) => {
+    Object.defineProperty(requestPrototype, key, {
+        value: function () {
+            const self = this;
+            const req = self._getRequest();
+            return req[key].call(req);
+        },
+        enumerable: true,
+    });
+});
+// 设置原型链
+Object.setPrototypeOf(requestPrototype, Request.prototype);
+/**
+ * 创建代理 Request
+ * @param incoming Node.js IncomingMessage
+ * @param defaultHost 默认主机名
+ */
+export function createProxyRequest(incoming, defaultHost) {
+    const req = Object.create(requestPrototype);
+    req[incomingKey] = incoming;
+    // 构建 URL
+    const host = incoming.headers.host || defaultHost;
+    const protocol = incoming.socket.encrypted
+        ? "https"
+        : "http";
+    req[urlKey] = `${protocol}://${host}${incoming.url || "/"}`;
+    return req;
+}

package/dist/node-server/response.d.ts

@@ -0,0 +1,15 @@
+/**
+ * 优化的 Response 写入
+ * 流式写入，避免内存拷贝
+ */
+import type { ServerResponse } from "node:http";
+/**
+ * 将 Web Response 写入 Node.js ServerResponse
+ * 流式写入，零拷贝
+ */
+export declare function writeResponse(response: Response, outgoing: ServerResponse): Promise<void>;
+/**
+ * 简化版写入（用于已知小体积响应）
+ * 直接 arrayBuffer 转换，适用于确定的小响应
+ */
+export declare function writeResponseSimple(response: Response, outgoing: ServerResponse): Promise<void>;

package/dist/node-server/response.js

@@ -0,0 +1,98 @@
+/**
+ * 优化的 Response 写入
+ * 流式写入，避免内存拷贝
+ */
+/**
+ * 构建 Node.js 响应头
+ * 处理 set-cookie 多值情况
+ */
+function buildOutgoingHeaders(headers) {
+    const result = {};
+    const cookies = [];
+    headers.forEach((value, key) => {
+        if (key === "set-cookie") {
+            cookies.push(value);
+        }
+        else {
+            result[key] = value;
+        }
+    });
+    if (cookies.length > 0) {
+        result["set-cookie"] = cookies;
+    }
+    return result;
+}
+/**
+ * 流式写入 Response body 到 ServerResponse
+ * 支持背压处理，避免内存溢出
+ */
+async function writeBodyStream(body, outgoing) {
+    const reader = body.getReader();
+    try {
+        while (true) {
+            const { done, value } = await reader.read();
+            if (done) {
+                break;
+            }
+            // 背压处理：如果写入返回 false，等待 drain 事件
+            const canContinue = outgoing.write(value);
+            if (!canContinue) {
+                await new Promise((resolve) => {
+                    outgoing.once("drain", resolve);
+                });
+            }
+        }
+    }
+    finally {
+        reader.releaseLock();
+    }
+}
+/**
+ * 将 Web Response 写入 Node.js ServerResponse
+ * 流式写入，零拷贝
+ */
+export async function writeResponse(response, outgoing) {
+    // 设置状态码
+    outgoing.statusCode = response.status;
+    // 设置响应头
+    const headers = buildOutgoingHeaders(response.headers);
+    for (const [key, value] of Object.entries(headers)) {
+        outgoing.setHeader(key, value);
+    }
+    const body = response.body;
+    // 无 body 的情况
+    if (!body) {
+        outgoing.end();
+        return;
+    }
+    // 流式写入 body
+    try {
+        await writeBodyStream(body, outgoing);
+        outgoing.end();
+    }
+    catch (error) {
+        // 处理客户端提前断开等情况
+        if (!outgoing.destroyed) {
+            outgoing.destroy(error instanceof Error ? error : new Error(String(error)));
+        }
+    }
+}
+/**
+ * 简化版写入（用于已知小体积响应）
+ * 直接 arrayBuffer 转换，适用于确定的小响应
+ */
+export async function writeResponseSimple(response, outgoing) {
+    outgoing.statusCode = response.status;
+    const headers = buildOutgoingHeaders(response.headers);
+    for (const [key, value] of Object.entries(headers)) {
+        outgoing.setHeader(key, value);
+    }
+    const body = response.body;
+    if (!body) {
+        outgoing.end();
+        return;
+    }
+    // 对于小响应，直接读取全部内容
+    const buffer = await response.arrayBuffer();
+    outgoing.end(Buffer.from(buffer));
+}

package/dist/node-server/serve.d.ts

@@ -0,0 +1,52 @@
+/**
+ * Node.js 服务器适配器
+ * 提供类似 Bun.serve 的 API
+ */
+import { type Server as HttpServer } from "node:http";
+/** fetch 函数类型 */
+export type FetchHandler = (request: Request) => Response | Promise<Response>;
+/** serve 配置选项 */
+export interface ServeOptions {
+    /** fetch 处理函数 */
+    fetch: FetchHandler;
+    /** 端口号，默认 3000 */
+    port?: number;
+    /** 主机名，默认 0.0.0.0 */
+    hostname?: string;
+    /** 错误处理函数 */
+    onError?: (error: Error) => Response | Promise<Response>;
+}
+/** serve 返回的服务器信息 */
+export interface ServeResult {
+    /** Node.js HTTP Server 实例 */
+    server: HttpServer;
+    /** 服务器端口 */
+    port: number;
+    /** 服务器主机名 */
+    hostname: string;
+    /** 关闭服务器 */
+    stop: () => Promise<void>;
+}
+/**
+ * 启动 HTTP 服务器
+ *
+ * @example
+ * ```ts
+ * import { serve } from "@vafast/node-server";
+ * import { Server } from "vafast";
+ *
+ * const app = new Server([
+ *   { method: "GET", path: "/", handler: () => "Hello World" },
+ * ]);
+ *
+ * serve({ fetch: app.fetch, port: 3000 }, () => {
+ *   console.log("Server running on http://localhost:3000");
+ * });
+ * ```
+ */
+export declare function serve(options: ServeOptions, callback?: () => void): ServeResult;
+/**
+ * 创建适配器服务器（不自动启动）
+ * 用于需要更多控制的场景
+ */
+export declare function createAdaptorServer(fetch: FetchHandler, onError?: (error: Error) => Response | Promise<Response>): HttpServer;

package/dist/node-server/serve.js

@@ -0,0 +1,88 @@
+/**
+ * Node.js 服务器适配器
+ * 提供类似 Bun.serve 的 API
+ */
+import { createServer, } from "node:http";
+import { createProxyRequest } from "./request";
+import { writeResponse } from "./response";
+/**
+ * 创建请求处理函数
+ */
+function createRequestHandler(fetch, defaultHost, onError) {
+    return async (incoming, outgoing) => {
+        try {
+            // 创建代理 Request（延迟创建真实 Request）
+            const request = createProxyRequest(incoming, defaultHost);
+            // 调用 fetch handler
+            const response = await fetch(request);
+            // 流式写入 Response
+            await writeResponse(response, outgoing);
+        }
+        catch (error) {
+            // 错误处理
+            const err = error instanceof Error ? error : new Error(String(error));
+            if (onError) {
+                try {
+                    const errorResponse = await onError(err);
+                    await writeResponse(errorResponse, outgoing);
+                    return;
+                }
+                catch {
+                    // onError 也失败了，返回 500
+                }
+            }
+            // 默认错误响应
+            if (!outgoing.headersSent) {
+                outgoing.statusCode = 500;
+                outgoing.setHeader("Content-Type", "text/plain");
+                outgoing.end("Internal Server Error");
+            }
+        }
+    };
+}
+/**
+ * 启动 HTTP 服务器
+ *
+ * @example
+ * ```ts
+ * import { serve } from "@vafast/node-server";
+ * import { Server } from "vafast";
+ *
+ * const app = new Server([
+ *   { method: "GET", path: "/", handler: () => "Hello World" },
+ * ]);
+ *
+ * serve({ fetch: app.fetch, port: 3000 }, () => {
+ *   console.log("Server running on http://localhost:3000");
+ * });
+ * ```
+ */
+export function serve(options, callback) {
+    const { fetch, port = 3000, hostname = "0.0.0.0", onError } = options;
+    const defaultHost = `${hostname === "0.0.0.0" ? "localhost" : hostname}:${port}`;
+    const handler = createRequestHandler(fetch, defaultHost, onError);
+    const server = createServer(handler);
+    // 启动服务器
+    server.listen(port, hostname, callback);
+    return {
+        server,
+        port,
+        hostname,
+        stop: () => new Promise((resolve, reject) => {
+            server.close((err) => {
+                if (err)
+                    reject(err);
+                else
+                    resolve();
+            });
+        }),
+    };
+}
+/**
+ * 创建适配器服务器（不自动启动）
+ * 用于需要更多控制的场景
+ */
+export function createAdaptorServer(fetch, onError) {
+    const handler = createRequestHandler(fetch, "localhost", onError);
+    return createServer(handler);
+}

package/dist/serve.d.ts

@@ -0,0 +1,12 @@
+/**
+ * 统一的 serve 函数
+ * 使用 Node.js 原生 http 模块，兼容 Bun 和 Node.js
+ *
+ * 基准测试结果（Bun 环境）：
+ * - Bun.serve: 35,422 req/s
+ * - node:http: 38,075 req/s
+ *
+ * node:http 在 Bun 下性能甚至更好，无需使用 Bun API
+ */
+export { serve, createAdaptorServer } from "./node-server/serve";
+export type { ServeOptions, ServeResult, FetchHandler, } from "./node-server/serve";

package/dist/serve.js

@@ -0,0 +1,11 @@
+/**
+ * 统一的 serve 函数
+ * 使用 Node.js 原生 http 模块，兼容 Bun 和 Node.js
+ *
+ * 基准测试结果（Bun 环境）：
+ * - Bun.serve: 35,422 req/s
+ * - node:http: 38,075 req/s
+ *
+ * node:http 在 Bun 下性能甚至更好，无需使用 Bun API
+ */
+export { serve, createAdaptorServer } from "./node-server/serve";

package/dist/server/server.js

@@ -82,7 +82,8 @@ export class Server extends BaseServer {
         if (match) {
             req.params = match.params;
             // 优先使用预编译的处理链（仅当全局中间件未变化时）
-            if (match.compiled && this.globalMiddleware.length === this.compiledWithMiddlewareCount) {
+            if (match.compiled &&
+                this.globalMiddleware.length === this.compiledWithMiddlewareCount) {
                 return match.compiled(req);
             }
             // 回退：运行时组合中间件

package/dist/utils/parsers.js

@@ -180,9 +180,10 @@ export function parseCookiesFast(req) {
             const key = trimmed.substring(0, eqIndex).trim();
             const value = trimmed.substring(eqIndex + 1).trim();
             // 移除引号
-            result[key] = value.startsWith('"') && value.endsWith('"')
-                ? value.slice(1, -1)
-                : value;
+            result[key] =
+                value.startsWith('"') && value.endsWith('"')
+                    ? value.slice(1, -1)
+                    : value;
         }
     }
     return result;

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "vafast",
-  "version": "0.2.4",
-  "description": "专为Bun构建的极简结构化Web框架。Go风格，函数优先。",
+  "version": "0.3.2",
+  "description": "极简结构化Web框架，支持 Bun 和 Node.js。Go风格，函数优先。",
   "type": "module",
   "repository": {
     "type": "git",
@@ -23,6 +23,12 @@
       "require": "./dist/index.js",
       "types": "./dist/index.d.ts",
       "default": "./dist/index.js"
+    },
+    "./node-server": {
+      "import": "./dist/node-server/index.js",
+      "require": "./dist/node-server/index.js",
+      "types": "./dist/node-server/index.d.ts",
+      "default": "./dist/node-server/index.js"
     }
   },
   "types": "./dist/index.d.ts",
@@ -53,6 +59,7 @@
   },
   "keywords": [
     "bun",
+    "node",
     "framework",
     "minimal",
     "router",