Bun-Crane 是一个专为Bun JavaScript运行时设计的轻量级Web框架。它提供了简洁直观的API，支持装饰器路由、中间件、依赖注入和数据验证等功能，帮助开发者快速构建高性能的Web应用。

• ✅ 装饰器路由：使用TypeScript装饰器定义API路由和控制器
• ✅ 中间件支持：灵活的中间件机制，支持全局和路径级中间件
• ✅ 依赖注入：通过@Inject和@Provide装饰器实现简单的依赖注入
• ✅ 数据验证：集成Zod进行请求数据验证
• ✅ 文件系统路由：支持类似Next.js的文件系统路由方式
• ✅ WebSocket支持：内置WebSocket功能
• ✅ 路径参数：支持URL路径参数解析

• Bun运行时环境
• TypeScript 5.0+

# 使用Bun安装
bun add bun-crane 

1. 创建一个简单的应用入口文件：

// index.ts
import { App } from 'bun-crane'

const app = await App.create('./demo')
app.listen()

2. 创建控制器：

// demo/controller/home.ts
import { EventContext, Controller, Get, Post } from 'bun-crane'

@Controller('/home')
export class Home {
    @Get('/')
    async index(ctx: EventContext) {
        return {
            code: 0,
            msg: 'success',
            data: { name: 'Bun-Crane' }
        }
    }
    
    @Post('/add')
    async add(ctx: EventContext) {
        return ctx.body
    }
}

3. 创建服务：

// demo/service/Post.ts
import { Provide } from 'bun-crane'

@Provide('Post')
export class Post {
    name = "post"
    
    add() {
        console.log('Post add', this.name)
    }
}

4. 创建中间件：

// demo/middleware/log.ts
import { definePathMiddleware } from "bun-crane"
 
export default definePathMiddleware({
    '/home': async (context) => {
        console.log('Request received')
        let ret = await context.next()
        console.log('Response sent')
        return ret
    }
})

5. 创建页面路由：

// demo/page/index.ts
import { defineHandler } from "bun-crane"

export default defineHandler((context) => {
    return new Response('首页')
})

6. 运行应用：

bun run index.ts

应用主类，用于创建和配置Web服务器。

// 创建应用实例
const app = await App.create('./demo')

// 或手动创建
const app = new App()
await app.service('./demo/service')
await app.middleware('./demo/middleware')
await app.controller('./demo/controller')
await app.page('./demo/page')

• listen(options?: ServerOptions): 启动服务器
• use(path: string | Middleware, middleware?: Middleware): 添加中间件
• get/post/put/delete/patch/head/options(path: string, handler: Handler): 注册路由处理器
• ws(path: string, handler: WebSocketHandler): 配置WebSocket
• onError(error: (err: Error) => Response): 设置错误处理器

• @Controller(path?: string): 将类标记为控制器并设置基础路径
• @Get(path: string): 注册GET路由
• @Post(path: string): 注册POST路由
• @Put(path: string): 注册PUT路由
• @Delete(path: string): 注册DELETE路由

• @Provide(key?: string): 将类标记为可注入服务
• @Inject(key?: string): 注入依赖服务

• @Validate(zodSchema: z.ZodSchema): 验证请求体数据

每个路由处理器都会接收一个EventContext对象，包含以下属性和方法：

• req: Bun请求对象
• params: URL路径参数
• body: 请求体数据
• state: 用于在请求处理过程中存储状态数据
• cookies: Cookie映射
• env: 环境变量
• next(): 调用下一个中间件或处理器

Bun-Crane提供了灵活的中间件系统，支持全局中间件和路径级中间件。

// 定义全局中间件
import { defineMiddleware } from 'bun-crane'

export default defineMiddleware(async (context) => {
    console.log('Global middleware')
    return await context.next()
})

// 定义路径中间件
import { definePathMiddleware } from 'bun-crane'

export default definePathMiddleware({
    '/api': async (context) => {
        console.log('API middleware')
        return await context.next()
    },
    '/admin': async (context) => {
        console.log('Admin middleware')
        return await context.next()
    }
})

Bun-Crane集成了Zod用于请求数据验证。

// validate/post.ts
import { z } from 'zod'

export const PostSchema = z.object({
    title: z.coerce.string('标题必填').min(1, '标题不能为空'),
    content: z.coerce.string('内容必填').min(1, '内容不能为空')
})

// controller/post.ts
import { Controller, Post, Validate, EventContext } from 'bun-crane'
import { PostSchema } from '../validate/post'

@Controller('/posts')
export class PostController {
    @Post('/create')
    @Validate(PostSchema)
    async create(ctx: EventContext) {
        // ctx.body 已通过验证
        return { success: true, data: ctx.body }
    }
}

Bun-Crane支持类似Next.js的文件系统路由。

// page/index.ts - 对应 / 路径
export default (context) => {
    return new Response('首页')
}

// page/users.ts
export const onRequestGET = (context) => {
    return Response.json([{ id: 1, name: 'User 1' }])
}

export const onRequestPOST = (context) => {
    return Response.json({ success: true })
}

Bun-Crane内置WebSocket支持。

// page/_websocket.ts
import { defineWebSocketHandler } from 'bun-crane'

export default defineWebSocketHandler({
    message(ws, message) {
        // 处理收到的消息
        console.log('收到消息:', message)
        // 发送消息给客户端
        ws.send('已收到消息: ' + message)
    },
    open(ws) {
        // 新连接建立时
        console.log('新连接建立')
    },
    close(ws) {
        // 连接关闭时
        console.log('连接关闭')
    }
})

Bun-Crane提供简单的依赖注入机制。

// service/UserService.ts
import { Provide } from 'bun-crane'

@Provide('UserService')
export class UserService {
    findAll() {
        return [{ id: 1, name: 'User 1' }]
    }
}

// controller/user.ts
import { Controller, Get, Inject, EventContext } from 'bun-crane'

@Controller('/users')
export class UserController {
    @Inject('UserService')
    userService: any
    
    @Get('/')
    async index(ctx: EventContext) {
        return this.userService.findAll()
    }
}

可以自定义全局错误处理器。

app.onError((err) => {
    console.error('发生错误:', err)
    return new Response(`错误: ${err.message}`, { status: 500 })
})

项目中包含一个完整的示例应用，位于demo/目录下。示例展示了：

• 控制器定义和路由
• 服务定义和依赖注入
• 中间件使用
• 数据验证
• 页面路由

要运行示例：

bun run dev

1. 确保使用TypeScript 5.0+版本以支持装饰器语法
2. 项目依赖Bun运行时环境，无法在Node.js环境下运行
3. 使用装饰器时，确保在tsconfig.json中启用了装饰器支持：

{
  "compilerOptions": {
    "experimentalDecorators": true,
    "emitDecoratorMetadata": true
  }
}

该项目采用MIT许可证 - 详情请查看LICENSE文件