Befly - 野蜂飞舞

道生一，一生二，二生三，三生万物

Befly 3.0 - JavaScript 版本

🎯 简介

Befly 是专为 Bun 运行时设计的现代化 API 框架，提供：

• ⚡ 简洁 JavaScript - 轻量直观
• 🚀 高性能 - 基于 Bun 运行时，超快的启动和执行速度
• 🔌 插件化架构 - 灵活的插件系统，轻松扩展功能
• 🗄️ 数据库（MySQL 8.0+） - core 仅支持 MySQL 8.0 及以上
• 📝 自动化表管理 - 基于 JSON 的表定义，自动同步数据库结构
• 🔐 内置身份验证 - sid 会话认证，角色权限管理
• 📊 完整日志系统 - 结构化日志，敏感字段过滤

📦 快速开始

安装

# 创建新项目
mkdir my-api && cd my-api

# 安装 Befly
bun add befly

最简示例

// index.js
import { Befly } from "befly";

// 配置从 configs/befly.*.json 扫描加载（见 packages/core/befly.config.js）
const app = new Befly({
    env: Bun.env
});
await app.start();

运行项目：

bun run index.js

创建第一个接口

// apis/user/hello.js
export default {
    name: "问候接口",
    auth: false, // 公开接口
    fields: {},
    handler: async (befly, ctx) => {
        return {
            msg: "Hello, Befly!",
            data: {
                timestamp: Date.now()
            }
        };
    }
};

访问：http://localhost:3000/api/app/user/hello

最小 smoke：在 api 模板项目新增接口并访问

1. 新增文件：apis/user/hello.js（上面示例可直接使用）
2. 启动服务：bun run dev
3. 访问：http://localhost:3000/api/app/user/hello

🔥 新版本特性（3.0）

增强的数据库操作

// 查询单条
const user = await befly.db.getOne({
    table: "user",
    where: { id: 1 }
});

// 分页列表
const result = await befly.db.getList({
    table: "product",
    where: { category: "electronics" },
    page: 1,
    limit: 10,
    orderBy: ["createdAt#DESC"]
});

// 插入数据
await befly.db.insData({
    table: "user",
    data: {
        username: "john",
        email: "[email protected]"
    }
});

// 更新数据
await befly.db.updData({
    table: "user",
    where: { id: 1 },
    data: {
        nickname: "John Doe"
    }
});

// 删除数据
await befly.db.delData({
    table: "user",
    where: { id: 1 }
});

智能表定义

{
    "username": "用户名|string|3|50|null|1|^[a-zA-Z0-9_]+$",
    "email": "邮箱|string|5|100|null|1|^[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\\.[a-zA-Z]{2,}$",
    "age": "年龄|number|0|150|18|0|null",
    "tags": "标签|array_string|0|10|null|0|null",
    "bio": "简介|text|0|5000|null|0|null"
}

字段定义格式："字段名|类型|最小值|最大值|默认值|是否索引|正则约束"

数据库与同步相关规则请参考 .github/skills/database-development/SKILL.md 与 .github/skills/core-runtime-overview/SKILL.md。

🗄️ 数据库配置（MySQL 8.0+）

统一使用环境变量配置（仅 MySQL 8.0+）：

DB_HOST=127.0.0.1
DB_PORT=3306
DB_USER=root
DB_PASS=password
DB_NAME=my_database

数据库同步

在 packages/api 目录中使用单一命令：

bun run db

该命令固定按以下顺序执行：

1. 先执行数据库差异检查（check）
2. 再执行表字段映射同步（apply）

不再区分 db:check、db:apply，也不需要传任何参数。

📖 文档

请优先参考仓库技能文档（.github/skills/*/SKILL.md），其中 API/表定义/插件/钩子/菜单/页面/配置/数据库/Redis/日志/运行链路已与当前代码对齐。

目录说明

• packages/core - Befly 核心框架包（发布到 npm）
• packages/api - API 项目模板示例
• packages/admin - 后台管理系统（Vue3 + TDesign Vue Next + 自动导入）

🚀 快速启动

启动 API 服务

bun run dev
# 访问: http://localhost:3000

启动后台管理

bun run dev:admin
# 访问: http://localhost:5173

🎓 示例项目

查看 packages/api 目录获取完整的示例项目。

🤝 贡献

欢迎提交 Issue 和 Pull Request！

📄 许可

MIT License

🌟 致谢

感谢所有为 Befly 做出贡献的开发者！

Befly 3.0 - 让 API 开发更简单、更高效！ 🚀