befly 3.10.18 → 3.10.19

package/README.md

@@ -4,356 +4,132 @@
 
 > 道生一，一生二，二生三，三生万物
 
-**Befly 3.0 - TypeScript 重构版本已发布！**
+专为 Bun 运行时设计的 API 框架：插件化、自动同步、内置权限与缓存。
 
-## 🎯 简介
+## 运行环境
 
-Befly 是专为 Bun 运行时设计的现代化 API 框架，提供：
+- Bun >= 1.0
+- MySQL >= 8.0（或 PostgreSQL / SQLite）
+- Redis >= 6.0（可选，但推荐）
 
-- ⚡ **原生 TypeScript 支持** - 完整的类型定义和智能提示
-- 🚀 **高性能** - 基于 Bun 运行时，超快的启动和执行速度
-- 🔌 **插件化架构** - 灵活的插件系统，轻松扩展功能
-- 🗄️ **多数据库支持** - MySQL、PostgreSQL、SQLite 统一接口
-- 📝 **自动化表管理** - 基于 JSON 的表定义，自动同步数据库结构
-- 🔐 **内置身份验证** - JWT 认证，角色权限管理
-- 📊 **完整日志系统** - 结构化日志，敏感字段过滤
+## 安装与启动
 
-## 📦 快速开始
+### 1) 安装
 
-### 安装
+在你的项目里安装：
 
 ```bash
-# 创建新项目
-mkdir my-api && cd my-api
-
-# 安装 Befly
 bun add befly
-
-# 初始化项目（即将支持）
-bunx befly init
-```
-
-### 最简示例
-
-```typescript
-// main.ts
-import { Befly } from "befly";
-
-const app = new Befly({
-    appName: "My API",
-    appPort: 3000
-});
-
-await app.start();
-```
-
-运行项目：
-
-```bash
-bun run main.ts
-```
-
-### 创建第一个接口
-
-```typescript
-// apis/user/hello.ts
-import type { ApiRoute } from "befly/types/api";
-
-export default {
-    name: "问候接口",
-    auth: false, // 公开接口
-    fields: {},
-    handler: async (befly, ctx) => {
-        return {
-            msg: "Hello, Befly!",
-            data: {
-                timestamp: Date.now()
-            }
-        };
-    }
-} as ApiRoute;
 ```
 
