befly 3.9.14 → 3.9.23

package/checks/checkTable.ts

@@ -37,6 +37,11 @@ const RESERVED_FIELDS = ['id', 'created_at', 'updated_at', 'deleted_at', 'state'
  */
 const FIELD_TYPES = ['string', 'number', 'text', 'array_string', 'array_text'] as const;
 
+/**
+ * 允许的字段属性列表
+ */
+const ALLOWED_FIELD_PROPERTIES = ['name', 'type', 'min', 'max', 'default', 'detail', 'index', 'unique', 'nullable', 'unsigned', 'regexp'] as const;
+
 /**
  * 小驼峰命名正则
  * 可选：以下划线开头（用于特殊文件，如通用字段定义）
@@ -133,6 +138,14 @@ export async function checkTable(): Promise<void> {
                     // 直接使用字段对象
                     const field = fieldDef as FieldDefinition;
 
+                    // 检查是否存在非法属性
+                    const fieldKeys = Object.keys(field);
+                    const illegalProps = fieldKeys.filter((key) => !ALLOWED_FIELD_PROPERTIES.includes(key as any));
+                    if (illegalProps.length > 0) {
+                        Logger.warn(`${item.typeName}表 ${fileName} 文件 ${colKey} 包含非法属性: ${illegalProps.join(', ')}，` + `允许的属性为: ${ALLOWED_FIELD_PROPERTIES.join(', ')}`);
+                        hasError = true;
+                    }
+
                     // 检查必填字段：name, type
                     if (!field.name || typeof field.name !== 'string') {
                         Logger.warn(`${item.typeName}表 ${fileName} 文件 ${colKey} 缺少必填字段 name 或类型错误`);
@@ -193,6 +206,11 @@ export async function checkTable(): Promise<void> {
                         hasError = true;
                     }
 
+                    // 检查 unique 和 index 冲突（警告但不阻断）
+                    if (field.unique && field.index) {
+                        Logger.warn(`${item.typeName}表 ${fileName} 文件 ${colKey} 同时设置了 unique=true 和 index=true，` + `unique 约束会自动创建唯一索引，index=true 将被忽略以避免重复索引`);
+                    }
+
                     // 约束：当最小值与最大值均为数字时，要求最小值 <= 最大值
                     if (fieldMin !== undefined && fieldMax !== undefined && fieldMin !== null && fieldMax !== null) {
                         if (fieldMin > fieldMax) {

package/docs/1-/345/237/272/346/234/254/344/273/213/347/273/215.md

@@ -0,0 +1,35 @@
+# Befly - 野蜂飞舞
+
+![野蜂飞舞](https://static.yicode.tech/befly.svg)
+
+Befly 是专为 Bun 运行时设计的快速开发 API 框架，并配套一个完整的后台管理系统。
+
+## 🎯 特性
+
+- ⚡ **原生 TypeScript 支持** - 完整的类型定义和智能提示
+- 🚀 **高性能** - 基于 Bun 运行时，超快的启动和执行速度
+- 🔌 **插件化架构** - 灵活的插件系统，轻松扩展功能
+- 🗄️ **多数据库支持** - MySQL、PostgreSQL、SQLite 统一接口
+- 📝 **自动化表管理** - 基于 JSON 的表定义，自动同步数据库结构
+- 🔐 **内置身份验证** - JWT 认证，角色权限管理
+- 📊 **完整日志系统** - 结构化日志，敏感字段过滤
+
+## 📦 限制
+
+- 为单机部署，单数据库，单缓存，小系统，小项目而设计。
+- 大型项目，多数据库，复杂系统请勿用本项目。
+
+## 🤝 贡献
+
+- [github👉https://github.com/chenbimo/befly](https://github.com/chenbimo/befly)
+- [gitee👉https://gitee.com/chenbimo/befly](https://gitee.com/chenbimo/befly)
+
+欢迎提交 Issue 和 Pull Request！
+
+## 📄 许可
+
+MIT License
+
+## 🌟 致谢
+
+感谢所有为 Befly 做出贡献的开发者！

package/docs/2-/345/210/235/346/255/245/344/275/223/351/252/214.md

@@ -0,0 +1,64 @@
+> 注意：befly 开发后端服务统一使用`.ts`文件和`TypeScript`写法。
+
+由于 Befly 只支持 `Bun` 环境，所以我们可以在一个空目录下，用 `bun init` 命令创建一个新项目。
+
+创建的初始项目结构如下：
+
+```bash
+befly-demo/
+├── node_modules
+├── bun.lock
+├── index.ts
+├── package.json
+└── tsconfig.json
+```
+
+下一步，使用 `bun add befly` 安装 `befly` 依赖。
+
+```json
+{
+    "name": "befly-demo",
+    "module": "index.ts",
+    "type": "module",
+    "private": true,
+    "devDependencies": {
+        "@types/bun": "latest"
+    },
+    "peerDependencies": {
+        "typescript": "^5.9.3"
+    },
+    "dependencies": {
+        "befly": "^3.8.14"
+    }
+}
+```
+
+接下来，在 `index.ts` 文件中，导入 `befly` 并运行。
+
+```js
+import { Befly } from 'befly';
+
+const app = new Befly();
+await app.listen();
+```
+
+最后，在终端执行 `bun run index.ts`，运行后端服务。
+
+```bash
+D:\codes\_test\t10>bun run main.ts
+[2025-11-19 20:08:31]  WARN - 数据库未启用，跳过初始化
+[2025-11-19 20:08:31]  WARN - Redis 未启用，跳过初始化
+[2025-11-19 20:08:31]  INFO - 野蜂飞舞开发环境 启动成功!
+[2025-11-19 20:08:31]  INFO - 服务器启动耗时: 2.06 毫秒
+[2025-11-19 20:08:31]  INFO - 服务器监听地址: http://127.0.0.1:3000
+```
+
+`befly` 默认监听 `3000` 端口，如果显示以上信息，则表示接口服务启动了。
+
+服务启动后，在浏览器访问 `http://127.0.0.1:3000`，将会看到如下信息。
+
+![](https://static.yicode.tech/images/202511/20251119151025.png)
+
+由于 `数据库` 和 `Redis` 默认为关闭状态，所以此时的服务是纯接口服务，可以用来写一些不需要数据库，不需要缓存的接口功能。
+
+后续文章，我们将会详细了解到`接口开发`、`数据定义`、`增删改查` 等等。

package/docs/3-/347/254/254/344/270/200/344/270/252/346/216/245/345/217/243.md

@@ -0,0 +1,46 @@
+`befly` 采用的是 `约定大于配置` 的思路，所有项目相关的接口都要按照约定放在 `apis` 目录下。
+
+接下来我们实现一个简单的 `复读机` 接口 `apis/echo.ts`，文件结构如下：
+
+```bash
+befly-demo/
+├── apis
+│   ├── echo.ts     # 复读机接口
+├── node_modules
+├── bun.lock
+├── index.ts
+├── package.json
+└── tsconfig.json
+```
+
+接口文件的写法如下：
+
+```typescript
+import { Yes } from 'befly';
+
+export default {
+    name: '复读机接口',
+    method: 'get',
+    auth: false,
+    fields: {
+        words: {
+            name: '文字内容',
+            type: 'string',
+            min: 0,
+            max: 999
+        }
+    },
+    handler: async (befly, ctx) => {
+        return Yes(ctx.body.words, {
+            timestamp: Date.now(),
+            message: '欢迎使用 Befly 框架'
+        });
+    }
+};
+```
+
+访问：`http://127.0.0.1:3001/api/echo?words=我是复读机`，将会看到如下内容：
+
+![](https://static.yicode.tech/images/202511/20251119152234.png)
+
+这就是接口的定义和写法。

package/docs/4-/346/223/215/344/275/234/346/225/260/346/215/256/345/272/223.md

@@ -0,0 +1,172 @@
+要操作数据，需要在项目中创建一个`env.ts` 或 `env.js` 文件，示例如下：
+
+```js
+import type { EnvConfig } from './types/env.js';
+
+export const Env: Partial<EnvConfig> = {
+    // 启用数据库
+    DATABASE_ENABLE: 1,
+    // 数据库配置
+    DB_TYPE: 'mysql',
+    DB_HOST: '127.0.0.1',
+    DB_PORT: 3306,
+    DB_USER: 'root',
+    DB_PASS: 'root',
+    DB_NAME: 'befly_demo',
+    // Redis 配置
+    REDIS_HOST: '127.0.0.1',
+    REDIS_PORT: 6379,
+    REDIS_USERNAME: '',
+    REDIS_PASSWORD: '',
+    REDIS_DB: 0,
+    REDIS_KEY_PREFIX: 'befly_demo'
+};
+```
+
+需要注意的是，数据库配置和 Redis 缓存配置都要设置，不能只设置一个，`DATABASE_ENABLE` 设置为 `1` 后，将会开启数据库功能，如果配置错误则会报错，配置正确再次运行 `bun run main.ts` 则会显示如下信息：
+
+```bash
+D:\codes\_test\t10>bun run index.ts
+[2025-11-19 20:33:09]  INFO - 野蜂飞舞开发环境 服务器启动成功!
+[2025-11-19 20:33:09]  INFO - 服务器启动耗时: 2.04 毫秒
+[2025-11-19 20:33:09]  INFO - 服务器监听地址: http://127.0.0.1:3000
+```
+
+可以看到，没有 `数据库未启用，跳过初始化` 和 `Redis 未启用，跳过初始化` 的提示信息了。
+
+正确配置和连接数据库后，下一步就是设计`数据库表结构了`，同样也是 `约定大于配置` 的思路，`数据库字段` 全部在 根目录下的 `tables` 目录下创建和定义。
+
+```bash
+befly-demo/
+├── apis
+│   ├── echo.ts     # 复读机接口
+│   └── save.ts     # 保存接口
+├── tables
+│   └── info.json     # 信息表
+├── node_modules
+├── bun.lock
+├── index.ts
+├── package.json
+└── tsconfig.json
+```
+
+如上，在 `tables` 目录下创建了一个 `info.json` 表，定义如下：
+
+```json
+{
+    "name": {
+        "name": "姓名",
+        "type": "string",
+        "min": 2,
+        "max": 50
+    },
+    "code": {
+        "name": "年龄",
+        "type": "number",
+        "min": 0,
+        "max": 120
+    },
+    "value": {
+        "name": "身高",
+        "type": "number",
+        "min": 0,
+        "max": 300
+    },
+    "sort": {
+        "name": "体重",
+        "type": "number",
+        "min": 0,
+        "max": 9999
+    }
+}
+```
+
+`befly` 的表结构定义全部在文件中定义即可，那么要同步到数据库中，需要用到 `befly-cli` 依赖，使用 `bun add befly-cli` 安装即可。
+
+安装完毕后，执行 `bunx befly sync` 命令，同步数据库字段到真实数据库中，终端显示的内容如下：
+
+```bash
+D:\codes\_test\t10>bunx befly sync
+========================================
+开始执行完整同步流程
+当前环境: development
+项目名称: 野蜂飞舞开发环境
+数据库地址: 127.0.0.1
+数据库名称: befly_demo
+========================================
+
+🔍 正在检查项目结构...
+✓ 项目结构检查完成
+
+开始执行同步任务...
+
+📦 正在同步数据库...
+MySQL 版本: 8.0.31
+🧹 清理 1 个表的字段缓存...
+✓ 已清理表字段缓存
+✓ 数据库同步完成
+
+🔌 正在同步接口...
+表 addon_admin_api 不存在，跳过 API 同步（需要安装 addon-admin 组件）
+✓ 接口同步完成
+
+📋 正在同步菜单...
+表 addon_admin_menu 不存在，跳过菜单同步（需要安装 addon-admin 组件）
+✓ 菜单同步完成
+
+👤 正在同步开发账号...
+✓ 开发账号同步完成
+
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+✅ 同步完成！总耗时: 0.08 秒
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+```
+
+同步完毕后，使用数据库工具查看，我这里使用的是 `HeidiSQL`，如下图。
+
+![](https://static.yicode.tech/images/202511/20251119225701.png)
+
+需要注意，改动数据库定义后，都要执行 `bunx befly sync` 命令同步到实际数据库结构中才会生效。
+
+数据库同步完毕，下一步就是写保存信息接口 `apis/save.ts`，接收从客户端传入的参数，并保存到数据库中，如下：
+
+```js
+import { Yes } from 'befly';
+import infoTable from '../tables/info.json';
+
+export default {
+    name: '保存信息接口',
+    method: 'get',
+    auth: false,
+    fields: infoTable,
+    handler: async (befly, ctx) => {
+        const res = await befly.db.insData({
+            table: 'info',
+            data: {
+                name: ctx.body.name,
+                age: ctx.body.age,
+                height: ctx.body.height,
+                weight: ctx.body.weight
+            }
+        });
+        return Yes('信息保存成功', {
+            id: 17635656770001
+        });
+    }
+};
+```
+
+在浏览器访问 `http://127.0.0.1:3000/api/save?name=张三&age=18&height=160&weight=70`，返回内容如下图。
+
+![](https://static.yicode.tech/images/202511/20251119232313.png)
+
+同时呢，查看数据库的 `info` 表数据库，如下图，可以看到数据已经正确保存到了数据库中。
+
+![](https://static.yicode.tech/images/202511/20251119232426.png)
+
+这就是使用`Befly`框架来写接口，操作数据库的基本流程，简单来说其实只有 2 个主要步骤。
+
+1. 定义数据库表，同步表结构。
+2. 写增删改查接口，操作数据库。
+
+这就是 `Belfy` 的极简主义，没有那么多花里胡哨的概念，当然更多使用和配置细节，将在后续文章一一说明。

package/docs/README.md

@@ -1,4 +1,4 @@
-# Befly Core 文档
+# Befly Core 文档
 
 > Befly 是基于 Bun 的高性能 API 框架
 
@@ -75,7 +75,7 @@
 ## 常用链接
 
 - [GitHub](https://github.com/chenbimo/befly)
-- [npm](https://www.npmjs.com/package/befly-core)
+- [npm](https://www.npmjs.com/package/befly)
 
 ## 版本信息
 

package/docs/addon.md

@@ -1,4 +1,4 @@
-# Addon 插件包开发
+# Addon 插件包开发
 
 > 可复用的功能模块，包含 API、表、插件、视图
 
@@ -127,7 +127,7 @@ bun init
 `apis/hello/world.ts`：
 
 ```typescript
-import type { ApiRoute } from 'befly-core/types/api.js';
+import type { ApiRoute } from 'befly/types/api.js';
 
 export default {
     name: 'Hello World',
@@ -267,7 +267,7 @@ apis/
 ### API 定义示例
 
 ```typescript
-import type { ApiRoute } from 'befly-core/types/api.js';
+import type { ApiRoute } from 'befly/types/api.js';
 
 export default {
     name: '管理员登录',
@@ -339,7 +339,7 @@ await befly.db.getList({
 `plugins/email.ts`：
 
 ```typescript
-import type { Plugin } from 'befly-core/types/plugin.js';
+import type { Plugin } from 'befly/types/plugin.js';
 
 export interface EmailConfig {
     host: string;

package/docs/api.md

@@ -1,4 +1,4 @@
-# Befly API 接口文档
+# Befly API 接口文档
 
 > 本文档详细介绍 Befly 框架的 API 接口开发规范，包括路由定义、参数验证、权限控制、请求处理流程等。
 
@@ -123,7 +123,7 @@ addonAdmin/apis/
 ### 基础结构
 
 ```typescript
-import type { ApiRoute } from 'befly-core/types/api';
+import type { ApiRoute } from 'befly/types/api';
 
 export default {
     // 必填字段
@@ -294,7 +294,7 @@ befly.tool.No(msg: string, data?: any, other?: Record<string, any>)
 在 Hook 中使用，用于提前拦截请求：
 
 ```typescript
-import { ErrorResponse } from 'befly-core/util';
+import { ErrorResponse } from 'befly/util';
 
 // 在 Hook 中使用
 ctx.response = ErrorResponse(ctx, '未授权', 1, null);
@@ -1208,7 +1208,7 @@ handler: async (befly, ctx) => {
 
 ```typescript
 // tpl/hooks/requestLog.ts
-import type { Hook } from 'befly-core/types/hook';
+import type { Hook } from 'befly/types/hook';
 
 const hook: Hook = {
     order: 100, // 执行顺序

package/docs/config.md

@@ -519,7 +519,7 @@ const plugin: Plugin = {
 ### 直接导入
 
 ```typescript
-import { beflyConfig } from 'befly-core/befly.config';
+import { beflyConfig } from 'befly/befly.config';
 
 console.log(beflyConfig.appName);
 ```

package/docs/examples.md

@@ -1,4 +1,4 @@
-# 实战示例
+# 实战示例
 
 > 完整的 CRUD 模块开发示例
 
@@ -40,7 +40,7 @@
 `apis/user/register.ts`：
 
 ```typescript
-import type { ApiRoute } from 'befly-core/types';
+import type { ApiRoute } from 'befly/types';
 
 export default {
     name: '用户注册',
@@ -87,7 +87,7 @@ export default {
 `apis/user/login.ts`：
 
 ```typescript
-import type { ApiRoute } from 'befly-core/types';
+import type { ApiRoute } from 'befly/types';
 
 export default {
     name: '用户登录',
@@ -155,7 +155,7 @@ export default {
 `apis/user/info.ts`：
 
 ```typescript
-import type { ApiRoute } from 'befly-core/types';
+import type { ApiRoute } from 'befly/types';
 
 export default {
     name: '获取用户信息',
@@ -182,7 +182,7 @@ export default {
 `apis/user/update.ts`：
 
 ```typescript
-import type { ApiRoute } from 'befly-core/types';
+import type { ApiRoute } from 'befly/types';
 
 export default {
     name: '更新用户信息',
@@ -227,7 +227,7 @@ export default {
 `apis/user/changePassword.ts`：
 
 ```typescript
-import type { ApiRoute } from 'befly-core/types';
+import type { ApiRoute } from 'befly/types';
 
 export default {
     name: '修改密码',
@@ -276,7 +276,7 @@ export default {
 `apis/user/list.ts`：
 
 ```typescript
-import type { ApiRoute } from 'befly-core/types';
+import type { ApiRoute } from 'befly/types';
 
 export default {
     name: '用户列表',
@@ -368,7 +368,7 @@ export default {
 `apis/article/create.ts`：
 
 ```typescript
-import type { ApiRoute } from 'befly-core/types';
+import type { ApiRoute } from 'befly/types';
 
 export default {
     name: '发布文章',
@@ -422,7 +422,7 @@ export default {
 `apis/article/update.ts`：
 
 ```typescript
-import type { ApiRoute } from 'befly-core/types';
+import type { ApiRoute } from 'befly/types';
 
 export default {
     name: '编辑文章',
@@ -503,7 +503,7 @@ export default {
 `apis/article/delete.ts`：
 
 ```typescript
-import type { ApiRoute } from 'befly-core/types';
+import type { ApiRoute } from 'befly/types';
 
 export default {
     name: '删除文章',
@@ -554,7 +554,7 @@ export default {
 `apis/article/list.ts`：
 
 ```typescript
-import type { ApiRoute } from 'befly-core/types';
+import type { ApiRoute } from 'befly/types';
 
 export default {
     name: '文章列表',
@@ -608,7 +608,7 @@ export default {
 `apis/article/detail.ts`：
 
 ```typescript
-import type { ApiRoute } from 'befly-core/types';
+import type { ApiRoute } from 'befly/types';
 
 export default {
     name: '文章详情',
@@ -673,7 +673,7 @@ export default {
 ```typescript
 import { join } from 'pathe';
 import { existsSync, mkdirSync } from 'node:fs';
-import type { ApiRoute } from 'befly-core/types';
+import type { ApiRoute } from 'befly/types';
 
 export default {
     name: '文件上传',
@@ -735,7 +735,7 @@ export default {
 `apis/user/export.ts`：
 
 ```typescript
-import type { ApiRoute } from 'befly-core/types';
+import type { ApiRoute } from 'befly/types';
 
 export default {
     name: '导出用户',

package/docs/hook.md

@@ -1,4 +1,4 @@
-# Hook 钩子开发指南
+# Hook 钩子开发指南
 
 > 本文档详细介绍 Befly 框架的 Hook 钩子系统，包括钩子结构、执行顺序、内置钩子及自定义钩子开发。
 
@@ -72,7 +72,7 @@ Befly Hook 系统是请求处理的中间件机制，采用串联模式依次执
 ### 基础结构
 
 ```typescript
-import type { Hook } from 'befly-core/types/hook';
+import type { Hook } from 'befly/types/hook';
 
 const hook: Hook = {
     // 执行顺序（数字越小越先执行）
@@ -462,7 +462,7 @@ const hook: Hook = {
 
 ```typescript
 // hooks/myHook.ts（项目钩子名：app_myHook）
-import type { Hook } from 'befly-core/types/hook';
+import type { Hook } from 'befly/types/hook';
 
 const hook: Hook = {
     order: 10,
@@ -482,8 +482,8 @@ export default hook;
 
 ```typescript
 // hooks/blacklist.ts
-import type { Hook } from 'befly-core/types/hook';
-import { ErrorResponse } from 'befly-core/util';
+import type { Hook } from 'befly/types/hook';
+import { ErrorResponse } from 'befly/util';
 
 const hook: Hook = {
     order: 1, // 最先执行
@@ -509,8 +509,8 @@ export default hook;
 
 ```typescript
 // hooks/rateLimit.ts
-import type { Hook } from 'befly-core/types/hook';
-import { ErrorResponse } from 'befly-core/util';
+import type { Hook } from 'befly/types/hook';
+import { ErrorResponse } from 'befly/util';
 
 const hook: Hook = {
     order: 7,
@@ -551,7 +551,7 @@ export default hook;
 
 ```typescript
 // hooks/audit.ts
-import type { Hook } from 'befly-core/types/hook';
+import type { Hook } from 'befly/types/hook';
 
 const hook: Hook = {
     order: 100, // 在 handler 执行后
@@ -590,7 +590,7 @@ export default hook;
 设置 `ctx.response` 可以中断后续 Hook 和 API Handler 的执行：
 
 ```typescript
-import { ErrorResponse } from 'befly-core/util';
+import { ErrorResponse } from 'befly/util';
 
 const hook: Hook = {
     order: 5,

package/docs/plugin.md

@@ -1,4 +1,4 @@
-# 插件开发指南
+# 插件开发指南
 
 > 本文档详细介绍 Befly 框架的插件系统，包括插件结构、生命周期、内置插件及自定义插件开发。
 
@@ -68,7 +68,7 @@ Befly 插件系统是框架的核心扩展机制，允许开发者封装和复
 ### 基础结构
 
 ```typescript
-import type { Plugin } from 'befly-core/types/plugin';
+import type { Plugin } from 'befly/types/plugin';
 
 const plugin: Plugin = {
     // 依赖的插件列表（可选）
@@ -440,7 +440,7 @@ return befly.tool.No('操作失败');
 
 ```typescript
 // plugins/hello.ts
-import type { Plugin } from 'befly-core/types/plugin';
+import type { Plugin } from 'befly/types/plugin';
 
 const plugin: Plugin = {
     handler: () => {
@@ -467,8 +467,8 @@ const greeting = befly.app_hello.sayHello('World');
 
 ```typescript
 // plugins/userService.ts
-import type { Plugin } from 'befly-core/types/plugin';
-import type { BeflyContext } from 'befly-core/types/befly';
+import type { Plugin } from 'befly/types/plugin';
+import type { BeflyContext } from 'befly/types/befly';
 
 const plugin: Plugin = {
     after: ['db', 'redis'], // 依赖数据库和 Redis
@@ -507,7 +507,7 @@ export default plugin;
 
 ```typescript
 // plugins/elastic.ts
-import type { Plugin } from 'befly-core/types/plugin';
+import type { Plugin } from 'befly/types/plugin';
 import { Client } from '@elastic/elasticsearch';
 
 const plugin: Plugin = {
@@ -550,8 +550,8 @@ export default plugin;
 
 ```typescript
 // plugins/sms.ts
-import type { Plugin } from 'befly-core/types/plugin';
-import type { BeflyContext } from 'befly-core/types/befly';
+import type { Plugin } from 'befly/types/plugin';
+import type { BeflyContext } from 'befly/types/befly';
 
 interface SmsConfig {
     accessKeyId: string;
@@ -598,8 +598,8 @@ export default plugin;
 // addonAdmin/plugins/email.ts
 import nodemailer from 'nodemailer';
 import type { Transporter } from 'nodemailer';
-import type { Plugin } from 'befly-core/types/plugin';
-import type { BeflyContext } from 'befly-core/types/befly';
+import type { Plugin } from 'befly/types/plugin';
+import type { BeflyContext } from 'befly/types/befly';
 
 /** 邮件配置 */
 interface EmailConfig {
@@ -767,8 +767,8 @@ Addon 插件是组件包中的扩展功能，用于为 Addon 提供特定的服
 
 ```typescript
 // packages/addonPay/plugins/wechat.ts
-import type { Plugin } from 'befly-core/types/plugin';
-import type { BeflyContext } from 'befly-core/types/befly';
+import type { Plugin } from 'befly/types/plugin';
+import type { BeflyContext } from 'befly/types/befly';
 
 class WechatPayHelper {
     private befly: BeflyContext;

package/docs/quickstart.md

@@ -1,4 +1,4 @@
-# Quickstart 快速入门
+# Quickstart 快速入门
 
 > 5 分钟搭建你的第一个 Befly API 服务
 
@@ -74,7 +74,7 @@ my-api/
 在 `apis/user/` 目录下创建 `login.ts`：
 
 ```typescript
-import type { ApiRoute } from 'befly-core/types';
+import type { ApiRoute } from 'befly/types';
 
 export default {
     name: '用户登录',

package/lib/dbHelper.ts

@@ -638,7 +638,7 @@ export class DbHelper {
         // 如果总数为 0，直接返回，不执行第二次查询
         if (total === 0) {
             return {
-                list: [],
+                lists: [],
                 total: 0,
                 page: prepared.page,
                 limit: prepared.limit,
@@ -666,7 +666,7 @@ export class DbHelper {
 
         // 转换 BIGINT 字段（id, pid 等）为数字类型
         return {
-            list: this.convertBigIntFields<T>(camelList),
+            lists: this.convertBigIntFields<T>(camelList),
             total: total,
             page: prepared.page,
             limit: prepared.limit,

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "befly",
-    "version": "3.9.14",
+    "version": "3.9.23",
     "description": "Befly - 为 Bun 专属打造的 TypeScript API 接口框架核心引擎",
     "type": "module",
     "private": false,
@@ -74,7 +74,7 @@
         "pino": "^10.1.0",
         "pino-roll": "^4.0.0"
     },
-    "gitHead": "9f37fe1d7b660c79cbee174865b9d65b1a4ead22",
+    "gitHead": "9b5f1999ae83f1f0842f763845ec9d3e80e01f19",
     "devDependencies": {
         "typescript": "^5.9.3"
     }

package/sync/syncDb/table.ts

@@ -161,7 +161,8 @@ export async function modifyTable(sql: SQL, tableName: string, fields: Record<st
         const dbFieldName = snakeCase(fieldKey);
 
         const indexName = `idx_${dbFieldName}`;
-        if (fieldDef.index && !existingIndexes[indexName]) {
+        // 如果字段有 unique 约束，跳过创建普通索引（unique 会自动创建唯一索引）
+        if (fieldDef.index && !fieldDef.unique && !existingIndexes[indexName]) {
             indexActions.push({ action: 'create', indexName: indexName, fieldName: dbFieldName });
             changed = true;
         } else if (!fieldDef.index && existingIndexes[indexName] && existingIndexes[indexName].length === 1) {

package/types/database.d.ts

@@ -152,7 +152,7 @@ export interface DeleteOptions {
  */
 export interface ListResult<T = any> {
     /** 数据列表 */
-    list: T[];
+    lists: T[];
     /** 总条数 */
     total: number;
     /** 当前页码 */