befly 3.9.40 → 3.10.1

package/docs/infra/redis.md

@@ -220,9 +220,11 @@ const count = await befly.redis.expireBatch([
 ### saddBatch - 批量添加 Set 成员
 
 ```typescript
+import { CacheKeys } from "befly/lib/cacheKeys";
+
 const count = await befly.redis.saddBatch([
-    { key: "role:admin:apis", members: ["GET/api/user", "POST/api/user"] },
-    { key: "role:editor:apis", members: ["GET/api/article", "POST/api/article"] }
+    { key: CacheKeys.roleApis("admin"), members: ["/api/user"] },
+    { key: CacheKeys.roleApis("editor"), members: ["/api/article"] }
 ]);
 // 返回: 成功添加的总成员数量
 ```
@@ -230,9 +232,11 @@ const count = await befly.redis.saddBatch([
 ### sismemberBatch - 批量检查 Set 成员
 
 ```typescript
+import { CacheKeys } from "befly/lib/cacheKeys";
+
 const results = await befly.redis.sismemberBatch([
-    { key: "role:admin:apis", member: "GET/api/user" },
-    { key: "role:admin:apis", member: "DELETE/api/user" }
+    { key: CacheKeys.roleApis("admin"), member: "/api/user" },
+    { key: CacheKeys.roleApis("admin"), member: "/api/user/delete" }
 ]);
 // 返回: [true, false]
 ```
@@ -285,11 +289,11 @@ const id = await befly.db.insData({
 import { CacheKeys } from "befly/lib/cacheKeys";
 
 // 获取键名
-const key = CacheKeys.apisAll(); // 'befly:apis:all'
-const key = CacheKeys.menusAll(); // 'befly:menus:all'
-const key = CacheKeys.roleInfo("admin"); // 'befly:role:info:admin'
-const key = CacheKeys.roleApis("admin"); // 'befly:role:apis:admin'
-const key = CacheKeys.tableColumns("user"); // 'befly:table:columns:user'
+const apisAllKey = CacheKeys.apisAll(); // 'befly:apis:all'
+const menusAllKey = CacheKeys.menusAll(); // 'befly:menus:all'
+const adminRoleInfoKey = CacheKeys.roleInfo("admin"); // 'befly:role:info:admin'
+const adminRoleApisKey = CacheKeys.roleApis("admin"); // 'befly:role:apis:admin'
+const userTableColumnsKey = CacheKeys.tableColumns("user"); // 'befly:table:columns:user'
 ```
 
 ### 键名前缀
@@ -304,7 +308,12 @@ Redis 插件支持配置全局前缀，避免键名冲突：
 }
 ```
 
-所有键会自动添加前缀：`myapp:user:1`
+所有键会自动添加前缀，最终写入 Redis 的 key 形如：`myapp:<key>`。
+
+- 例如：你调用 `befly.redis.getString("user:1")`，实际访问的是 `myapp:user:1`
+- 例如：你调用 `befly.redis.sismember(CacheKeys.roleApis("admin"), "/api/user")`，实际访问的是 `myapp:befly:role:apis:admin`
+
+> 注意：`redis.prefix` **不允许包含** `:`，因为 RedisHelper 会自动拼接分隔符 `:`。
 
 ---
 
@@ -313,6 +322,8 @@ Redis 插件支持配置全局前缀，避免键名冲突：
 ### 场景1：表结构缓存
 
 DbHelper 自动缓存表字段信息，避免重复查询数据库。
+
+```typescript
 // 计数 + 过期：常用于限流/风控
 // 更推荐：直接使用 Befly Core 内置的 rateLimit hook（通过 configs 配置即可）
 
@@ -323,8 +334,9 @@ const key = `ratelimit:${ctx.ip}:${ctx.route}`;
 const count = await befly.redis.incrWithExpire(key, windowSeconds);
 
 if (count > limit) {
-return befly.tool.No("请求过于频繁");
+    return befly.tool.No("请求过于频繁");
 }
+```
 
 ### 场景2：接口权限缓存
 
@@ -333,7 +345,7 @@ return befly.tool.No("请求过于频繁");
 ```typescript
 // 极简方案：每个角色一个 Set
 const roleApisKey = CacheKeys.roleApis("admin");
-const hasPermission = await befly.redis.sismember(roleApisKey, "POST/api/user/add");
+const hasPermission = await befly.redis.sismember(roleApisKey, "/api/user/add");
 // 返回: true
 ```
 
@@ -473,14 +485,14 @@ const menus = await befly.cache.getMenus();
 
 // 获取角色权限
 const permissions = await befly.cache.getRolePermissions("admin");
-// 返回: ['GET/api/user/list', 'POST/api/user/add', ...]
+// 返回: ['/api/user/list', '/api/user/add', ...]
 ```
 
 ### 权限检查
 
 ```typescript
 // 检查角色是否有指定接口权限
-const hasPermission = await befly.cache.checkRolePermission("admin", "POST/api/user/add");
+const hasPermission = await befly.cache.checkRolePermission("admin", "/api/user/add");
 // 返回: true 或 false
 ```
 

package/docs/plugins/plugin.md

@@ -72,7 +72,7 @@ import type { Plugin } from "befly/types/plugin";
 
 const plugin: Plugin = {
     // 依赖的插件列表（可选）
-    after: ["logger", "db"],
+    deps: ["logger", "db"],
 
     // 初始化函数（必填）
     handler: (befly) => {
@@ -96,10 +96,10 @@ interface Plugin {
     name?: string;
 
     /** 依赖的插件列表（在这些插件之后执行） */
-    after?: string[];
+    deps: string[];
 
     /** 插件初始化函数 */
-    handler?: (context: BeflyContext) => any | Promise<any>;
+    handler: (context: BeflyContext) => any | Promise<any>;
 
     /** 插件描述（可选） */
     description?: string;
@@ -171,12 +171,12 @@ interface Plugin {
 
 ### 依赖排序
 
-使用 `after` 属性声明依赖关系：
+使用 `deps` 属性声明依赖关系：
 
 ```typescript
 // redis.ts - 依赖 logger
 const plugin: Plugin = {
-    after: ["logger"], // 在 logger 插件之后初始化
+    deps: ["logger"], // 在 logger 插件之后初始化
     handler: () => {
         /* ... */
     }
@@ -199,7 +199,7 @@ const plugin: Plugin = {
 ```typescript
 // 插件源码
 const loggerPlugin: Plugin = {
-    after: [],
+    deps: [],
     async handler(): Promise<typeof Logger> {
         if (beflyConfig.logger) {
             Logger.configure(beflyConfig.logger);
@@ -250,10 +250,11 @@ const redisConfig = befly.config.redis;
 ```typescript
 // 插件源码
 const dbPlugin: Plugin = {
-    after: ["logger"],
+    deps: ["logger", "redis"],
     async handler(befly: BeflyContext): Promise<DbHelper> {
-        const sql = await Connect.connectSql();
-        return new DbHelper(befly, sql);
+        // 连接由启动期统一完成；插件仅消费已连接实例
+        const sql = Connect.getSql();
+        return new DbHelper({ redis: befly.redis, sql: sql, dialect: new MySqlDialect() });
     }
 };
 ```
@@ -285,9 +286,10 @@ await befly.db.delData({ table: "user", where: { id: 1 } });
 ```typescript
 // 插件源码
 const redisPlugin: Plugin = {
-    after: ["logger"],
+    deps: ["logger"],
     async handler(): Promise<RedisHelper | Record<string, never>> {
-        await Connect.connectRedis();
+        // 连接由启动期统一完成；插件仅校验连接存在
+        Connect.getRedis();
         return new RedisHelper(redisConfig.prefix);
     }
 };
@@ -384,9 +386,9 @@ const decrypted = befly.cipher.decrypt(encrypted);
 ```typescript
 // 插件源码
 const cachePlugin: Plugin = {
-    after: [],
+    deps: ["logger", "redis", "db"],
     async handler(befly: BeflyContext): Promise<CacheHelper> {
-        return new CacheHelper(befly);
+        return new CacheHelper({ db: befly.db, redis: befly.redis });
     }
 };
 ```
@@ -473,7 +475,7 @@ import type { Plugin } from "befly/types/plugin";
 import type { BeflyContext } from "befly/types/befly";
 
 const plugin: Plugin = {
-    after: ["db", "redis"], // 依赖数据库和 Redis
+    deps: ["db", "redis"], // 依赖数据库和 Redis
     handler: (befly: BeflyContext) => {
         return {
             async getUser(id: number) {
@@ -513,7 +515,7 @@ import type { Plugin } from "befly/types/plugin";
 import { Client } from "@elastic/elasticsearch";
 
 const plugin: Plugin = {
-    after: ["logger", "config"],
+    deps: ["logger", "config"],
     async handler(befly) {
         const config = befly.config.elasticsearch || {};
 
@@ -580,7 +582,7 @@ class SmsHelper {
 }
 
 const plugin: Plugin = {
-    after: ["logger", "config"],
+    deps: ["logger", "config"],
     handler: (befly: BeflyContext) => {
         const smsConfig = befly.config.sms || {};
         return new SmsHelper(befly, smsConfig);
@@ -688,7 +690,7 @@ class EmailHelper {
  * 邮件插件
  */
 const emailPlugin: Plugin = {
-    after: ["db", "logger", "config"],
+    deps: ["db", "logger", "config"],
     async handler(befly: BeflyContext): Promise<EmailHelper> {
         const emailConfig = befly.config?.addons?.admin?.email || {};
         return new EmailHelper(befly, emailConfig);
@@ -801,7 +803,7 @@ class WechatPayHelper {
 }
 
 const plugin: Plugin = {
-    after: ["logger", "config"],
+    deps: ["logger", "config"],
     handler: (befly: BeflyContext) => {
         return new WechatPayHelper(befly);
     }
@@ -851,7 +853,7 @@ const plugin: Plugin = {
 ```typescript
 // ✅ 推荐：明确声明所有依赖
 const plugin: Plugin = {
-    after: ["logger", "db", "redis"], // 声明所有使用的插件
+    deps: ["logger", "db", "redis"], // 声明所有使用的插件
     handler: (befly) => {
         /* ... */
     }
@@ -929,7 +931,7 @@ class DatabasePool {
 插件按以下顺序加载：
 
 1. 核心插件 → Addon 插件 → 项目插件
-2. 同一类型内根据 `after` 依赖关系排序
+2. 同一类型内根据 `deps` 依赖关系排序
 3. 无依赖的插件按文件名字母顺序
 
 ### Q2: 如何在插件中访问其他插件？
@@ -938,7 +940,7 @@ class DatabasePool {
 
 ```typescript
 const plugin: Plugin = {
-    after: ["db"], // 声明依赖
+    deps: ["db"], // 声明依赖
     handler: (befly) => {
         return {
             async getUser(id: number) {

package/docs/quickstart.md

@@ -1,331 +1,8 @@
-# Quickstart 快速入门
+# Quickstart 快速入门（已迁移）
 
-> 5 分钟搭建你的第一个 Befly API 服务
+为避免重复内容长期漂移，本 Quickstart 已迁移到权威入口：
 
-## 目录
+- `packages/core/docs/guide/quickstart.md`
+- 在线阅读：[`./guide/quickstart.md`](./guide/quickstart.md)
 
-- [环境准备](#环境准备)
-- [项目结构](#项目结构)
-- [第一个 API](#第一个-api)
-- [配置数据库](#配置数据库)
-- [定义表结构](#定义表结构)
-- [同步数据库](#同步数据库)
-- [启动服务](#启动服务)
-- [下一步](#下一步)
-
----
-
-## 环境准备
-
-### 必需软件
-
-| 软件  | 版本要求 | 说明              |
-| ----- | -------- | ----------------- |
-| Bun   | >= 1.0   | JavaScript 运行时 |
-| MySQL | >= 8.0   | 数据库            |
-| Redis | >= 6.0   | 缓存（可选）      |
-
-### 安装 Bun
-
-```bash
-# Windows (PowerShell)
-powershell -c "irm bun.sh/install.ps1 | iex"
-
-# macOS / Linux
-curl -fsSL https://bun.sh/install | bash
-```
-
-### 创建项目
-
-```bash
-# 克隆模板项目
-git clone https://github.com/chenbimo/befly-tpl.git my-api
-cd my-api
-
-# 安装依赖
-bun install
-```
-
----
-
-## 项目结构
-
-```
-my-api/
-├── apis/                  # API 接口目录
-│   └── user/
-│       └── login.ts       # 用户登录接口
-├── tables/                # 表定义目录
-│   └── user.json          # 用户表定义
-├── configs/               # 配置文件目录
-│   ├── befly.common.json  # 公共配置
-│   ├── befly.development.json  # 开发环境配置
-│   └── befly.production.json   # 生产环境配置
-├── main.ts                # 入口文件
-└── package.json
-```
-
----
-
-## 第一个 API
-
-### 创建 API 文件
-
-在 `apis/user/` 目录下创建 `login.ts`：
-
-```typescript
-import type { ApiRoute } from "befly/types/api";
-
-export default {
-    name: "用户登录",
-    method: "POST",
-    auth: false, // 不需要登录
-    fields: {
-        email: { name: "邮箱", type: "string", min: 5, max: 100, regexp: "@email" },
-        password: { name: "密码", type: "string", min: 6, max: 100 }
-    },
-    required: ["email", "password"],
-    handler: async (befly, ctx) => {
-        // 查询用户
-        const user = await befly.db.getDetail({
-            table: "user",
-            columns: ["id", "email", "password", "nickname"],
-            where: { email: ctx.body.email }
-        });
-
-        if (!user?.id) {
-            return No("用户不存在");
-        }
-
-        // 验证密码
-        const isValid = await befly.cipher.verifyPassword(ctx.body.password, user.password);
-        if (!isValid) {
-            return No("密码错误");
-        }
-
-        // 签发令牌
-        const token = befly.jwt.sign({ userId: user.id });
-
-        return Yes("登录成功", { token: token, user: { id: user.id, nickname: user.nickname } });
-    }
-} as ApiRoute;
-```
-
-### API 路由规则
-
-文件路径自动转换为路由：
-
-| 文件路径                | 路由路径                  |
-| ----------------------- | ------------------------- |
-| `apis/user/login.ts`    | `POST /api/user/login`    |
-| `apis/user/register.ts` | `POST /api/user/register` |
-| `apis/article/list.ts`  | `POST /api/article/list`  |
-
----
-
-## 配置数据库
-
-### 编辑配置文件
-
-修改 `configs/befly.development.json`：
-
-```json
-{
-    "db": {
-        "type": "mysql",
-        "host": "127.0.0.1",
-        "port": 3306,
-        "user": "root",
-        "password": "your_password",
-        "database": "my_api"
-    },
-    "redis": {
-        "host": "127.0.0.1",
-        "port": 6379,
-        "password": ""
-    },
-    "auth": {
-        "secret": "your-jwt-secret-change-in-production",
-        "expiresIn": "7d"
-    },
-    "logger": {
-        "debug": 1,
-        "console": 1
-    }
-}
-```
-
-### 创建数据库
-
-```sql
-CREATE DATABASE my_api CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;
-```
-
----
-
-## 定义表结构
-
-### 创建表定义文件
-
-在 `tables/` 目录下创建 `user.json`：
-
-```json
-{
-    "email": "邮箱|string|5|100||true|^[\\w.-]+@[\\w.-]+\\.[a-zA-Z]{2,}$",
-    "password": "密码|string|6|100||true",
-    "nickname": "昵称|string|2|50|用户",
-    "avatar": "头像|string|0|500",
-    "phone": "手机号|string|0|20"
-}
-```
-
-### 字段定义格式
-
-格式：`"字段标签|类型|最小|最大|默认|必填|正则"`
-
-| 位置 | 说明        | 示例                  |
-| ---- | ----------- | --------------------- |
-| 1    | 字段标签    | `邮箱`                |
-| 2    | 数据类型    | `string` / `number`   |
-| 3    | 最小值/长度 | `5`                   |
-| 4    | 最大值/长度 | `100`                 |
-| 5    | 默认值      | `用户`                |
-| 6    | 是否必填    | `true` / `false`      |
-| 7    | 正则验证    | `@email` 或自定义正则 |
-
-### 自动字段
-
-每个表自动添加：
-
-| 字段         | 类型    | 说明                            |
-| ------------ | ------- | ------------------------------- |
-| `id`         | BIGINT  | 主键，自增                      |
-| `created_at` | BIGINT  | 创建时间戳                      |
-| `updated_at` | BIGINT  | 更新时间戳                      |
-| `state`      | TINYINT | 状态（1=正常，0=禁用，-1=删除） |
-
----
-
-## 同步数据库
-
-### 运行同步命令
-
-```bash
-# 全量同步（表结构 + API + 菜单 + 开发账户）
-bun befly sync
-
-# 或单独同步
-bun befly sync:db      # 只同步表结构
-bun befly sync:api     # 只同步 API 路由
-```
-
-### 验证同步结果
-
-```bash
-# 查看数据库
-mysql -u root -p my_api -e "SHOW TABLES;"
-
-# 应该看到：
-# +------------------+
-# | Tables_in_my_api |
-# +------------------+
-# | user             |
-# +------------------+
-```
-
----
-
-## 启动服务
-
-### 开发模式
-
-```bash
-bun run dev
-```
-
-服务启动后：
-
-```
-🚀 Befly 服务已启动
-📍 http://localhost:3000
-```
-
-### 测试 API
-
-```bash
-# 测试登录接口
-curl -X POST http://localhost:3000/api/user/login \
-  -H "Content-Type: application/json" \
-  -d '{"email":"test@example.com","password":"123456"}'
-```
-
-响应示例：
-
-```json
-{
-    "code": 0,
-    "msg": "登录成功",
-    "data": {
-        "token": "eyJhbGciOiJIUzI1NiIs...",
-        "user": {
-            "id": 1,
-            "nickname": "用户"
-        }
-    }
-}
-```
-
----
-
-## 下一步
-
-### 学习更多
-
-| 主题       | 文档                                 | 说明                 |
-| ---------- | ------------------------------------ | -------------------- |
-| API 开发   | [api.md](./api/api.md)               | API 定义、字段、权限 |
-| 表结构     | [table.md](./table.md)               | 表定义格式详解       |
-| 数据库操作 | [database.md](./plugins/database.md) | CRUD 操作            |
-| 配置系统   | [config.md](./config.md)             | 配置文件说明         |
-| 插件开发   | [plugin.md](./plugins/plugin.md)     | 自定义插件           |
-| Hook 开发  | [hook.md](./hooks/hook.md)           | 请求处理钩子         |
-| 验证系统   | [validator.md](./validator.md)       | 参数验证             |
-| 日志系统   | [logger.md](./logger.md)             | 日志配置             |
-| 加密工具   | [cipher.md](./plugins/cipher.md)     | 加密与 JWT           |
-| 同步命令   | [sync.md](./sync.md)                 | 数据库同步           |
-
-### 常用命令
-
-```bash
-# 开发
-bun run dev          # 启动开发服务
-bun befly sync       # 同步数据库
-bun befly sync:db    # 只同步表结构
-
-# 生产
-bun run build        # 构建
-bun run start        # 启动生产服务
-```
-
-### 项目示例
-
-```
-apis/
-├── user/
-│   ├── login.ts      # 登录
-│   ├── register.ts   # 注册
-│   ├── info.ts       # 获取信息
-│   └── update.ts     # 更新信息
-├── article/
-│   ├── list.ts       # 文章列表
-│   ├── detail.ts     # 文章详情
-│   ├── create.ts     # 创建文章
-│   └── delete.ts     # 删除文章
-└── common/
-    └── upload.ts     # 文件上传
-
-tables/
-├── user.json         # 用户表
-├── article.json      # 文章表
-└── category.json     # 分类表
-```
+如你从旧链接跳转到这里，请以 `guide/quickstart.md` 的内容为准（配置字段、同步流程、权限 pathname 规则等都以当前实现为准）。

package/docs/reference/addon.md

@@ -465,10 +465,6 @@ A: 在配置文件中设置：
 }
 ```
 
-### Q: Addon 的表如何迁移？
-
-A: 使用 `befly sync:db` 命令，会自动同步所有 Addon 的表定义。
-
 ### Q: 如何在 Addon 中访问项目配置？
 
 A: 通过 `befly.config` 访问：

package/docs/reference/config.md

@@ -207,14 +207,14 @@ befly.development.json 或 befly.production.json（环境配置）
 
 ### Redis 配置 (redis)
 
-| 配置项     | 类型   | 默认值          | 说明             |
-| ---------- | ------ | --------------- | ---------------- |
-| `host`     | string | `'127.0.0.1'`   | Redis 主机       |
-| `port`     | number | `6379`          | Redis 端口       |
-| `username` | string | `''`            | Redis 用户名     |
-| `password` | string | `''`            | Redis 密码       |
-| `db`       | number | `0`             | Redis 数据库索引 |
-| `prefix`   | string | `'befly_demo:'` | Redis Key 前缀   |
+| 配置项     | 类型   | 默认值         | 说明                                                   |
+| ---------- | ------ | -------------- | ------------------------------------------------------ |
+| `host`     | string | `'127.0.0.1'`  | Redis 主机                                             |
+| `port`     | number | `6379`         | Redis 端口                                             |
+| `username` | string | `''`           | Redis 用户名                                           |
+| `password` | string | `''`           | Redis 密码                                             |
+| `db`       | number | `0`            | Redis 数据库索引                                       |
+| `prefix`   | string | `'befly_demo'` | Redis Key 前缀（不允许包含 `:`，分隔符由系统自动拼接） |
 
 ```json
 {
@@ -223,7 +223,7 @@ befly.development.json 或 befly.production.json（环境配置）
         "port": 6379,
         "password": "redis_password",
         "db": 1,
-        "prefix": "myapp:"
+        "prefix": "myapp"
     }
 }
 ```
@@ -295,13 +295,11 @@ befly.development.json 或 befly.production.json（环境配置）
 | ---------------- | -------- | ------ | -------------- |
 | `disableHooks`   | string[] | `[]`   | 禁用的钩子列表 |
 | `disablePlugins` | string[] | `[]`   | 禁用的插件列表 |
-| `hiddenMenus`    | string[] | `[]`   | 隐藏的菜单路径 |
 
 ```json
 {
     "disableHooks": ["requestLogger"],
-    "disablePlugins": ["redis"],
-    "hiddenMenus": ["/admin/debug", "/admin/test"]
+    "disablePlugins": ["redis"]
 }
 ```
 
@@ -381,7 +379,7 @@ NODE_ENV=production bun run start
     },
 
     "redis": {
-        "prefix": "myapp:"
+        "prefix": "myapp"
     },
 
     "cors": {
@@ -464,30 +462,15 @@ export default {
 ### 在插件中访问
 
 ```typescript
-import { beflyConfig } from "../befly.config.js";
-
 const plugin: Plugin = {
-    handler: () => {
-        const port = beflyConfig.appPort;
-        const dbConfig = beflyConfig.db;
+    handler: (context) => {
+        const port = context.config.appPort;
+        const dbConfig = context.config.db;
         // ...
     }
 };
 ```
 
-### 直接导入（仅 Befly 源码/单仓内）
-
-> 说明：`befly` 包的 `exports` 仅暴露 `befly`、`befly/lib/*`、`befly/utils/*`、`befly/types/*`。
-> 因此不支持 `befly/befly.config` 这种子路径导入。
-
-如果你在 Befly 源码/单仓内开发（例如编写内置插件/命令），可以使用相对路径导入：
-
-```typescript
-import { beflyConfig } from "../befly.config.js";
-
-console.log(beflyConfig.appName);
-```
-
 ---
 
 ## 最佳实践