关键概念

Vafast 是一个专为 Bun 运行时设计的高性能 Web 框架。了解这些核心概念将帮助你更好地使用 Vafast 构建应用。

🏗️ 架构概览

Vafast 采用模块化架构设计，主要包含以下核心组件：

Server: 主要的服务器类，负责处理请求和响应
Router: 路由匹配和分发系统
Middleware: 中间件系统，用于扩展功能
Types: 完整的类型定义系统
Utils: 工具函数和辅助类

🚀 Server 类

Server 类是 Vafast 的核心，继承自 BaseServer，提供了完整的 HTTP 服务器功能。

主要特性

路由管理: 自动扁平化嵌套路由
中间件支持: 全局和路由级中间件
错误处理: 内置的错误处理机制
性能优化: 智能路由排序和冲突检测

基本用法

typescript

import { Server, defineRoutes, createHandler } from 'vafast'

const routes = defineRoutes([
  {
    method: 'GET',
    path: '/',
    handler: createHandler(() => 'Hello World')
  }
])

const server = new Server(routes)
export default { fetch: server.fetch }

🛣️ 路由系统

Vafast 的路由系统基于配置对象，支持静态路径、动态参数和嵌套路由。

路由配置

typescript

interface Route {
  method: 'GET' | 'POST' | 'PUT' | 'DELETE' | 'PATCH' | 'OPTIONS' | 'HEAD'
  path: string
  handler: Handler
  middleware?: Middleware[]
  body?: any
  query?: any
  params?: any
  headers?: any
  cookies?: any
}

路径匹配

Vafast 使用智能路径匹配算法，支持：

静态路径: /users
动态参数: /users/:id
嵌套路由: 支持父子路由结构

路由优先级

路由按特异性自动排序：

静态路径（最高优先级）
动态参数（:param）
通配符（*）

🔧 中间件系统

中间件是 Vafast 中扩展功能的核心机制，支持全局和路由级中间件。

中间件类型

typescript

type Middleware = (
  req: Request, 
  next: () => Promise<Response>
) => Promise<Response>

中间件链

中间件按以下顺序执行：

全局中间件
路由级中间件
路由处理器

中间件示例

typescript

import { Server, defineRoutes, createHandler } from 'vafast'

// 日志中间件
const loggingMiddleware = async (req: Request, next: () => Promise<Response>) => {
  console.log(`${new Date().toISOString()} - ${req.method} ${req.url}`)
  const response = await next()
  console.log(`Response: ${response.status}`)
  return response
}

// 认证中间件
const authMiddleware = async (req: Request, next: () => Promise<Response>) => {
  const token = req.headers.get('authorization')
  if (!token) {
    return new Response('Unauthorized', { status: 401 })
  }
  return await next()
}

const routes = defineRoutes([
  {
    method: 'GET',
    path: '/protected',
    handler: createHandler(() => 'Protected content'),
    middleware: [authMiddleware]
  }
])

const server = new Server(routes)
server.use(loggingMiddleware) // 全局中间件

📝 类型系统

Vafast 提供完整的 TypeScript 支持，包括类型安全的处理器和验证器。

处理器类型

typescript

type Handler = (context: HandlerContext) => Response | Promise<Response>

interface HandlerContext {
  req: Request
  params?: Record<string, string>
  body?: any
  query?: any
  headers?: any
  cookies?: any
}

Schema 验证

Vafast 集成了 TypeBox 进行运行时类型验证：

typescript

import { Type } from '@sinclair/typebox'

const userSchema = Type.Object({
  name: Type.String({ minLength: 1 }),
  email: Type.String({ pattern: '^[^@]+@[^@]+\\.[^@]+$' }),
  age: Type.Optional(Type.Number({ minimum: 0 }))
})

const routes = defineRoutes([
  {
    method: 'POST',
    path: '/users',
    handler: createHandler(({ body }) => {
      // body 已经通过验证，类型安全
      return { success: true, user: body }
    }),
    body: userSchema
  }
])

🎯 路由处理器工厂

createHandler 函数用于创建类型安全的路由处理器，自动处理参数解构和类型推断。

基本用法

typescript

// 简单处理器
const simpleHandler = createHandler(() => 'Hello')

// 带参数的处理器
const paramHandler = createHandler(({ params }) => `ID: ${params.id}`)

