基于 Bun.js 和 TypeScript 的轻量级后端 API 应用框架

1. 项目概览

这是一个基于Bun运行时的轻量级后端应用框架，采用MVC架构模式，提供了简洁的路由系统和数据库操作能力。

基于Bun运行时，提供高性能服务
内置路由解析和控制器映射机制
统一的CRUD操作接口
集成数据库操作模型，支持分页、排序等功能
使用TypeScript提供类型安全

2. 目录结构

项目采用模块化结构设计，代码组织清晰。核心逻辑位于src/core/目录，控制器位于src/controller/目录，应用入口为src/app.ts。

bash 复制代码

app/
├── src/
│   ├── app.ts             # 应用入口文件
│   ├── controller/        # 控制器目录
│   │   ├── Home.tsx       # 首页控制器
│   │   ├── Post.ts        # 帖子控制器
│   │   └── index.ts       # 控制器导出配置
│   └── core/              # 核心代码目录
│       ├── App.ts         # 应用主体类
│       ├── Base.ts        # 基础控制器类
│       └── Model.ts       # 数据模型类
├── package.json           # 项目配置和依赖
└── tsconfig.json          # TypeScript配置

3. 核心模块详解

3.1 应用主体 (App)

App类是整个应用的核心，负责初始化配置、启动HTTP服务器并处理路由请求。

typescript:src/core/App.ts 复制代码

class App {
    config: configType
    constructor(config: configType = { prot: 3000, development: true }) {
        this.config = config
    }
    start(controllers: Record<string, any>) {
        // 启动HTTP服务器并处理路由
    }
}

主要功能：

配置管理：支持设置端口和开发模式
路由解析：根据URL路径自动映射到对应控制器和方法
请求处理：将HTTP请求转发给相应的控制器方法处理
错误处理：提供统一的错误响应机制

3.2 基础控制器 (Base)

Base类定义了所有控制器的通用接口和默认实现，实现了RESTful API的基本CRUD操作。

typescript:src/core/Base.ts 复制代码

class Base implements IBase {
    public name: string=''    
    async index(req:Request) { /* 默认实现 */ }
    async add(req:Request) { /* 默认实现 */ }
    async read(req:Request) { /* 默认实现 */ }
    async edit(req:Request) { /* 默认实现 */ }
    async delete(req:Request) { /* 默认实现 */ }
}

主要功能：

提供标准的CRUD操作接口
统一的响应格式
支持控制器名称自动识别
便于子类继承和重写

3.3 数据模型 (Model)

Model类封装了数据库操作，提供了丰富的数据访问方法，是应用与数据库交互的桥梁。

typescript:src/core/Model.ts 复制代码

class Model<T extends Record<string, unknown>> {
    name = ''
    constructor(name: string) { this.name = name }
    
    // 分页查询
    async page(params = {}) { /* 实现 */ }
    // 列表查询
    async list(map = {}, sort = {}) { /* 实现 */ }
    // 添加数据
    async add(value: Record<string, unknown>) { /* 实现 */ }
    // 更新数据
    async update(id: number, value: Record<string, unknown>) { /* 实现 */ }
    // 删除数据
    async delete(map: Record<string, unknown>) { /* 实现 */ }
    // 更多数据库操作方法...
}

主要功能：

类型安全的数据操作
支持分页、排序、筛选
完整的CRUD操作API
基于Bun的SQL查询构建
数据验证集成

3.4 应用入口 (app.ts)

app.ts是应用的启动入口，负责初始化应用实例并启动服务。

typescript:src/app.ts 复制代码

import { App } from './core/App'
import * as controllers from './controller'

const app = new App()
app.start(controllers)

4. 控制器系统

控制器是处理HTTP请求的核心组件，项目采用了约定优于配置的方式进行路由映射。

4.1 路由规则

应用根据URL路径自动映射到对应的控制器和方法：

路径格式：/控制器名/方法名
控制器名会自动转换为驼峰命名（如user_profile -> UserProfile）
默认控制器为Home，默认方法为index

4.2 示例控制器

Home控制器：

typescript:src/controller/Home.tsx 复制代码

export class Home extends Base {
  override async index(req: Request) {
    return Response.json({ code: 0, msg: '首页' })
  }
  async login(req: Request) {
    return Response.json({ code: 0, msg: '登录' })
  }
}

Post控制器：

typescript:src/controller/Post.ts 复制代码

export class Post extends Base {
  // 可在此重写或添加自定义方法
}

5. 技术栈与依赖

技术/依赖	版本	用途
Bun	latest	JavaScript运行时和工具包
Zod	^4.1.3	数据验证库
TypeScript	^5	静态类型系统

6. 运行与开发

6.1 启动开发服务器

项目使用Bun的--watch模式支持热重载：

bash 复制代码

npm run dev
# 或直接使用bun
bun --watch ./src/app.ts

6.2 API访问示例

首页：GET http://localhost:3000/ 或 GET http://localhost:3000/home/index
登录：GET http://localhost:3000/home/login
Post控制器：GET http://localhost:3000/post/index

7. 项目特点与优势

轻量级架构：代码简洁，易于理解和扩展
高性能：基于Bun运行时，提供优异的性能表现
类型安全：完整的TypeScript支持，减少运行时错误
约定优于配置：简化路由配置，提高开发效率
模块化设计：清晰的代码组织，便于维护和扩展
内置数据操作：提供丰富的数据库操作API