bunms-core

Bun 微服务通用运行时库，提供 Express、日志、JWT、Redis 等开箱即用的模块。

安装

bun add bunms-core

API

bunms-core 的所有 API 通过 bms 命名空间访问。

初始化

模块是带有生命周期（default 工厂函数 + order 排序）的注册单元，通过 app.start(moduleMap) 加载：

import {bms} from 'bunms-core'
import type {BusiConfig} from '~my-service/config/BusiConfig'

// 返回 {config, getLogger, start(modules)}
export const app = bms.createApp<BusiConfig>()

await app.start(moduleMap) // 按 order 排序后依次初始化模块

moduleMap 可手动构建，也可使用 bunms-cli 扫描项目源码目录自动生成，详情见 bunms-cli 文档。

日志

const logger = app.getLogger('my-module')
logger.info('hello')

数据库

下游自行创建 Kysely 实例并管理生命周期：

import {Kysely, MysqlDialect} from 'kysely'
import mysql from 'mysql2/promise'

export const db = new Kysely<DB>({
  dialect: new MysqlDialect({ pool: mysql.createPool(app.config.db!.url) }),
})

Express

bms.express 是全局 Express 实例，内置模块自动注册中间件，无需手动调用。

静态 HTML

static 模块默认挂载 assets/html 目录到 /html 路径。通过 server.html 配置可自定义：

# config/base.yml
server:
  port: 3000
  html: assets/html    # 默认值，可省略
  # html: ''           # 设为空字符串则关闭静态HTML访问

使用 bunms-cli init 会自动生成 assets/html/index.html 最小页面。

Redis

若使用bunms-cli初始化项目，会自动将redis注册为模块，自动实例化 ，以下为手动实例化和清空方法

import {initRedis, redis} from 'bunms-core'
initRedis(someConfig) // 手动创建redis实例
redis(undefined) // 手动清空redis实例

无论自动还是手动实例化，获取方法相同：

import {redis} from 'bunms-core'
const redisClient = redis() // 获取当前的redis实例

工具函数

import {bms} from 'bunms-core'

// 向按行分割的文本文件注入条目，跳过已存在的行
bms.util.injectLines(
  '.gitignore',                        // 文件路径
  {'**/generated/*': 'include'},       // 内容 → 排重模式
  /^\s*#/                              // 可选：注释行正则，排重时忽略
)

排重模式：false（不排重）、'eq'（精确匹配）、'start'（前缀）、'end'（后缀）、'include'（包含）、RegExp（正则测试）。

单例工具

创建自包含、懒加载、可注入替换的泛型单例：

import {bms} from 'bunms-core'

const db = bms.singleton<Kysely<DB>>()       // 无工厂，需手动注入
db(new Kysely({ dialect: new SqliteDialect({ database: ':memory:' }) }))
db()  // 获取实例

const redis = bms.singleton<Redis>(() => new Redis())  // 带工厂，懒加载
redis().connect()

db(undefined)  // 重置实例

未初始化且无工厂时调用 getter 会抛出 SingletonNullError，可捕获做兜底初始化（见下方错误处理）。

错误处理

业务异常使用 HttpStatusError（来自 bunms-core）：

import { HttpStatusError } from 'bunms-core'

throw new HttpStatusError(404, '未找到')
throw new HttpStatusError(403, '权限不足', 1001)

• 构造函数参数：(status: number, message: string, code?: number)
• code 为业务错误码，默认 999；前端通过 error.response.data.code 获取
• 前端通过 error.response.data.message 获取错误描述
• 不在返回体中内嵌错误信息，直接抛异常

错误处理器 errorHandler 会根据错误类型返回对应状态码和业务码：

• HttpStatusError：使用其 status 和 code 字段
• 其他 Error：返回 500 状态码，code 为 999

数据库配置

db 字段为 IDBConfig 对象，运行时只需 url（用于创建 Kysely 实例），其余参数仅 bunms-cli db 生成类型时使用。完整字段说明与 DAO 生成配置见 skills/bunms-core/SKILL.md 的「配置系统」「db 配置字段」章节。

最小配置：

# config/base.yml
db:
  url: ./test.db

优先级：DATABASE_URL 环境变量 > yml 配置文件中的 db.url。未配置 yml 时自动从环境变量读取。