Bun-Crane 一个基于 Bun 运行时的轻量级 Web 框架

原创已于 2025-11-26 23:17:09 修改 · 置顶 · 666 阅读

14 ·

CC 4.0 BY-SA版权

文章标签：

#后端

于 2025-11-26 17:39:43 首次发布

Bun-Crane 框架分析文档

1. 代码功能概述

Bun-Crane 是一个基于 Bun 运行时的轻量级 Web 框架，提供了简洁的 API 来构建 HTTP 服务器和 WebSocket 服务。它支持中间件机制、Next.js 风格的文件系统路由以及多种路由定义方式，旨在为开发者提供一个高效、易用的 Web 开发体验。

主要功能特性

HTTP 服务器：基于 Bun 的内置 HTTP 服务器，提供高性能的请求处理
WebSocket 支持：原生支持 WebSocket 连接，方便构建实时应用
中间件机制：支持全局和路径级别的中间件，用于处理请求前/后的逻辑
灵活的路由定义：支持多种路由定义方式
- 编程式路由（get, post, put 等方法）
- 文件系统路由（Next.js 风格）
- 方法级路由处理
TypeScript 支持：完全用 TypeScript 编写，提供类型安全

2. 核心逻辑说明

2.1 框架架构

Bun-Crane 采用了分层架构设计，主要包含以下核心组件：

App 类：框架的核心入口，负责管理路由、中间件和服务器配置
EventContext 类：请求上下文，封装了请求信息、参数、状态等
路由系统：处理 HTTP 请求的路由匹配和分发
中间件系统：处理请求前/后的逻辑，支持链式调用
WebSocket 处理：管理 WebSocket 连接和消息处理

2.2 请求处理流程

客户端发送 HTTP 请求到服务器
Bun 运行时接收请求并传递给 Bun-Crane 框架
框架根据请求路径和方法匹配对应的路由
如果匹配到路由，执行对应的中间件链
中间件执行完毕后，调用最终的请求处理器
请求处理器生成响应并返回给客户端

2.3 中间件执行机制

中间件采用链式调用机制，使用 compose 函数将多个中间件组合成一个处理器。中间件执行流程如下：

收集所有匹配当前路径的中间件
创建一个 next 函数，用于调用下一个中间件
创建 EventContext 对象，包含请求信息和 next 函数
执行第一个中间件
每个中间件可以选择调用 next() 继续执行后续中间件，或者直接返回响应
所有中间件执行完毕后，调用最终的请求处理器

3. 关键函数/模块解析

3.1 App 类

App 类是框架的核心，负责创建和配置 Web 服务器。

构造函数

constructor() {
    this.fetch = this.fetch.bind(this)
}

初始化 App 实例，绑定 fetch 方法的上下文。

page 方法

async page(dir: string = '')

从指定目录加载路由文件，支持 Next.js 风格的文件系统路由。

参数：

dir：路由文件目录路径，默认为空字符串

功能：

创建文件系统路由器，使用 Next.js 风格的路由
动态导入所有路由模块
注册路由处理器和中间件

use 方法

use(path: string | Middleware, middleware?: Middleware)

添加中间件，支持全局中间件和路径级中间件。

参数：

path：中间件应用的路径，或直接传入中间件函数
middleware：中间件函数，当 path 为字符串时必填

compose 方法

compose(handler: Handler)

组合中间件和请求处理器，生成一个新的处理器函数。

参数：

handler：最终的请求处理器函数

返回值：

组合后的处理器函数，类型为 BunHandler

路由方法

all(path: string, handler: Handler)：为所有 HTTP 方法注册同一个处理器
on(path: string, handler: Handler, method: HTTPMethod)：为指定 HTTP 方法注册处理器
get(path: string, handler: Handler)：GET 方法路由注册快捷方法
post(path: string, handler: Handler)：POST 方法路由注册快捷方法
put(path: string, handler: Handler)：PUT 方法路由注册快捷方法
delete(path: string, handler: Handler)：DELETE 方法路由注册快捷方法
patch(path: string, handler: Handler)：PATCH 方法路由注册快捷方法
head(path: string, handler: Handler)：HEAD 方法路由注册快捷方法
options(path: string, handler: Handler)：OPTIONS 方法路由注册快捷方法

ws 方法

ws(path: string, handler: WebSocketHandler<Headers>)

配置 WebSocket 服务。

参数：

path：WebSocket 连接的路径
handler：WebSocket 事件处理器

listen 方法

listen(options: ServerOptions = {})

启动 HTTP 服务器。

参数：

options：服务器配置选项，继承自 Bun.Serve.Options<Headers>

返回值：

Bun 服务器实例，类型为 Server

3.2 EventContext 类

EventContext 类封装了请求上下文信息，包含请求对象、参数、状态等。

构造函数

constructor(req: BunRequest, next: NextHandler)

参数：

req：Bun 请求对象
next：下一个中间件或处理器的调用函数

属性