-访问：`http://localhost:3000/api/user/hello`
-
-## 🔥 新版本特性（3.0）
-
-### TypeScript 全面支持
-
-```typescript
-import type { ApiRoute } from "befly/types/api";
-import type { BeflyContext } from "befly/types/befly";
-import type { User } from "./types/models";
-
-export default {
-    name: "获取用户",
-    auth: true,
-    fields: {
-        id: "用户ID|number|1|999999|null|1|null"
-    },
-    required: ["id"],
-    handler: async (befly: BeflyContext, ctx) => {
-        const { id } = ctx.body;
-
-        // 类型安全的数据库查询
-        const user = await befly.db.getOne<User>({
-            table: "user",
-            where: { id }
-        });
-
-        return { msg: "查询成功", data: user };
-    }
-} as ApiRoute;
+### 2) 项目结构（约定）
+
+```text
+my-api/
+├── apis/                 # 项目 API（扫描 ts/js）
+│   └── user/
+│       └── hello.ts
+├── tables/               # 表定义 JSON（可选）
+│   └── user.json
+├── configs/              # 配置文件（必需）
+│   ├── befly.common.json
+│   ├── befly.development.json
+│   └── befly.production.json
+└── main.ts
 ```
 
-### 增强的数据库操作
+### 3) 配置文件
 
-```typescript
-// 查询单条
-const user = await befly.db.getOne<User>({
-    table: "user",
-    where: { id: 1 }
-});
-
-// 分页列表
-const result = await befly.db.getList<Product>({
-    table: "product",
-    where: { category: "electronics" },
-    page: 1,
-    limit: 10,
-    orderBy: ["createdAt#DESC"]
-});
-
-// 插入数据
-await befly.db.insData({
-    table: "user",
-    data: {
-        username: "john",
-        email: "john@example.com"
-    }
-});
-
-// 更新数据
-await befly.db.updData({
-    table: "user",
-    where: { id: 1 },
-    data: {
-        nickname: "John Doe"
-    }
-});
-
-// 删除数据
-await befly.db.delData({
-    table: "user",
-    where: { id: 1 }
-});
-```
-
-### 智能表定义
+`configs/befly.development.json` 示例：
 
 ```json
 {
-    "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"
-}
-```
-
-字段定义格式：`"字段名|类型|最小值|最大值|默认值|是否索引|正则约束"`
-
-同步到数据库：
-
-请参考：`docs/reference/sync.md`（`syncTable` / `syncData` 等同步流程说明）。
-
-## 🗄️ 数据库配置
-
-统一使用环境变量配置，支持三种数据库：
-
-```bash
-# MySQL
-DB_TYPE=mysql
-DB_HOST=127.0.0.1
-DB_PORT=3306
-DB_USER=root
-DB_PASS=password
-DB_NAME=my_database
-
-# PostgreSQL
-DB_TYPE=postgresql
-DB_HOST=localhost
-DB_PORT=5432
-DB_USER=postgres
-DB_PASS=password
-DB_NAME=my_database
-
-# SQLite
-DB_TYPE=sqlite
-DB_NAME=/path/to/database.sqlite
-# 或使用内存数据库
-DB_NAME=:memory:
-```
-
-## ⚙️ 项目配置文件
-
-Befly 使用 `befly.config.ts` 作为统一配置文件：
-
-```typescript
-// befly.config.ts
-export const beflyConfig = {
-    appName: "我的应用",
-    appPort: 3000,
-    appHost: "0.0.0.0",
-
-    // 数据库配置（优先使用环境变量）
-    db: {
-        type: "mysql",
-        host: "127.0.0.1",
-        port: 3306,
-        username: "root",
-        password: "password",
-        database: "my_database"
-    },
-
-    // Redis 配置
-    redis: {
-        host: "127.0.0.1",
-        port: 6379,
-        prefix: "befly"
+    "appName": "My API",
+    "appPort": 3000,
+    "appHost": "127.0.0.1",
+
+    "db": {
+        "type": "mysql",
+        "host": "127.0.0.1",
+        "port": 3306,
+        "username": "root",
+        "password": "root",
+        "database": "my_api"
     },
 
-    // CORS 跨域配置
-    cors: {
-        origin: ["http://localhost:5173"],
-        methods: ["GET", "POST", "PUT", "DELETE"]
+    "redis": {
+        "host": "127.0.0.1",
+        "port": 6379,
+        "db": 0,
+        "prefix": "my_api"
     },
 
-    // Addon 插件配置
-    addons: {
-        admin: {
-            email: { host: "smtp.qq.com" }
-        }
+    "auth": {
+        "secret": "change-me",
+        "expiresIn": "7d",
+        "algorithm": "HS256"
     }
-};
+}
 ```
 
-> 注意：`redis.prefix` 不要包含 `:`（系统会自动拼接分隔符）。
-
-### 数据库连接
-
-通常你不需要手动连接（框架启动期会完成连接并注入插件实例）。
+> 注意：`redis.prefix` 不要包含 `:`，框架会自动拼接分隔符。
 
-如果你在自定义脚本/测试中需要手动连接，请显式传入配置片段（不要依赖全局单例配置）：
+### 4) 启动入口
 
 ```typescript
-import { Connect } from "befly/lib/connect";
-
-// 连接 SQL 数据库
-await Connect.connectSql({
-    type: "mysql",
-    host: "127.0.0.1",
-    port: 3306,
-    username: "root",
-    password: "root",
-    database: "befly_demo",
-    poolMax: 1
-});
-
-// 连接 Redis
-await Connect.connectRedis({
-    host: "127.0.0.1",
-    port: 6379,
-    db: 0,
-    prefix: "befly"
-});
-
-// 或：同时连接 SQL 和 Redis
-await Connect.connect({
-    db: {
-        type: "mysql",
-        host: "127.0.0.1",
-        port: 3306,
-        username: "root",
-        password: "root",
-        database: "befly_demo",
-        poolMax: 1
-    },
-    redis: {
-        host: "127.0.0.1",
-        port: 6379,
-        db: 0,
-        prefix: "befly"
-    }
-});
-
-// 获取连接状态
-const status = Connect.getStatus();
-console.log(status.sql.connected); // true/false
-console.log(status.redis.connected); // true/false
+// main.ts
+import { Befly } from "befly";
 
-// 断开连接
-await Connect.disconnect();
+const app = new Befly();
+await app.start();
 ```
 
-### 配置文件（当前约定）
-
-配置文件名为 `befly.config.ts`，导出名为 `beflyConfig`：
+## 编写第一个 API
 
 ```typescript
-export const beflyConfig = {
-    // ...
-};
+// apis/user/hello.ts
+import type { ApiRoute } from "befly/types/api";
+
+export default {
+    name: "问候接口",
+    auth: false,
+    handler: async (_befly, _ctx) => {
+        return { code: 0, msg: "Hello, Befly!", data: { ts: Date.now() } };
+    }
+} as ApiRoute;
 ```
 
-## 📖 文档
+启动后访问：
 
-完整文档请访问 [`/docs` 目录](./docs/)：
+- `GET http://localhost:3000/api/app/user/hello`
 
-- [快速开始](./docs/02-快速上手/01-10分钟体验.md)
-- [核心概念](./docs/03-核心概念/)
-- [API 开发](./docs/04-API开发/)
-- [数据库操作](./docs/05-数据库/)
-- [TypeScript 支持](./docs/10-TypeScript/01-TypeScript支持.md)
+## 路由规则（重要）
 
-### 目录说明
+Befly 会根据“来源 + 文件相对路径”生成 `routePath`：
 
-- **`packages/core`** - Befly 核心框架包（发布到 npm）
-- **`packages/tpl`** - API 项目模板示例
-- **`packages/admin`** - 后台管理系统（Vue3 + TDesign Vue Next + 自动导入）
+- 项目 API：`apis/**/*.{ts,js}` → `/api/app/...`
+- Addon API：
+    - `addons/<addonName>/apis/**/*.{ts,js}` → `/api/addon/<addonName>/...`
+    - `node_modules/@befly-addon/<addonName>/apis/**/*.{ts,js}` → `/api/addon/<addonName>/...`
 
-## 🚀 快速启动
+并且：
 
-### 启动 API 服务
+- 系统内部用于存储/权限判断的 `routePath` **只看 `url.pathname`**（例如 `/api/app/user/login`）。
+- **禁止**把权限写成 `POST /api/...` 或 `POST/api/...`（那只是请求行展示，不参与存储）。
 
-```bash
-bun run dev
-# 访问: http://localhost:3000
-```
+## TypeScript 类型导入（public types）
 
-### 启动后台管理
+只从 `befly/types/*` 子路径引入类型：
 
-```bash
-bun run dev:admin
-# 访问: http://localhost:5173
+```typescript
+import type { ApiRoute } from "befly/types/api";
+import type { BeflyContext } from "befly/types/befly";
 ```
 
-## 🎓 示例项目
-
-查看 `/tpl` 目录获取完整的示例项目。
-
-## 🤝 贡献
-
-欢迎提交 Issue 和 Pull Request！
-
-## 📄 许可
-
-MIT License
-
-## 🌟 致谢
-
-感谢所有为 Befly 做出贡献的开发者！
+## 文档
 
----
+更多细节请看 `packages/core/docs/`：
 
-**Befly 3.0 - 让 API 开发更简单、更高效！** 🚀
+- `docs/guide/quickstart.md`
+- `docs/reference/sync.md`
+- `docs/plugins/plugin.md`

package/dist/befly.config.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Befly 配置模块
+ * 自动加载 configs 目录下的配置文件并与默认配置合并
+ * 支持环境分离：befly.common.json + befly.development/production.json
+ */
+import type { BeflyOptions } from "./types/befly.ts";
+export declare function loadBeflyConfig(): Promise<BeflyOptions>;

package/{befly.config.ts → dist/befly.config.js}

@@ -1,15 +1,7 @@
-/**
- * Befly 配置模块
- * 自动加载 configs 目录下的配置文件并与默认配置合并
- * 支持环境分离：befly.common.json + befly.development/production.json
- */
-import type { BeflyOptions } from "./types/befly.ts";
-
-import { compileDisableMenuGlobRules } from "./utils/disableMenusGlob.ts";
-import { scanConfig } from "./utils/scanConfig.ts";
-
+import { compileDisableMenuGlobRules } from "./utils/disableMenusGlob.js";
+import { scanConfig } from "./utils/scanConfig.js";
 /** 默认配置 */
-const defaultOptions: BeflyOptions = {
+const defaultOptions = {
     // ========== 核心参数 ==========
     nodeEnv: "development",
     appName: "野蜂飞舞",
@@ -19,7 +11,6 @@ const defaultOptions: BeflyOptions = {
     devPassword: "beflydev123456",
     bodyLimit: 1048576, // 1MB
     tz: "Asia/Shanghai",
-
     // ========== 日志配置 ==========
     logger: {
         debug: 1,
@@ -30,7 +21,6 @@ const defaultOptions: BeflyOptions = {
         maxStringLen: 100,
         maxArrayItems: 100
     },
-
     // ========== 数据库配置 ==========
     db: {
         type: "mysql",
@@ -41,7 +31,6 @@ const defaultOptions: BeflyOptions = {
         database: "befly_demo",
         poolMax: 10
     },
-
     // ========== Redis 配置 ==========
     redis: {
         host: "127.0.0.1",
@@ -51,14 +40,12 @@ const defaultOptions: BeflyOptions = {
         db: 0,
         prefix: "befly_demo"
     },
-
     // ========== 认证配置 ==========
     auth: {
         secret: "befly-secret",
         expiresIn: "7d",
         algorithm: "HS256"
     },
-
     // ========== CORS 配置 ==========
     cors: {
         origin: "*",
@@ -68,7 +55,6 @@ const defaultOptions: BeflyOptions = {
         maxAge: 86400,
         credentials: "true"
     },
-
     // ========== Hook：全局限流 ==========
     rateLimit: {
         enable: 1,
@@ -79,28 +65,22 @@ const defaultOptions: BeflyOptions = {
         skipRoutes: [],
         rules: []
     },
-
     // ========== 禁用配置 ==========
     disableHooks: [],
     disablePlugins: [],
     disableMenus: ["**/404", "**/403", "**/500", "**/login"],
-
     // ========== Addon 配置 ==========
     addons: {}
 };
-
-const beflyConfigCache: Map<string, Promise<BeflyOptions>> = new Map();
-
-export async function loadBeflyConfig(): Promise<BeflyOptions> {
+const beflyConfigCache = new Map();
+export async function loadBeflyConfig() {
     const nodeEnv = process.env.NODE_ENV || defaultOptions.nodeEnv || "development";
     const envSuffix = nodeEnv === "production" ? "production" : "development";
-
     const cacheKey = nodeEnv;
     const cached = beflyConfigCache.get(cacheKey);
     if (cached) {
         return await cached;
     }
-
     const promise = (async () => {
         // 使用 scanConfig 一次性加载并合并所有配置文件
         // 合并顺序：defaultOptions ← befly.common.json ← befly.development/production.json
@@ -111,30 +91,27 @@ export async function loadBeflyConfig(): Promise<BeflyOptions> {
             mode: "merge",
             defaults: defaultOptions
         });
-
         // 配置校验：redis.prefix 作为 key 前缀，由 RedisHelper 统一拼接 ":"。
         // 因此 prefix 本身不允许包含 ":"，否则会导致 key 结构出现空段或多段分隔（例如 "prefix::key"），
         // 在 RedisInsight 等工具里可能显示 [NO NAME] 空分组，且容易造成 key 管理混乱。
-        const redisPrefix = (config as any)?.redis?.prefix;
+        const redisPrefix = config?.redis?.prefix;
         if (typeof redisPrefix === "string") {
             const trimmedPrefix = redisPrefix.trim();
             if (trimmedPrefix.includes(":")) {
                 throw new Error(`配置错误：redis.prefix 不允许包含 ':'（RedisHelper 会自动拼接分隔符 ':'），请改为不带冒号的前缀，例如 'befly_demo'，当前值=${redisPrefix}`);
             }
         }
-
         // 预编译 disableMenus 的 Bun.Glob 规则：
         // - 提前暴露配置错误（fail-fast）
         // - 后续 checkMenu 会复用同一进程级缓存
-        compileDisableMenuGlobRules((config as any)?.disableMenus);
-
-        return config as BeflyOptions;
+        compileDisableMenuGlobRules(config?.disableMenus);
+        return config;
     })();
-
     beflyConfigCache.set(cacheKey, promise);
     try {
         return await promise;
-    } catch (error: any) {
+    }
+    catch (error) {
         beflyConfigCache.delete(cacheKey);
         throw error;
     }

package/dist/checks/checkApi.d.ts

@@ -0,0 +1 @@
+export declare function checkApi(apis: any[]): Promise<void>;

package/{checks/checkApi.ts → dist/checks/checkApi.js}

@@ -1,11 +1,8 @@
 import { isPlainObject } from "es-toolkit/compat";
 import { omit } from "es-toolkit/object";
-
-import { Logger } from "../lib/logger.ts";
-
-export async function checkApi(apis: any[]): Promise<void> {
+import { Logger } from "../lib/logger.js";
+export async function checkApi(apis) {
     let hasError = false;
-
     for (const api of apis) {
         try {
             if (typeof api?.name !== "string" || api.name.trim() === "") {
@@ -13,83 +10,69 @@ export async function checkApi(apis: any[]): Promise<void> {
                 hasError = true;
                 continue;
             }
-
             if (typeof api?.handler !== "function") {
                 Logger.warn(omit(api, ["handler"]), "接口的 handler 属性必须是函数");
                 hasError = true;
                 continue;
             }
-
             // routePath / routePrefix 由 scanFiles 系统生成：必须是严格的 pathname
             if (typeof api?.routePath !== "string" || api.routePath.trim() === "") {
                 Logger.warn(omit(api, ["handler"]), "接口的 routePath 属性必须是非空字符串（由系统生成）");
                 hasError = true;
-            } else {
+            }
+            else {
                 const routePath = api.routePath.trim();
-
                 // 不允许出现 "POST/api/..." 等 method 前缀
                 if (/^(GET|POST|PUT|PATCH|DELETE|OPTIONS|HEAD)\b/i.test(routePath)) {
                     Logger.warn(omit(api, ["handler"]), "接口的 routePath 不允许包含 method 前缀，应为 url.pathname（例如 /api/app/xxx）");
                     hasError = true;
                 }
-
                 if (!routePath.startsWith("/api/")) {
                     Logger.warn(omit(api, ["handler"]), "接口的 routePath 必须以 /api/ 开头");
                     hasError = true;
                 }
-
                 if (routePath.includes(" ")) {
                     Logger.warn(omit(api, ["handler"]), "接口的 routePath 不允许包含空格");
                     hasError = true;
                 }
-
                 if (routePath.includes("/api//")) {
                     Logger.warn(omit(api, ["handler"]), "接口的 routePath 不允许出现 /api//（重复斜杠）");
                     hasError = true;
                 }
             }
-
             if (typeof api?.routePrefix !== "string" || api.routePrefix.trim() === "") {
                 Logger.warn(omit(api, ["handler"]), "接口的 routePrefix 属性必须是非空字符串（由系统生成）");
                 hasError = true;
             }
-
             if (api.method && !["GET", "POST", "GET,POST", "POST,GET"].includes(String(api.method).toUpperCase())) {
                 Logger.warn(omit(api, ["handler"]), "接口的 method 属性必须是有效的 HTTP 方法 (GET, POST, GET,POST, POST,GET)");
                 hasError = true;
             }
-
             if (api.auth !== undefined && typeof api.auth !== "boolean") {
                 Logger.warn(omit(api, ["handler"]), "接口的 auth 属性必须是布尔值 (true=需登录, false=公开)");
                 hasError = true;
             }
-
             if (api.fields && !isPlainObject(api.fields)) {
                 Logger.warn(omit(api, ["handler"]), "接口的 fields 属性必须是对象");
                 hasError = true;
             }
-
             if (api.required && !Array.isArray(api.required)) {
                 Logger.warn(omit(api, ["handler"]), "接口的 required 属性必须是数组");
                 hasError = true;
             }
-
-            if (api.required && api.required.some((reqItem: any) => typeof reqItem !== "string")) {
+            if (api.required && api.required.some((reqItem) => typeof reqItem !== "string")) {
                 Logger.warn(omit(api, ["handler"]), "接口的 required 属性必须是字符串数组");
                 hasError = true;
             }
-        } catch (error: any) {
-            Logger.error(
-                {
-                    err: error,
-                    item: api
-                },
-                "接口解析失败"
-            );
+        }
+        catch (error) {
+            Logger.error({
+                err: error,
+                item: api
+            }, "接口解析失败");
             hasError = true;
         }
     }
-
     if (hasError) {
         throw new Error("接口结构检查失败");
     }

package/dist/checks/checkHook.d.ts

@@ -0,0 +1 @@
+export declare function checkHook(hooks: any[]): Promise<void>;