Bun-Crane 框架使用指南
框架概述
Bun-Crane 是一个为 Bun 运行时设计的轻量级 Web 框架，提供了简洁而强大的 API 来构建高性能的 Web 应用程序。它结合了现代框架的优雅设计与 Bun 运行时的卓越性能，支持路由、中间件、WebSocket 等核心 Web 功能。
源码下载
https://cnb.cool/hebian/bun-crane
主要特点：
- 轻量级设计，最小化依赖
- 支持基于文件系统的路由（类似 Next.js 风格）
- 灵活的中间件系统
- 完整的 HTTP 方法支持
- 内置 WebSocket 功能
- TypeScript 原生支持
- 高性能路由匹配
环境配置要求
在使用 Bun-Crane 之前，请确保您的环境满足以下要求：
- Bun 运行时：需要安装最新版本的 Bun
- TypeScript：版本 5.0 或更高（作为 peerDependency）
安装步骤
1. 安装 Bun（如果尚未安装）
# 使用官方安装脚本
curl -fsSL https://bun.sh/install | bash
2. 在项目中安装 Bun-Crane
# 使用 bun 安装
bun add bun-crane
# 安装 TypeScript（如果尚未安装）
bun add -D typescript
基本使用方法
创建简单的应用
以下是一个基本的 Bun-Crane 应用示例：
// index.ts
import { App } from 'bun-crane'
// 创建应用实例
const app = new App()
// 加载页面路由（可选）
await app.page('./pages')
// 添加中间件
app.use('/', (ctx) => {
console.log('Request received:', ctx.req.url)
return ctx.next()
})
// 定义 GET 路由
app.get('/', (ctx) => {
return new Response('Hello, Bun-Crane!')
})
// 启动服务器
app.listen({
port: 3000,
hostname: 'localhost'
})
运行应用：
bun run --watch index.ts
核心功能说明
1. 路由系统
Bun-Crane 支持两种路由定义方式：
基于文件系统的路由
创建 pages 目录，并在其中添加路由文件：
// pages/index.ts
import { defineHandler } from 'bun-crane'
export default defineHandler((context) => {
return new Response('Hello, World!')
})
手动路由注册
// 使用 HTTP 方法快捷函数
app.get('/api/users', (context) => {
return Response.json([{ id: 1, name: 'User 1' }])
})
app.post('/api/users', (context) => {
// 处理 POST 请求
return new Response('User created', { status: 201 })
})
// 为所有 HTTP 方法注册同一处理器
app.all('/health', (context) => {
return new Response('OK')
})
2. 中间件系统
中间件可以用于请求预处理、日志记录、认证授权等：
全局中间件
// 应用于所有路由
app.use((context) => {
console.log('Global middleware')
return context.next()
})
路径特定中间件
// 仅应用于 /api 开头的路由
app.use('/api', (context) => {
console.log('API middleware')
return context.next()
})
在路由文件中定义中间件
// pages/_middleware.ts
import { defineMiddleware } from 'bun-crane'
export const auth = defineMiddleware(async (context) => {
// 认证逻辑
return context.next()
})
export const logger = defineMiddleware((context) => {
// 日志记录逻辑
return context.next()
})
3. WebSocket 支持
Bun-Crane 提供了内置的 WebSocket 支持：
// 在应用中配置 WebSocket
app.ws('/ws', {
open: (ws) => {
console.log('WebSocket connection opened')
ws.send('Welcome!')
},
message: (ws, message) => {
console.log('Received message:', message)
ws.send(`Echo: ${message}`)
},
close: (ws) => {
console.log('WebSocket connection closed')
}
})
或者在路由文件中定义：
// pages/_websocket.ts
import { defineWebSocketHandler } from 'bun-crane'
export default defineWebSocketHandler({
open: (ws) => {
console.log('WebSocket connection opened')
},
message: (ws, message) => {
ws.send(`Received: ${message}`)
}
})
4. 请求处理
方法处理器
可以为不同的 HTTP 方法定义不同的处理器：
// pages/users.ts
import { defineMethodHandler } from 'bun-crane'
export default defineMethodHandler({
GET: (context) => {
return Response.json([{ id: 1, name: 'User 1' }])
},
POST: (context) => {
return new Response('Created', { status: 201 })
}
})
命名导出处理器
也可以使用命名导出定义特定方法的处理器：
// pages/products.ts
import { EventContext } from 'bun-crane'
export const onRequestGet = async (context: EventContext) => {
return Response.json([{ id: 1, name: 'Product 1' }])
}
export const onRequestPost = async (context: EventContext) => {
return new Response('Product created', { status: 201 })
}
5. 动态路由
支持类似 Next.js 的动态路由参数：
// pages/users/[id].ts
import { defineHandler } from 'bun-crane'
export default defineHandler((context) => {
// 访问动态路由参数
const { id } = context.params
return Response.json({ id, message: `User ${id}` })
})
常见操作示例
1. 创建 RESTful API
// pages/api/users/[id].ts
import { defineMethodHandler } from 'bun-crane'
export default defineMethodHandler({
GET: (context) => {
const { id } = context.params
return Response.json({ id, name: `User ${id}` })
},
PUT: async (context) => {
const { id } = context.params
const body = await context.req.json()
return Response.json({ id, ...body })
},
DELETE: (context) => {
const { id } = context.params
return new Response(`User ${id} deleted`, { status: 200 })
}
})
2. 使用中间件进行认证
// auth.ts
import { defineMiddleware } from 'bun-crane'
export const authMiddleware = defineMiddleware((context) => {
const authHeader = context.req.headers.get('Authorization')
if (!authHeader || !authHeader.startsWith('Bearer ')) {
return new Response('Unauthorized', { status: 401 })
}
const token = authHeader.split(' ')[1]
// 验证 token
if (!isValidToken(token)) {
return new Response('Invalid token', { status: 403 })
}
// 将用户信息添加到上下文状态
context.state.user = { id: 1, name: 'Authenticated User' }
return context.next()
})
// 在应用中使用
app.use('/api/protected', authMiddleware)
3. 静态文件服务
// 使用 Bun 的静态文件服务能力
app.get('/static/*', (context) => {
const path = context.req.url.split('/static/')[1]
const file = Bun.file(`./public/${path}`)
return new Response(file)
})
参数配置说明
App.listen() 配置选项
app.listen({
// 端口，默认为 3000
port: 3000,
// 主机名，默认为 '0.0.0.0'
hostname: 'localhost',
// TLS 选项
tls: {
key: Bun.file('./key.pem'),
cert: Bun.file('./cert.pem')
}
})
EventContext 对象
处理函数接收的上下文对象包含以下属性：
req: 请求对象，包含请求信息params: 路由参数state: 可用于中间件间传递数据的状态对象cookies: Cookie 映射env: 环境变量next(): 调用下一个中间件或处理函数
故障排除指南
1. 路由未找到
- 检查文件路径是否正确
- 确认路由文件已正确导出处理函数
- 对于动态路由，确保参数格式正确
2. 中间件不执行
- 检查中间件注册顺序
- 确保中间件调用了
context.next() - 验证路径匹配是否正确
3. WebSocket 连接失败
- 确认 WebSocket 路径配置正确
- 检查服务器是否支持 WebSocket
- 验证客户端连接 URL 是否正确
4. TypeScript 类型错误
- 确保安装了正确版本的 TypeScript
- 检查类型导入是否正确
- 使用
defineHandler、defineMiddleware等辅助函数确保类型安全
注意事项
-
性能优化：Bun-Crane 设计注重性能，但仍应注意避免在中间件中执行昂贵的操作
-
错误处理：建议添加全局错误处理中间件捕获未处理的异常
-
开发模式：使用
bun --watch启用热重载以提高开发效率 -
版本兼容性：由于框架仍在快速发展，请确保使用与您的项目兼容的版本
-
生产环境：在生产环境中部署前，建议进行充分的测试和性能优化
结语
Bun-Crane 提供了构建现代 Web 应用所需的核心功能，同时保持了轻量级和高性能的特点。无论是构建简单的 API 服务还是复杂的 Web 应用，Bun-Crane 都是一个值得考虑的选择。
扫一扫
1150
被折叠的 条评论
为什么被折叠?
到【灌水乐园】发言