req：Bun 请求对象
params：路由参数，类型为 { [key: string]: string }
state：请求状态，用于中间件间传递数据，类型为 Record<string, unknown>
cookies：请求 cookies，类型为 Bun.CookieMap
env：环境变量，类型为 ImportMetaEnv
next：下一个中间件或处理器的调用函数，类型为 NextHandler

3.3 辅助函数

defineMiddleware

export const defineMiddleware = (middleware: Middleware) => middleware

中间件定义辅助函数，用于类型推断和代码提示。

defineHandler

export const defineHandler = (handler: Handler) => handler

请求处理器定义辅助函数，用于类型推断和代码提示。

defineMethodHandler

export const defineMethodHandler = (methodHandler: MethodHandler) => methodHandler

方法处理器定义辅助函数，用于类型推断和代码提示。

defineWebSocketHandler

export const defineWebSocketHandler = (webSocketHandler: WebSocketHandler<undefined>) => webSocketHandler

WebSocket 处理器定义辅助函数，用于类型推断和代码提示。

4. 输入/输出参数说明

4.1 类型定义

Handler

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

请求处理器类型，接收 EventContext 对象，返回 Response 或 Promise。

Middleware

export type Middleware = (context: EventContext) => Promise<Response>

中间件类型，接收 EventContext 对象，返回 Promise。

MethodHandler

export type MethodHandler = Partial<{ [key in HTTPMethod]: BunHandler }>

按 HTTP 方法分类的请求处理器类型，键为 HTTP 方法，值为 BunHandler。

NextHandler

export type NextHandler = () => Promise<Response>

下一个中间件或处理器的调用函数类型，返回 Promise。

5. 使用方法

5.1 基本使用

安装

bun add bun-crane

创建简单服务器

import { App, defineHandler } from 'bun-crane'

const app = new App()

// 定义路由
app.get('/', defineHandler((context) => {
    return new Response('Hello, Bun-Crane!')
}))

// 启动服务器
app.listen({ port: 3000 })

5.2 使用中间件

import { App, defineHandler, defineMiddleware } from 'bun-crane'

const app = new App()

// 定义中间件
const loggerMiddleware = defineMiddleware(async (context) => {
    console.log(`[${new Date().toISOString()}] ${context.req.method} ${context.req.url}`)
    const response = await context.next()
    console.log(`[${new Date().toISOString()}] ${response.status}`)
    return response
})

// 使用中间件
app.use(loggerMiddleware)

// 定义路由
app.get('/', defineHandler((context) => {
    return new Response('Hello, Bun-Crane!')
}))

// 启动服务器
app.listen({ port: 3000 })

5.3 使用文件系统路由

import { App } from 'bun-crane'

const app = new App()

// 加载路由文件
await app.page('./pages')

// 启动服务器
app.listen({ port: 3000 })

在 ./pages 目录下创建路由文件，例如：

./pages/index.ts：处理根路径请求
./pages/about.ts：处理 /about 路径请求
./pages/api/[id].ts：处理 /api/:id 动态路由请求

5.4 使用 WebSocket

import { App, defineWebSocketHandler } from 'bun-crane'

const app = new App()

// 配置 WebSocket
app.ws('/ws', defineWebSocketHandler({
    open: (ws) => {
        console.log('WebSocket connection opened')
        ws.send('Welcome to Bun-Crane WebSocket!')
    },
    message: (ws, message) => {
        console.log('Received message:', message)
        ws.send(`Echo: ${message}`)
    },
    close: (ws) => {
        console.log('WebSocket connection closed')
    }
}))

// 启动服务器
app.listen({ port: 3000 })

6. 常见问题排查

6.1 路由匹配问题

问题：请求返回 404 Not Found

排查步骤：

检查路由路径是否正确定义
检查 HTTP 方法是否匹配
对于文件系统路由，检查文件路径是否符合 Next.js 风格
检查中间件是否正确调用了 next() 函数

6.2 中间件不执行

问题：定义的中间件没有被执行

排查步骤：

检查中间件是否正确使用 app.use() 注册
检查中间件路径是否与请求路径匹配
检查中间件是否正确调用了 next() 函数

6.3 WebSocket 连接失败

问题：WebSocket 连接无法建立

排查步骤：

检查 WebSocket 路径是否正确配置
检查 WebSocket 处理器是否正确注册
检查客户端连接 URL 是否与服务器配置一致
检查服务器是否支持 WebSocket（Bun 运行时默认支持）

6.4 服务器无法启动

问题：调用 app.listen() 后服务器无法启动

排查步骤：

检查端口是否被占用
检查配置选项是否正确
查看控制台输出的错误信息
检查是否正确导入了所有依赖

7. 示例运行步骤

7.1 运行示例应用

克隆仓库

git clone <repository-url>
cd bun-crane

安装依赖

bun install

运行示例应用

bun run dev

访问示例应用

打开浏览器访问 http://localhost:3000，可以看到示例应用的首页。

7.2 测试不同路由

静态路由：http://localhost:3000、http://localhost:3000/news、http://localhost:3000/post
动态路由：http://localhost:3000/api/123（将返回 {"id":"123"}）
WebSocket：使用 WebSocket 客户端连接 ws://localhost:3000/ws