// 带请求体的处理器
const bodyHandler = createHandler(async ({ req, body }) => {
  const data = await req.json()
  return { received: data, validated: body }
})

高级用法

typescript

// 带多个验证的处理器
const fullHandler = createHandler(
  ({ params, body, query, headers }) => {
    return {
      params,
      body,
      query,
      headers
    }
  },
  {
    body: userSchema,
    query: querySchema,
    params: paramsSchema
  }
)

🔄 请求处理流程

Vafast 的请求处理流程如下：

请求接收: 接收 HTTP 请求
路由匹配: 根据路径和方法匹配路由
中间件执行: 按顺序执行全局和路由中间件
参数解析: 解析路径参数、查询参数等
Schema 验证: 验证请求数据（如果配置了）
处理器执行: 执行路由处理器
响应返回: 返回 HTTP 响应

🚀 性能优化

Vafast 内置多项性能优化技术，无需额外配置即可获得高性能：

JIT 编译验证器

Schema 验证器在首次使用时编译并缓存，后续验证直接使用编译后的代码：

typescript

import { createValidator, validateFast, precompileSchemas } from 'vafast'
import { Type } from '@sinclair/typebox'

const UserSchema = Type.Object({
  name: Type.String(),
  age: Type.Number()
})

// 方式一：自动缓存（推荐）
const isValid = validateFast(UserSchema, data)

// 方式二：预编译验证器（最高性能）
const validateUser = createValidator(UserSchema)
const result = validateUser(data)

// 启动时预编译（避免首次请求开销）
precompileSchemas([UserSchema, PostSchema])

性能效果：10000 次验证仅需 ~5ms

中间件链预编译

路由注册时自动预编译完整的中间件链，运行时零开销：

typescript

const server = new Server(routes)

// 添加全局中间件后手动触发预编译
server.use(authMiddleware)
server.use(logMiddleware)
server.compile() // 预编译所有路由

// 每次请求直接执行编译好的处理链

性能效果：1000 次请求仅需 ~4ms，平均每次 0.004ms

快速请求解析

提供优化的解析函数，比标准方法快约 2x：

typescript

import { parseQueryFast, getCookie, getHeader } from 'vafast'

// 快速解析查询参数（简单场景）
const query = parseQueryFast(req)

// 获取单个 Cookie（避免解析全部）
const sessionId = getCookie(req, 'sessionId')

// 获取单个请求头
const token = getHeader(req, 'Authorization')

Radix Tree 路由

基于 Radix Tree 的高效路由匹配，时间复杂度 O(k)（k 为路径段数）：

路由预排序: 构造时按特异性排序
智能路径匹配: 静态路径 > 动态参数 > 通配符
冲突检测: 自动检测并警告路由冲突

📚 下一步

现在你已经了解了 Vafast 的核心概念，建议你：

查看路由指南学习如何定义复杂路由
阅读中间件系统了解如何扩展功能
探索 API 参考查看完整的 API 文档
查看示例代码获取更多实践示例

如果你有任何问题，欢迎在我们的 GitHub Issues 社区询问。

关键概念 ​

🏗️ 架构概览 ​

🚀 Server 类 ​

主要特性 ​

基本用法 ​

🛣️ 路由系统 ​

路由配置 ​

路径匹配 ​

路由优先级 ​

🔧 中间件系统 ​

中间件类型 ​

中间件链 ​

中间件示例 ​

📝 类型系统 ​

处理器类型 ​

Schema 验证 ​

🎯 路由处理器工厂 ​

基本用法 ​

高级用法 ​

🔄 请求处理流程 ​

🚀 性能优化 ​

JIT 编译验证器 ​

中间件链预编译 ​

快速请求解析 ​

Radix Tree 路由 ​

📚 下一步 ​

关键概念

🏗️ 架构概览

🚀 Server 类

主要特性

基本用法

🛣️ 路由系统

路由配置

路径匹配

路由优先级

🔧 中间件系统

中间件类型

中间件链

中间件示例

📝 类型系统

处理器类型

Schema 验证

🎯 路由处理器工厂

基本用法

高级用法

🔄 请求处理流程

🚀 性能优化

JIT 编译验证器

中间件链预编译

快速请求解析

Radix Tree 路由

📚 下一步