befly 3.10.0 → 3.10.2

package/README.md

@@ -220,7 +220,7 @@ export const beflyConfig = {
     redis: {
         host: "127.0.0.1",
         port: 6379,
-        prefix: "befly:"
+        prefix: "befly"
     },
 
     // CORS 跨域配置
@@ -238,6 +238,8 @@ export const beflyConfig = {
 };
 ```
 
+> 注意：`redis.prefix` 不要包含 `:`（系统会自动拼接分隔符）。
+
 ### 数据库连接
 
 通常你不需要手动连接（框架启动期会完成连接并注入插件实例）。
@@ -263,7 +265,7 @@ await Connect.connectRedis({
     host: "127.0.0.1",
     port: 6379,
     db: 0,
-    prefix: "befly:"
+    prefix: "befly"
 });
 
 // 或：同时连接 SQL 和 Redis
@@ -281,7 +283,7 @@ await Connect.connect({
         host: "127.0.0.1",
         port: 6379,
         db: 0,
-        prefix: "befly:"
+        prefix: "befly"
     }
 });
 
@@ -294,19 +296,14 @@ console.log(status.redis.connected); // true/false
 await Connect.disconnect();
 ```
 
-### 配置文件迁移指南
-
-如果你的项目之前使用 `app.config.ts`，请按以下步骤迁移：
+### 配置文件（当前约定）
 
-1. **重命名文件**：`app.config.ts` → `befly.config.ts`
-2. **更新导出名**：`config` → `beflyConfig`
+配置文件名为 `befly.config.ts`，导出名为 `beflyConfig`：
 
 ```typescript
-// 旧写法
-export const config = { ... };
-
-// 新写法
-export const beflyConfig = { ... };
+export const beflyConfig = {
+    // ...
+};
 ```
 
 ## 📖 文档

package/configs/presetFields.ts

@@ -0,0 +1,10 @@
+/**
+ * 预定义的默认字段（API fields 的 @ 引用）
+ */
+export const presetFields: Record<string, any> = {
+    "@id": { name: "ID", type: "number", min: 1, max: null },
+    "@page": { name: "页码", type: "number", min: 1, max: 9999, default: 1 },
+    "@limit": { name: "每页数量", type: "number", min: 1, max: 100, default: 30 },
+    "@keyword": { name: "关键词", type: "string", min: 0, max: 50 },
+    "@state": { name: "状态", type: "number", regex: "^[0-2]$" }
+};

package/configs/presetRegexp.ts

@@ -0,0 +1,225 @@
+/**
+ * 内置正则表达式别名
+ * 用于表单验证和数据校验
+ * 命名规范：小驼峰格式
+ */
+export const RegexAliases = {
+    // ============================================
+    // 数字类型
+    // ============================================
+    /** 正整数（不含0） */
+    number: "^\\d+$",
+    /** 整数（含负数） */
+    integer: "^-?\\d+$",
+    /** 浮点数 */
+    float: "^-?\\d+(\\.\\d+)?$",
+    /** 正整数（不含0） */
+    positive: "^[1-9]\\d*$",
+    /** 负整数 */
+    negative: "^-\\d+$",
+    /** 零 */
+    zero: "^0$",
+
+    // ============================================
+    // 字符串类型
+    // ============================================
+    /** 纯字母 */
+    word: "^[a-zA-Z]+$",
+    /** 字母和数字 */
+    alphanumeric: "^[a-zA-Z0-9]+$",
+    /** 字母、数字和下划线 */
+    alphanumeric_: "^[a-zA-Z0-9_]+$",
+    /** 字母、数字、下划线和短横线 */
+    alphanumericDash_: "^[a-zA-Z0-9_-]+$",
+    /** 小写字母 */
+    lowercase: "^[a-z]+$",
+    /** 大写字母 */
+    uppercase: "^[A-Z]+$",
+
+    // ============================================
+    // 中文
+    // ============================================
+    /** 纯中文 */
+    chinese: "^[\\u4e00-\\u9fa5]+$",
+    /** 中文和字母 */
+    chineseWord: "^[\\u4e00-\\u9fa5a-zA-Z]+$",
+
+    // ============================================
+    // 常用格式
+    // ============================================
+    /** 邮箱地址 */
+    email: "^[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\\.[a-zA-Z]{2,}$",
+    /** 中国大陆手机号 */
+    phone: "^1[3-9]\\d{9}$",
+    /** 固定电话（区号-号码） */
+    telephone: "^0\\d{2,3}-?\\d{7,8}$",
+    /** URL 地址 */
+    url: "^https?://",
+    /** IPv4 地址 */
+    ip: "^((25[0-5]|2[0-4]\\d|[01]?\\d\\d?)\\.){3}(25[0-5]|2[0-4]\\d|[01]?\\d\\d?)$",
+    /** IPv6 地址 */
+    ipv6: "^([0-9a-fA-F]{1,4}:){7}[0-9a-fA-F]{1,4}$",
+    /** 域名 */
+    domain: "^(?:[a-zA-Z0-9](?:[a-zA-Z0-9-]{0,61}[a-zA-Z0-9])?\\.)+[a-zA-Z]{2,}$",
+
+    // ============================================
+    // 特殊格式
+    // ============================================
+    /** UUID */
+    uuid: "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$",
+    /** 十六进制字符串 */
+    hex: "^[0-9a-fA-F]+$",
+    /** Base64 编码 */
+    base64: "^[A-Za-z0-9+/=]+$",
+    /** MD5 哈希 */
+    md5: "^[a-f0-9]{32}$",
+    /** SHA1 哈希 */
+    sha1: "^[a-f0-9]{40}$",
+    /** SHA256 哈希 */
+    sha256: "^[a-f0-9]{64}$",
+
+    // ============================================
+    // 日期时间
+    // ============================================
+    /** 日期 YYYY-MM-DD */
+    date: "^\\d{4}-\\d{2}-\\d{2}$",
+    /** 时间 HH:MM:SS */
+    time: "^\\d{2}:\\d{2}:\\d{2}$",
+    /** ISO 日期时间 */
+    datetime: "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}",
+    /** 年份 */
+    year: "^\\d{4}$",
+    /** 月份 01-12 */
+    month: "^(0[1-9]|1[0-2])$",
+    /** 日期 01-31 */
+    day: "^(0[1-9]|[12]\\d|3[01])$",
+
+    // ============================================
+    // 代码相关
+    // ============================================
+    /** 变量名 */
+    variable: "^[a-zA-Z_][a-zA-Z0-9_]*$",
+    /** 常量名（全大写） */
+    constant: "^[A-Z][A-Z0-9_]*$",
+    /** 包名（小写+连字符） */
+    package: "^[a-z][a-z0-9-]*$",
+
+    // ============================================
+    // 证件相关
+    // ============================================
+    /** 中国身份证号（18位） */
+    idCard: "^\\d{17}[\\dXx]$",
+    /** 护照号 */
+    passport: "^[a-zA-Z0-9]{5,17}$",
+
+    // ============================================
+    // 账号相关（国内常用）
+    // ============================================
+    /** 银行卡号（16-19位数字） */
+    bankCard: "^\\d{16,19}$",
+    /** 微信号（6-20位，字母开头，可包含字母、数字、下划线、减号） */
+    wechat: "^[a-zA-Z][a-zA-Z0-9_-]{5,19}$",
+    /** QQ号（5-11位数字，首位非0） */
+    qq: "^[1-9]\\d{4,10}$",
+    /** 支付宝账号（手机号或邮箱） */
+    alipay: "^(1[3-9]\\d{9}|[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\\.[a-zA-Z]{2,})$",
+    /** 用户名（4-20位，字母开头，可包含字母、数字、下划线） */
+    username: "^[a-zA-Z][a-zA-Z0-9_]{3,19}$",
+    /** 昵称（2-20位，支持中文、字母、数字） */
+    nickname: "^[\\u4e00-\\u9fa5a-zA-Z0-9]{2,20}$",
+
+    // ============================================
+    // 密码强度
+    // ============================================
+    /** 弱密码（至少6位） */
+    passwordWeak: "^.{6,}$",
+    /** 中等密码（至少8位，包含字母和数字） */
+    passwordMedium: "^(?=.*[a-zA-Z])(?=.*\\d).{8,}$",
+    /** 强密码（至少8位，包含大小写字母、数字和特殊字符） */
+    passwordStrong: "^(?=.*[a-z])(?=.*[A-Z])(?=.*\\d)(?=.*[!@#$%^&*]).{8,}$",
+
+    // ============================================
+    // 其他常用
+    // ============================================
+    /** 车牌号（新能源+普通） */
+    licensePlate: "^[京津沪渝冀豫云辽黑湘皖鲁新苏浙赣鄂桂甘晋蒙陕吉闽贵粤青藏川宁琼使领][A-Z][A-HJ-NP-Z0-9]{4,5}[A-HJ-NP-Z0-9挂学警港澳]$",
+    /** 邮政编码 */
+    postalCode: "^\\d{6}$",
+    /** 版本号（语义化版本） */
+    semver: "^\\d+\\.\\d+\\.\\d+(-[a-zA-Z0-9.]+)?(\\+[a-zA-Z0-9.]+)?$",
+    /** 颜色值（十六进制） */
+    colorHex: "^#([0-9a-fA-F]{3}|[0-9a-fA-F]{6})$",
+
+    // ============================================
+    // 空值
+    // ============================================
+    /** 空字符串 */
+    empty: "^$",
+    /** 非空 */
+    notempty: ".+"
+} as const;
+
+/**
+ * 正则别名类型
+ */
+export type RegexAliasName = keyof typeof RegexAliases;
+
+// ============================================
+// 正则表达式缓存（性能优化）
+// ============================================
+const regexCache = new Map<string, RegExp>();
+
+/**
+ * 获取正则表达式字符串
+ * @param name 正则别名（以 @ 开头）或自定义正则字符串
+ * @returns 正则表达式字符串
+ */
+export function getRegex(name: string): string {
+    if (name.startsWith("@")) {
+        const alias = name.slice(1) as RegexAliasName;
+        return RegexAliases[alias] || name;
+    }
+    return name;
+}
+
+/**
+ * 获取编译后的正则表达式对象（带缓存）
+ * @param pattern 正则别名或正则字符串
+ * @param flags 正则标志（如 'i', 'g'）
+ * @returns 编译后的 RegExp 对象
+ */
+export function getCompiledRegex(pattern: string, flags?: string): RegExp {
+    const regexStr = getRegex(pattern);
+    const cacheKey = `${regexStr}:${flags || ""}`;
+
+    let cached = regexCache.get(cacheKey);
+    if (!cached) {
+        cached = new RegExp(regexStr, flags);
+        regexCache.set(cacheKey, cached);
+    }
+    return cached;
+}
+
+/**
+ * 验证值是否匹配正则（使用缓存）
+ * @param value 要验证的值
+ * @param pattern 正则别名或正则字符串
+ * @returns 是否匹配
+ */
+export function matchRegex(value: string, pattern: string): boolean {
+    return getCompiledRegex(pattern).test(value);
+}
+
+/**
+ * 清除正则缓存
+ */
+export function clearRegexCache(): void {
+    regexCache.clear();
+}
+
+/**
+ * 获取缓存大小
+ */
+export function getRegexCacheSize(): number {
+    return regexCache.size;
+}

package/docs/README.md

@@ -2,18 +2,24 @@
 
 > Befly 是基于 Bun 的高性能 API 框架
 
+## 文档原则
+
+- 文档只描述**当前实现**：不提供迁移指引、不保留兼容说明、不出现“已迁移/跳转页/占位页”。
+- 如文档与代码行为不一致：**以代码为准**，应直接修正文档。
+- 规则以“可执行/可验证”为标准：给出明确约束（例如 pathname-only、严格校验规则），避免含糊表述。
+
 ## 快速开始
 
 - [Quickstart 快速入门](./guide/quickstart.md) - 5 分钟搭建第一个 API 服务
 
 ## 核心概念
 
-| 文档                                     | 说明                         |
-| ---------------------------------------- | ---------------------------- |
-| [API 开发](./api/api.md)                 | API 定义、字段验证、权限控制 |
-| [Table 表结构](./reference/table.md)     | JSON 表定义格式、字段类型    |
-| [Database 数据库](./plugins/database.md) | CRUD 操作、事务、批量操作    |
-| [Config 配置](./reference/config.md)     | 配置文件、环境分离           |
+| 文档                                     | 说明                                                                  |
+| ---------------------------------------- | --------------------------------------------------------------------- |
+| [API 开发](./api/api.md)                 | API 定义、字段验证、权限控制（[强约束清单](./api/api.md#强约束清单)） |
+| [Table 表结构](./reference/table.md)     | JSON 表定义格式、字段类型                                             |
+| [Database 数据库](./plugins/database.md) | CRUD 操作、事务、批量操作                                             |
+| [Config 配置](./reference/config.md)     | 配置文件、环境分离                                                    |
 
 ## 扩展开发
 
@@ -41,9 +47,9 @@
 
 ## 命令工具
 
-| 文档                             | 说明                  |
-| -------------------------------- | --------------------- |
-| [Sync 同步](./reference/sync.md) | 数据库、API、菜单同步 |
+| 文档                             | 说明                                                                  |
+| -------------------------------- | --------------------------------------------------------------------- |
+| [Sync 同步](./reference/sync.md) | 数据库、API、菜单同步（[强约束清单](./reference/sync.md#强约束清单)） |
 
 ## 实战示例
 
@@ -57,7 +63,7 @@
 
 ### 开发篇
 
-2. **[API](./api/api.md)** - API 路由定义、字段验证、权限控制、响应格式
+2. **[API](./api/api.md)** - API 路由定义、字段验证、权限控制、响应格式（[强约束清单](./api/api.md#强约束清单)）
 3. **[Table](./reference/table.md)** - 表定义格式、字段类型、系统字段、命名规范
 4. **[Database](./plugins/database.md)** - 数据库连接、CRUD 操作、事务处理、批量操作
 5. **[Config](./reference/config.md)** - 配置文件结构、环境分离、运行时配置
@@ -77,7 +83,7 @@
 
 ### 运维篇
 
-13. **[Sync](./reference/sync.md)** - syncTable、syncData（内部：syncApi、syncMenu、syncDev）
+13. **[Sync](./reference/sync.md)** - syncTable、syncApi、syncMenu、syncDev、syncCache（[强约束清单](./reference/sync.md#强约束清单)）
 
 ## 常用链接
 

package/docs/api/api.md

@@ -8,6 +8,7 @@
     - [目录](#目录)
     - [概述](#概述)
         - [核心特性](#核心特性)
+    - [强约束清单](#强约束清单)
     - [目录结构](#目录结构-1)
         - [项目 API](#项目-api)
         - [Addon API](#addon-api)
@@ -78,6 +79,15 @@ Befly 框架的 API 系统是一套基于约定优于配置的接口开发体系
 
 ---
 
+## 强约束清单
+
+- **权限/路由匹配只看 pathname**：系统内部用于路由匹配与权限判断的值均为 `url.pathname`（例如 `/api/user/login`），与 method 无关。
+- **禁止写法**：禁止把权限或路由路径写成 `POST/api/...` 或 `POST /api/...`（这些只是一种“请求行展示写法”，不能进入任何存储/配置/权限集合）。
+- **routePath 必须严格合法**：必须以 `/api/` 开头、不得包含空格、不得出现 `/api//`。
+- **同一路径多方法共用权限**：同一个 pathname（例如 `/api/user/login`）即使同时注册 GET/POST，也共用同一套权限集合。
+
+---
+
 ## 目录结构
 
 ### 项目 API
@@ -139,7 +149,7 @@ export default {
     fields: {}, // 字段定义（验证规则）
     required: [], // 必填字段列表
     rawBody: false // 是否保留原始请求体
-    // 缓存/限流：已统一迁移为 Hook 能力（见 hook 文档/配置），不再挂载在接口定义上
+    // 缓存/限流：当前实现为 Hook 能力（见 hook 文档/配置），不再挂载在接口定义上
 } as ApiRoute;
 ```
 
@@ -1276,6 +1286,8 @@ if (!ctx.user?.id) {
 | `addonAdmin/apis/auth/login.ts` | `POST /api/addon/addonAdmin/auth/login` |
 | `addonAdmin/apis/admin/list.ts` | `POST /api/addon/addonAdmin/admin/list` |
 
+> 注意：上表中的 `POST /api/...` 是“请求行示意”。系统内部生成并存储的 `ctx.route` / 数据库 `routePath` / 角色权限 `role.apis` / Redis 权限缓存都只使用 `url.pathname`（例如 `/api/user/login`），与 method 无关；权限数据禁止写成 `POST /api/...` 或 `POST/api/...`。
+
 ### 多方法注册
 
 当 `method: 'GET,POST'` 时，会同时注册两个路由：
@@ -1283,6 +1295,8 @@ if (!ctx.user?.id) {
 - `GET /api/user/search`
 - `POST /api/user/search`
 
+> 权限校验只看 pathname：如果同一个 pathname 同时注册了多个 method，它们共享同一套权限（以 `/api/user/search` 作为权限值）。
+
 ---
 
 ## BeflyContext 对象

package/docs/guide/quickstart.md

@@ -121,6 +121,8 @@ export default {
 | `apis/user/register.ts` | `POST /api/user/register` |
 | `apis/article/list.ts`  | `POST /api/article/list`  |
 
+> 注意：上面的写法是“HTTP 请求方法 + url.pathname”。系统内部生成并存储的 `routePath`、角色权限 `role.apis` 以及 Redis 权限缓存都只使用 `url.pathname`（例如 `/api/user/login`），与 method 无关，且禁止写成 `POST/api/...` 或 `POST /api/...`。
+
 ---
 
 ## 配置数据库
@@ -135,7 +137,7 @@ export default {
         "type": "mysql",
         "host": "127.0.0.1",
         "port": 3306,
-        "user": "root",
+        "username": "root",
         "password": "your_password",
         "database": "my_api"
     },
@@ -213,19 +215,31 @@ CREATE DATABASE my_api CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;
 服务启动时会在**主进程**自动执行同步流程：
 
 1. `syncTable()`：同步表结构
-2. `syncData()`：固定顺序执行 `syncApi` → `syncMenu` → `syncDev`
+2. `syncApi()`：同步接口定义
+3. `syncMenu()`：同步菜单定义
+4. `syncDev()`：同步开发账户/开发角色
+5. `syncCache()`：缓存同步收尾（cacheApis + cacheMenus + rebuildRoleApiPermissions）
 
 如需手动触发，可在代码中调用（一般不建议在请求路径中调用）：
 
 ```typescript
-import { syncData } from "../sync/syncData.js";
 import { syncTable } from "../sync/syncTable.js";
+import { syncApi } from "../sync/syncApi.js";
+import { syncMenu } from "../sync/syncMenu.js";
+import { syncDev } from "../sync/syncDev.js";
+import { syncCache } from "../sync/syncCache.js";
+import { checkMenu } from "../checks/checkMenu.js";
 import { scanSources } from "../utils/scanSources.js";
 
-// ctx：BeflyContext（需已具备 ctx.db / ctx.redis / ctx.config）
+// ctx：BeflyContext（需已具备 ctx.db / ctx.redis / ctx.cache / ctx.config）
 const sources = await scanSources();
+const checkedMenus = await checkMenu(sources.addons, { disableMenus: ctx.config.disableMenus || [] });
+
 await syncTable(ctx, sources.tables);
-await syncData();
+await syncApi(ctx, sources.apis as any);
+await syncMenu(ctx, checkedMenus);
+await syncDev(ctx, { devEmail: ctx.config.devEmail, devPassword: ctx.config.devPassword });
+await syncCache(ctx);
 ```
 
 ### 验证同步结果

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: ["/api/user"] },
-    { key: "role:editor:apis", members: ["/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: "/api/user" },
-    { key: "role:admin:apis", member: "/api/user/delete" }
+    { 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：接口权限缓存