befly 3.10.14 → 3.10.16

package/docs/api/api.md

@@ -518,14 +518,14 @@ export default {
 
         const result = await befly.db.getList({
             table: "article",
-            columns: ["id", "title", "summary", "createdAt"],
+            fields: ["id", "title", "summary", "createdAt"],
             where: where,
             page: page || 1,
             limit: limit || 10,
-            orderBy: { id: "desc" }
+            orderBy: ["id#DESC"]
         });
 
-        return befly.tool.Yes("获取成功", result);
+        return befly.tool.Yes("获取成功", result.data);
     }
 } as ApiRoute;
 ```
@@ -542,11 +542,13 @@ export default {
     },
     required: ["id"],
     handler: async (befly, ctx) => {
-        const article = await befly.db.getDetail({
+        const articleRes = await befly.db.getOne({
             table: "article",
             where: { id: ctx.body.id, state: 1 }
         });
 
+        const article = articleRes.data;
+
         if (!article?.id) {
             return befly.tool.No("文章不存在");
         }
@@ -1336,29 +1338,23 @@ interface BeflyContext {
 
 ### 常用工具方法
 
-#### befly.db.cleanFields - 清理数据字段
+#### fieldClear - 清理数据字段
 
-清理对象中的 `null` 和 `undefined` 值，适用于处理可选参数：
+清理对象中的指定值（常用：`null/undefined`），适用于处理可选参数。
 
 ```typescript
-// 方法签名
-befly.db.cleanFields<T>(
-    data: T,                           // 要清理的数据对象
-    excludeValues?: any[],             // 要排除的值，默认 [null, undefined]
-    keepValues?: Record<string, any>   // 强制保留的键值对
-): Partial<T>
-```
+import { fieldClear } from "befly/utils/fieldClear";
 
-**基本用法：**
-
-```typescript
-// 默认排除 null 和 undefined
-const cleanData = befly.db.cleanFields({
-    name: "John",
-    age: null,
-    email: undefined,
-    phone: ""
-});
+// 常用：排除 null 和 undefined
+const cleanData = fieldClear(
+    {
+        name: "John",
+        age: null,
+        email: undefined,
+        phone: ""
+    },
+    { excludeValues: [null, undefined] }
+);
 // 结果: { name: 'John', phone: '' }
 ```
 
@@ -1366,19 +1362,22 @@ const cleanData = befly.db.cleanFields({
 
 ```typescript
 // 同时排除 null、undefined 和空字符串
-const cleanData = befly.db.cleanFields({ name: "John", phone: "", age: null }, [null, undefined, ""]);
+const cleanData = fieldClear({ name: "John", phone: "", age: null }, { excludeValues: [null, undefined, ""] });
 // 结果: { name: 'John' }
 ```
 
 **保留特定字段的特定值：**
 
 ```typescript
-// 即使值在排除列表中，也保留 status 字段的 null 值
-const cleanData = befly.db.cleanFields({ name: "John", status: null, count: 0 }, [null, undefined], { status: null });
-// 结果: { name: 'John', status: null, count: 0 }
+// 保留 count 的 0 值
+const cleanData = fieldClear(
+    { name: "John", status: null, count: 0 },
+    { excludeValues: [null, undefined], keepMap: { count: 0 } }
+);
+// 结果: { name: 'John', count: 0 }
 ```
 
-> **注意**：`insData`、`updData` 和 `where` 条件会自动调用 `cleanFields`，通常无需手动调用。
+> **注意**：DbHelper 的写入（`insData/insBatch/updData`）与查询条件（`where`）会自动过滤 `null/undefined`，通常无需手动调用。
 
 ---
 
@@ -1562,15 +1561,16 @@ export default {
     required: ["productId", "quantity"],
     handler: async (befly, ctx) => {
         // 使用事务确保库存扣减和订单创建的原子性
-        const result = await befly.db.transaction(async (trx) => {
+        const result = await befly.db.trans(async (trx) => {
             // 1. 查询商品信息（带锁）
-            const product = await trx.getOne({
+            const productRes = await trx.getOne({
                 table: "product",
-                where: { id: ctx.body.productId },
-                forUpdate: true // 行锁
+                where: { id: ctx.body.productId }
             });
 
-            if (!product) {
+            const product = productRes.data;
+
+            if (!product?.id) {
                 throw new Error("商品不存在");
             }
 
@@ -1588,7 +1588,7 @@ export default {
             });
 
             // 3. 创建订单
-            const orderId = await trx.insData({
+            const orderIdRes = await trx.insData({
                 table: "order",
                 data: {
                     userId: ctx.user.id,
@@ -1599,6 +1599,8 @@ export default {
                 }
             });
 
+            const orderId = orderIdRes.data;
+
             // 4. 创建订单明细
             await trx.insData({
                 table: "order_item",
@@ -1640,19 +1642,21 @@ export default {
         }
 
         // 批量插入
-        const result = await befly.db.batchInsert({
-            table: "user",
-            data: users.map((user: any) => ({
-                username: user.username,
-                email: user.email,
-                nickname: user.nickname || user.username,
-                state: 1
-            }))
-        });
+        const idsRes = await befly.db.insBatch(
+            "user",
+            users.map((user: any) => {
+                return {
+                    username: user.username,
+                    email: user.email,
+                    nickname: user.nickname || user.username,
+                    state: 1
+                };
+            })
+        );
 
         return befly.tool.Yes("导入成功", {
             total: users.length,
-            inserted: result.affectedRows
+            ids: idsRes.data
         });
     }
 };
@@ -1682,7 +1686,7 @@ export default {
         });
 
         return befly.tool.Yes("更新成功", {
-            updated: result.affectedRows
+            updated: result.data
         });
     }
 };
@@ -1711,7 +1715,7 @@ export default {
         });
 
         return befly.tool.Yes("删除成功", {
-            deleted: result.affectedRows
+            deleted: result.data
         });
     }
 };
@@ -1728,12 +1732,14 @@ export default {
     required: ['id'],
     handler: async (befly, ctx) => {
         // 查询订单基本信息
-        const order = await befly.db.getOne({
+        const orderRes = await befly.db.getOne({
             table: 'order',
             where: { id: ctx.body.id }
         });
 
-        if (!order) {
+        const order = orderRes.data;
+
+        if (!order?.id) {
             return befly.tool.No('订单不存在');
         }
 
@@ -1744,23 +1750,17 @@ export default {
         });
 
         // 查询用户信息
-        const user = await befly.db.getOne({
+        const userRes = await befly.db.getOne({
             table: 'user',
+            fields: ['id', 'username', 'nickname', 'phone'],
             where: { id: order.userId }
         });
 
+        const user = userRes.data;
+
         return befly.tool.Yes('查询成功', {
             order: order,
-            items: itemsResult.lists,  // 订单明细列表
-            user: user
-        });
-            where: { id: order.userId },
-            columns: ['id', 'username', 'nickname', 'phone']
-        });
-
-        return befly.tool.Yes('获取成功', {
-            ...order,
-            items: items,
+            items: itemsResult.data.lists, // 订单明细列表
             user: user
         });
     }
@@ -1784,13 +1784,13 @@ export default {
                     on: { "article.authorId": "author.id" }
                 }
             ],
-            columns: ["article.id", "article.title", "article.createdAt", "author.nickname AS authorName"],
+            fields: ["article.id", "article.title", "article.createdAt", "author.nickname AS authorName"],
             page: ctx.body.page || 1,
             limit: ctx.body.limit || 10,
             orderBy: ["article.createdAt#DESC"]
         });
 
-        return befly.tool.Yes("获取成功", result);
+        return befly.tool.Yes("获取成功", result.data);
     }
 };
 ```
@@ -1866,14 +1866,14 @@ export default {
         // 查询所有用户（不分页，注意上限 10000 条）
         const result = await befly.db.getAll({
             table: "user",
-            columns: ["id", "username", "nickname", "email", "phone", "createdAt"],
+            fields: ["id", "username", "nickname", "email", "phone", "createdAt"],
             where: { state: 1 },
             orderBy: ["createdAt#DESC"]
         });
 
         // 转换为 CSV 格式
         const headers = ["ID", "用户名", "昵称", "邮箱", "手机", "注册时间"];
-        const rows = result.lists.map((u: any) => [u.id, u.username, u.nickname, u.email, u.phone, new Date(u.createdAt).toLocaleString()]);
+        const rows = result.data.lists.map((u: any) => [u.id, u.username, u.nickname, u.email, u.phone, new Date(u.createdAt).toLocaleString()]);
 
         const csv = [headers.join(","), ...rows.map((r: any[]) => r.join(","))].join("\n");
 

package/docs/guide/examples.md

@@ -54,21 +54,21 @@ export default {
     required: ["email", "password"],
     handler: async (befly, ctx) => {
         // 检查邮箱是否已存在
-        const exists = await befly.db.getDetail({
+        const existsRes = await befly.db.getOne({
             table: "user",
-            columns: ["id"],
+            fields: ["id"],
             where: { email: ctx.body.email }
         });
 
-        if (exists?.id) {
-            return No("该邮箱已被注册");
+        if (existsRes.data?.id) {
+            return befly.tool.No("该邮箱已被注册");
         }
 
         // 加密密码
         const hashedPassword = await befly.cipher.hashPassword(ctx.body.password);
 
         // 创建用户
-        const result = await befly.db.insData({
+        const idRes = await befly.db.insData({
             table: "user",
             data: {
                 email: ctx.body.email,
@@ -77,7 +77,7 @@ export default {
             }
         });
 
-        return Yes("注册成功", { id: result.insertId });
+        return befly.tool.Yes("注册成功", { id: idRes.data });
     }
 } as ApiRoute;
 ```
@@ -100,31 +100,33 @@ export default {
     required: ["email", "password"],
     handler: async (befly, ctx) => {
         // 查询用户
-        const user = await befly.db.getDetail({
+        const userRes = await befly.db.getOne({
             table: "user",
-            columns: ["id", "email", "password", "nickname", "avatar", "role", "state"],
+            fields: ["id", "email", "password", "nickname", "avatar", "role", "state", "loginCount"],
             where: { email: ctx.body.email }
         });
 
+        const user = userRes.data;
+
         if (!user?.id) {
-            return No("用户不存在");
+            return befly.tool.No("用户不存在");
         }
 
         if (user.state !== 1) {
-            return No("账户已被禁用");
+            return befly.tool.No("账户已被禁用");
         }
 
         // 验证密码
         const isValid = await befly.cipher.verifyPassword(ctx.body.password, user.password);
         if (!isValid) {
-            return No("密码错误");
+            return befly.tool.No("密码错误");
         }
 
         // 更新登录信息
         await befly.db.updData({
             table: "user",
             data: {
-                loginCount: user.loginCount + 1,
+                loginCount: (user.loginCount || 0) + 1,
                 lastLoginAt: Date.now()
             },
             where: { id: user.id }
@@ -132,11 +134,11 @@ export default {
 
         // 签发令牌
         const token = befly.jwt.sign({
-            userId: user.id,
+            id: user.id,
             role: user.role
         });
 
-        return Yes("登录成功", {
+        return befly.tool.Yes("登录成功", {
             token: token,
             user: {
                 id: user.id,
@@ -162,17 +164,19 @@ export default {
     method: "GET",
     auth: true,
     handler: async (befly, ctx) => {
-        const user = await befly.db.getDetail({
+        const userRes = await befly.db.getOne({
             table: "user",
-            columns: ["id", "email", "nickname", "avatar", "phone", "gender", "birthday", "bio", "role", "createdAt"],
-            where: { id: ctx.user.userId }
+            fields: ["id", "email", "nickname", "avatar", "phone", "gender", "birthday", "bio", "role", "createdAt"],
+            where: { id: ctx.user?.id }
         });
 
+        const user = userRes.data;
+
         if (!user?.id) {
-            return No("用户不存在");
+            return befly.tool.No("用户不存在");
         }
 
-        return Yes("获取成功", user);
+        return befly.tool.Yes("获取成功", user);
     }
 } as ApiRoute;
 ```
@@ -208,16 +212,16 @@ export default {
         if (ctx.body.bio !== undefined) updateData.bio = ctx.body.bio;
 
         if (Object.keys(updateData).length === 0) {
-            return No("没有需要更新的字段");
+            return befly.tool.No("没有需要更新的字段");
         }
 
         await befly.db.updData({
             table: "user",
             data: updateData,
-            where: { id: ctx.user.userId }
+            where: { id: ctx.user?.id }
         });
 
-        return Yes("更新成功");
+        return befly.tool.Yes("更新成功");
     }
 } as ApiRoute;
 ```
@@ -240,20 +244,22 @@ export default {
     required: ["oldPassword", "newPassword"],
     handler: async (befly, ctx) => {
         // 获取用户密码
-        const user = await befly.db.getDetail({
+        const userRes = await befly.db.getOne({
             table: "user",
-            columns: ["id", "password"],
-            where: { id: ctx.user.userId }
+            fields: ["id", "password"],
+            where: { id: ctx.user?.id }
         });
 
+        const user = userRes.data;
+
         if (!user?.id) {
-            return No("用户不存在");
+            return befly.tool.No("用户不存在");
         }
 
         // 验证原密码
         const isValid = await befly.cipher.verifyPassword(ctx.body.oldPassword, user.password);
         if (!isValid) {
-            return No("原密码错误");
+            return befly.tool.No("原密码错误");
         }
 
         // 加密新密码
@@ -263,10 +269,10 @@ export default {
         await befly.db.updData({
             table: "user",
             data: { password: hashedPassword },
-            where: { id: ctx.user.userId }
+            where: { id: ctx.user?.id }
         });
 
-        return Yes("密码修改成功");
+        return befly.tool.Yes("密码修改成功");
     }
 } as ApiRoute;
 ```
@@ -310,14 +316,14 @@ export default {
 
         const result = await befly.db.getList({
             table: "user",
-            columns: ["id", "email", "nickname", "avatar", "phone", "role", "state", "loginCount", "lastLoginAt", "createdAt"],
+            fields: ["id", "email", "nickname", "avatar", "phone", "role", "state", "loginCount", "lastLoginAt", "createdAt"],
             where: where,
             page: page || 1,
             limit: limit || 20,
-            orderBy: { id: "desc" }
+            orderBy: ["id#DESC"]
         });
 
-        return Yes("获取成功", result);
+        return befly.tool.Yes("获取成功", result.data);
     }
 } as ApiRoute;
 ```
@@ -398,7 +404,7 @@ export default {
                 cover: cover || "",
                 categoryId: categoryId || 0,
                 tags: tags || [],
-                authorId: ctx.user.userId,
+                authorId: ctx.user?.id,
                 publishedAt: Date.now()
             }
         });
@@ -412,7 +418,7 @@ export default {
             });
         }
 
-        return Yes("发布成功", { id: result.insertId });
+        return befly.tool.Yes("发布成功", { id: result.data });
     }
 } as ApiRoute;
 ```
@@ -442,19 +448,21 @@ export default {
         const { id, title, content, summary, cover, categoryId, tags } = ctx.body;
 
         // 检查文章是否存在
-        const article = await befly.db.getDetail({
+        const articleRes = await befly.db.getOne({
             table: "article",
-            columns: ["id", "authorId", "categoryId"],
+            fields: ["id", "authorId", "categoryId"],
             where: { id: id }
         });
 
+        const article = articleRes.data;
+
         if (!article?.id) {
-            return No("文章不存在");
+            return befly.tool.No("文章不存在");
         }
 
         // 检查权限（只能编辑自己的文章，管理员除外）
-        if (article.authorId !== ctx.user.userId && ctx.user.role !== "admin") {
-            return No("没有权限编辑此文章");
+        if (article.authorId !== ctx.user?.id && ctx.user?.role !== "admin") {
+            return befly.tool.No("没有权限编辑此文章");
         }
 
         const updateData: Record<string, any> = {};
@@ -466,7 +474,7 @@ export default {
         if (tags !== undefined) updateData.tags = tags;
 
         if (Object.keys(updateData).length === 0) {
-            return No("没有需要更新的字段");
+            return befly.tool.No("没有需要更新的字段");
         }
 
         await befly.db.updData({
@@ -493,7 +501,7 @@ export default {
             }
         }
 
-        return Yes("更新成功");
+        return befly.tool.Yes("更新成功");
     }
 } as ApiRoute;
 ```
@@ -514,19 +522,21 @@ export default {
     },
     required: ["id"],
     handler: async (befly, ctx) => {
-        const article = await befly.db.getDetail({
+        const articleRes = await befly.db.getOne({
             table: "article",
-            columns: ["id", "authorId", "categoryId"],
+            fields: ["id", "authorId", "categoryId"],
             where: { id: ctx.body.id }
         });
 
+        const article = articleRes.data;
+
         if (!article?.id) {
-            return No("文章不存在");
+            return befly.tool.No("文章不存在");
         }
 
         // 检查权限
-        if (article.authorId !== ctx.user.userId && ctx.user.role !== "admin") {
-            return No("没有权限删除此文章");
+        if (article.authorId !== ctx.user?.id && ctx.user?.role !== "admin") {
+            return befly.tool.No("没有权限删除此文章");
         }
 
         // 软删除
@@ -544,7 +554,7 @@ export default {
             });
         }
 
-        return Yes("删除成功");
+        return befly.tool.Yes("删除成功");
     }
 } as ApiRoute;
 ```
@@ -585,20 +595,20 @@ export default {
         }
 
         // 排序
-        let order: Record<string, "asc" | "desc"> = { isTop: "desc", publishedAt: "desc" };
-        if (orderBy === "views") order = { viewCount: "desc" };
-        if (orderBy === "likes") order = { likeCount: "desc" };
+        let orderByList: string[] = ["isTop#DESC", "publishedAt#DESC"];
+        if (orderBy === "views") orderByList = ["viewCount#DESC"];
+        if (orderBy === "likes") orderByList = ["likeCount#DESC"];
 
         const result = await befly.db.getList({
             table: "article",
-            columns: ["id", "title", "summary", "cover", "categoryId", "tags", "authorId", "viewCount", "likeCount", "commentCount", "isTop", "isRecommend", "publishedAt"],
+            fields: ["id", "title", "summary", "cover", "categoryId", "tags", "authorId", "viewCount", "likeCount", "commentCount", "isTop", "isRecommend", "publishedAt"],
             where: where,
             page: page || 1,
             limit: limit || 10,
-            orderBy: order
+            orderBy: orderByList
         });
 
-        return Yes("获取成功", result);
+        return befly.tool.Yes("获取成功", result.data);
     }
 } as ApiRoute;
 ```
@@ -619,13 +629,15 @@ export default {
     },
     required: ["id"],
     handler: async (befly, ctx) => {
-        const article = await befly.db.getDetail({
+        const articleRes = await befly.db.getOne({
             table: "article",
             where: { id: ctx.body.id, state: 1 }
         });
 
+        const article = articleRes.data;
+
         if (!article?.id) {
-            return No("文章不存在");
+            return befly.tool.No("文章不存在");
         }
 
         // 增加浏览量
@@ -636,25 +648,41 @@ export default {
         });
 
         // 获取作者信息
-        const author = await befly.db.getDetail({
+        const authorRes = await befly.db.getOne({
             table: "user",
-            columns: ["id", "nickname", "avatar"],
+            fields: ["id", "nickname", "avatar"],
             where: { id: article.authorId }
         });
 
+        const author = authorRes.data;
+
         // 获取分类信息
         let category = null;
         if (article.categoryId) {
-            category = await befly.db.getDetail({
+            const categoryRes = await befly.db.getOne({
                 table: "category",
-                columns: ["id", "name", "slug"],
+                fields: ["id", "name", "slug"],
                 where: { id: article.categoryId }
             });
+
+            category = categoryRes.data;
         }
 
-        return Yes("获取成功", {
-            ...article,
-            viewCount: article.viewCount + 1,
+        return befly.tool.Yes("获取成功", {
+            id: article.id,
+            title: article.title,
+            content: article.content,
+            summary: article.summary,
+            cover: article.cover,
+            categoryId: article.categoryId,
+            tags: article.tags,
+            authorId: article.authorId,
+            viewCount: (article.viewCount || 0) + 1,
+            likeCount: article.likeCount,
+            commentCount: article.commentCount,
+            isTop: article.isTop,
+            isRecommend: article.isRecommend,
+            publishedAt: article.publishedAt,
             author: author,
             category: category
         });
@@ -684,18 +712,18 @@ export default {
         const file = formData.get("file") as File | null;
 
         if (!file) {
-            return No("请选择文件");
+            return befly.tool.No("请选择文件");
         }
 
         // 检查文件大小（10MB）
         if (file.size > 10 * 1024 * 1024) {
-            return No("文件大小不能超过 10MB");
+            return befly.tool.No("文件大小不能超过 10MB");
         }
 
         // 检查文件类型
         const allowedTypes = ["image/jpeg", "image/png", "image/gif", "image/webp"];
         if (!allowedTypes.includes(file.type)) {
-            return No("只支持 jpg/png/gif/webp 格式");
+            return befly.tool.No("只支持 jpg/png/gif/webp 格式");
         }
 
         // 生成文件名
@@ -716,7 +744,7 @@ export default {
         // 返回 URL
         const url = `/uploads/${new Date().toISOString().slice(0, 7)}/${fileName}`;
 
-        return Yes("上传成功", {
+        return befly.tool.Yes("上传成功", {
             url: url,
             name: file.name,
             size: file.size,
@@ -746,7 +774,7 @@ export default {
         // 获取所有用户
         const result = await befly.db.getList({
             table: "user",
-            columns: ["id", "email", "nickname", "phone", "role", "state", "createdAt"],
+            fields: ["id", "email", "nickname", "phone", "role", "state", "createdAt"],
             where: { state: { $gte: 0 } },
             page: 1,
             limit: 10000
@@ -754,7 +782,7 @@ export default {
 
         // 生成 CSV
         const headers = ["ID", "邮箱", "昵称", "手机号", "角色", "状态", "注册时间"];
-        const rows = result.list.map((user: any) => [user.id, user.email, user.nickname, user.phone || "", user.role, user.state === 1 ? "正常" : "禁用", new Date(user.createdAt).toLocaleString()]);
+        const rows = result.data.lists.map((user: any) => [user.id, user.email, user.nickname, user.phone || "", user.role, user.state === 1 ? "正常" : "禁用", new Date(user.createdAt).toLocaleString()]);
 
         const csv = [headers.join(","), ...rows.map((row: any[]) => row.map((cell) => `"${cell}"`).join(","))].join("\n");
 
@@ -794,43 +822,49 @@ if (Object.keys(updateData).length === 0) {
 await befly.db.updData({
     table: "user",
     data: updateData,
-    where: { id: ctx.user.userId }
+    where: { id: ctx.user?.id }
 });
 ```
 
 #### 优化写法（简洁）
 
 ```typescript
-// ✅ 直接传入，undefined 值自动过滤
-const { nickname, avatar, phone, gender, birthday, bio } = ctx.body;
+import { fieldClear } from "befly/utils/fieldClear";
 
-const data = { nickname: nickname, avatar: avatar, phone: phone, gender: gender, birthday: birthday, bio: bio };
-
-// 使用 cleanFields 检查是否有有效数据
-const cleanData = befly.tool.cleanFields(data);
+// ✅ 直接传入，undefined 值自动过滤
+const data = {
+    nickname: ctx.body.nickname,
+    avatar: ctx.body.avatar,
+    phone: ctx.body.phone,
+    gender: ctx.body.gender,
+    birthday: ctx.body.birthday,
+    bio: ctx.body.bio
+};
+
+// 使用 fieldClear 检查是否有有效数据
+const cleanData = fieldClear(data, { excludeValues: [null, undefined] });
 if (Object.keys(cleanData).length === 0) {
-    return No("没有需要更新的字段");
+    return befly.tool.No("没有需要更新的字段");
 }
 
 await befly.db.updData({
     table: "user",
     data: cleanData,
-    where: { id: ctx.user.userId }
+    where: { id: ctx.user?.id }
 });
 ```
 
-### 使用 cleanFields 进行精细控制
+### 使用 fieldClear 进行精细控制
 
-当需要保留特定值（如 0、空字符串）时，使用 `cleanFields` 的高级参数：
+当需要保留特定值（如 0、空字符串）时，使用 `fieldClear` 的高级参数：
 
 ```typescript
 const { nickname, sort, state, remark } = ctx.body;
 
 // 保留 0 值（sort 和 state 允许为 0）
-const data = befly.tool.cleanFields(
+const data = fieldClear(
     { nickname: nickname, sort: sort, state: state, remark: remark },
-    [null, undefined], // 排除 null 和 undefined
-    { sort: true, state: true } // 保留这些字段的 0 值
+    { excludeValues: [null, undefined], keepMap: { sort: 0, state: 0 } }
 );
 
 await befly.db.updData({
@@ -850,7 +884,7 @@ const { keyword, state, categoryId, startDate, endDate } = ctx.body;
 
 const result = await befly.db.getList({
     table: "article",
-    columns: ["id", "title", "createdAt"],
+    fields: ["id", "title", "createdAt"],
     where: {
         state: state, // undefined 时忽略
         categoryId: categoryId, // undefined 时忽略

package/docs/guide/quickstart.md

@@ -87,26 +87,28 @@ export default {
     required: ["email", "password"],
     handler: async (befly, ctx) => {
         // 查询用户
-        const user = await befly.db.getDetail({
+        const userRes = await befly.db.getOne({
             table: "user",
-            columns: ["id", "email", "password", "nickname"],
+            fields: ["id", "email", "password", "nickname"],
             where: { email: ctx.body.email }
         });
 
+        const user = userRes.data;
+
         if (!user?.id) {
-            return No("用户不存在");
+            return befly.tool.No("用户不存在");
         }
 
         // 验证密码
         const isValid = await befly.cipher.verifyPassword(ctx.body.password, user.password);
         if (!isValid) {
-            return No("密码错误");
+            return befly.tool.No("密码错误");
         }
 
         // 签发令牌
-        const token = befly.jwt.sign({ userId: user.id });
+        const token = befly.jwt.sign({ id: user.id });
 
-        return Yes("登录成功", { token: token, user: { id: user.id, nickname: user.nickname } });
+        return befly.tool.Yes("登录成功", { token: token, user: { id: user.id, nickname: user.nickname } });
     }
 } as ApiRoute;
 ```

package/docs/plugins/database.md

@@ -1,128 +1,189 @@
-# Befly 数据库操作指南
+# Befly 数据库（DbHelper）
 
-> 本文档详细介绍 Befly 框架的数据库操作 API，包括 CRUD 操作、事务、条件查询等。
+本文档只描述 **当前实现**：所有数据库操作统一返回 `DbResult`（`{ data, sql }`），调用方必须读取 `.data`。
 
-## 目录
+## 核心约定：DbResult（必须读 data）
 
-- [核心概念](#核心概念)
-- [字段命名规范](#字段命名规范)
-- [查询方法](#查询方法)
-- [写入方法](#写入方法)
-- [数值操作](#数值操作)
-- [事务操作](#事务操作)
-- [多表联查](#多表联查)
-- [Where 条件语法](#where-条件语法)
-- [字段选择语法](#字段选择语法)
-- [排序语法](#排序语法)
-- [系统字段说明](#系统字段说明)
-- [完整示例](#完整示例)
+`DbHelper` 的所有方法都会返回：
 
----
+- `data`：你真正要用的结果
+- `sql`：本次执行的 SQL 信息（用于调试/排错）
 
-## 核心概念
+```js
+type DbResult<TData = any, TSql = SqlInfo> = {
+data: TData;
+sql: TSql;
+};
+
+```
+
+### SQL 信息（SqlInfo / ListSql）
 
-### DbHelper
+- 单条/写入类操作的 `sql` 为 `SqlInfo`：
+    - `sql`：SQL 字符串
+    - `params`：参数数组
+    - `duration`：耗时（毫秒）
+- 列表/全量查询的 `sql` 为 `ListSql`：
+    - `count`：统计 SQL（用于 total）
+    - `data?`：数据 SQL（当 total=0 时可能不会执行第二次查询）
 
-`DbHelper` 是 Befly 的数据库操作核心类，提供了完整的 CRUD 封装。通过 `befly.db` 访问。
+> 注意：不要把整个 `DbResult` 直接返回给客户端；应只返回 `result.data`。
+
+## 常用查询
+
+### getOne（单条）
 
 ```typescript
-// 在 API handler 中使用
-handler: async (befly, ctx) => {
-    const user = await befly.db.getOne({
-        table: "user",
-        where: { id: 1 }
-    });
-};
+const userRes = await befly.db.getOne({
+    table: "user",
+    fields: ["id", "email", "nickname"],
+    where: { id: ctx.user?.id }
+});
+
+const user = userRes.data;
+if (!user?.id) {
+    return befly.tool.No("用户不存在");
+}
+
+return befly.tool.Yes("获取成功", user);
 ```
 
-### 自动转换
-
-- **表名**：小驼峰 `userProfile` 自动转换为下划线 `user_profile`
-- **字段名**：写入时小驼峰转下划线，查询时下划线转小驼峰
-- **BIGINT 字段**：`id`、`*Id`、`*_id`、`*At`、`*_at` 自动转为 number
+### getList（分页）
 
-### 自动过滤 null 和 undefined
+```typescript
+const listRes = await befly.db.getList({
+    table: "user",
+    fields: ["id", "email", "nickname"],
+    where: { state: 1 },
+    page: 1,
+    limit: 20,
+    orderBy: ["id#DESC"]
+});
+
+return befly.tool.Yes("获取成功", listRes.data);
+// listRes.data: { lists, total, page, limit, pages }
+```
 
-所有写入方法（`insData`、`insBatch`、`updData`）和条件查询（`where`）都会**自动过滤值为 `null` 或 `undefined` 的字段**。
+### getAll（不分页，有上限保护）
 
----
+```typescript
+const allRes = await befly.db.getAll({
+    table: "user",
+    fields: ["id", "email"],
+    where: { state: 1 },
+    orderBy: ["createdAt#DESC"]
+});
+
+return befly.tool.Yes("获取成功", allRes.data);
+// allRes.data: { lists, total }
+```
 
-## 字段命名规范
+## 写入与返回值
 
-| 位置                  | 格式   | 示例                    |
-| --------------------- | ------ | ----------------------- |
-| 代码中（参数/返回值） | 小驼峰 | `userId`, `createdAt`   |
-| 数据库中              | 下划线 | `user_id`, `created_at` |
+### insData（插入单条）
 
----
+`insData` 返回插入的 ID（数值）：
 
-## 查询方法
+```typescript
+const idRes = await befly.db.insData({
+    table: "user",
+    data: {
+        email: ctx.body.email,
+        nickname: ctx.body.nickname
+    }
+});
+
+return befly.tool.Yes("创建成功", { id: idRes.data });
+```
 
-- `getOne`：查询单条
-- `getList`：分页查询
-- `getAll`：查询全部（有上限保护）
-- `getCount`：查询数量
-- `exists`：检查存在
-- `getFieldValue`：查询单字段
+### updData / delData
 
----
+`updData` / `delData` 返回影响行数（数值）：
 
-## 写入方法
+```typescript
+const updRes = await befly.db.updData({
+    table: "user",
+    data: { nickname: ctx.body.nickname },
+    where: { id: ctx.user?.id }
+});
 
-- `insData`：插入单条（自动生成系统字段）
-- `insBatch`：批量插入
-- `updData`：更新（自动更新 `updated_at`）
-- `delData`：软删除
-- `delForce`：硬删除
-- `disableData` / `enableData`：禁用/启用
+return befly.tool.Yes("更新成功", { changed: updRes.data });
+```
 
----
+### insBatch（批量插入）
 
-## 数值操作
+`insBatch` 返回插入的 ID 列表：
 
-- `increment`：自增
-- `decrement`：自减
+```typescript
+const idsRes = await befly.db.insBatch("user", [
+    { email: "a@qq.com", nickname: "A" },
+    { email: "b@qq.com", nickname: "B" }
+]);
 
----
+return befly.tool.Yes("导入成功", { ids: idsRes.data });
+```
 
-## 事务操作
+## 字段/排序
 
-使用 `trans` 方法执行事务，自动处理 commit/rollback。
+### fields（字段选择）
 
----
+- 不传或 `[]`：查询所有字段
+- 仅包含字段：`["id", "email"]`
+- 仅排除字段：`["!password"]`
 
-## 多表联查
+> 禁止混用包含与排除。
 
-查询方法支持通过 `joins` 参数进行多表联查。
+### orderBy（排序）
 
----
+格式：`"字段#ASC" | "字段#DESC"`，例如：`["id#DESC"]`。
 
-## Where 条件语法
+## null/undefined 自动过滤
 
-支持 `$or/$and` 与 `$gt/$gte/$lt/$lte/$in/$between/$null/$like` 等。
+DbHelper 在写入（`insData/insBatch/updData`）以及查询条件（`where`）中，会自动过滤 `null/undefined`。
 
----
+如果你希望在业务侧更精细控制（例如：保留 `0` / 空字符串），请使用 `fieldClear`：
 
-## 字段选择语法
+```typescript
+import { fieldClear } from "befly/utils/fieldClear";
 
-- `fields: []` / 不传：查询所有字段
-- `fields: ["id", "name"]`：指定字段
-- `fields: ["!password"]`：排除字段（不能混用包含与排除）
+const data = fieldClear(
+    { nickname: ctx.body.nickname, sort: ctx.body.sort, state: ctx.body.state },
+    { excludeValues: [null, undefined], keepMap: { sort: 0, state: 0 } }
+);
+```
 
----
+## 事务（trans）
 
-## 排序语法
+````typescript
+const out = await befly.db.trans(async (trx) => {
+    const idRes = await trx.insData({
+        table: "order",
+        data: { userId: ctx.user?.id, status: "pending" }
+    });
+    return { orderId: idRes.data };
+});
 
-使用 `字段#方向` 格式：`ASC` / `DESC`。
+return befly.tool.Yes("创建成功", out);
 
----
+## 原生 SQL（query / unsafe）
 
-## 系统字段说明
+```typescript
+const r = await befly.db.query("SELECT 1 AS cnt");
+return befly.tool.Yes("ok", r.data);
+````
 
-每条记录自动包含：`id`、`created_at`、`updated_at`、`deleted_at`、`state`。
+`unsafe` 用于内部脚本/同步逻辑（行为与 `query` 相同，返回 `DbResult`）。
 
----
+## 错误定位：error.sqlInfo
 
-## 完整示例
+当 SQL 执行失败，抛出的错误对象会带 `sqlInfo`：
 
-更完整示例与细节说明请参考仓库中的 `DbHelper` 相关测试用例与源码实现。
+```typescript
+try {
+    await befly.db.query("SELECT * FROM not_exists");
+} catch (error: any) {
+    // error.sqlInfo: { sql, params, duration }
+    befly.logger.error({ sqlInfo: error?.sqlInfo }, "SQL 执行失败");
+    throw error;
+}
+```

package/docs/plugins/plugin.md

@@ -263,16 +263,20 @@ const dbPlugin: Plugin = {
 
 ```typescript
 // 查询
-const user = await befly.db.getOne({ table: "user", where: { id: 1 } });
+const userRes = await befly.db.getOne({ table: "user", where: { id: 1 } });
+const user = userRes.data;
 
 // 插入
-const id = await befly.db.insData({ table: "user", data: { name: "张三" } });
+const idRes = await befly.db.insData({ table: "user", data: { name: "张三" } });
+const id = idRes.data;
 
 // 更新
-await befly.db.updData({ table: "user", data: { name: "李四" }, where: { id: 1 } });
+const updRes = await befly.db.updData({ table: "user", data: { name: "李四" }, where: { id: 1 } });
+const changed = updRes.data;
 
 // 删除
-await befly.db.delData({ table: "user", where: { id: 1 } });
+const delRes = await befly.db.delData({ table: "user", where: { id: 1 } });
+const deleted = delRes.data;
 ```
 
 > 详细用法请参考 [database.md](./database.md)

package/docs/reference/addon.md

@@ -280,12 +280,14 @@ export default {
     required: ["email", "password"],
     handler: async (befly, ctx) => {
         // 使用 addon 表时需要完整表名
-        const admin = await befly.db.getDetail({
+        const adminRes = await befly.db.getOne({
             table: "addon_admin_admin",
-            columns: ["id", "email", "password", "nickname"],
+            fields: ["id", "email", "password", "nickname"],
             where: { email: ctx.body.email }
         });
 
+        const admin = adminRes.data;
+
         // ... 业务逻辑
 
         return Yes("登录成功", { token: token });
@@ -325,7 +327,7 @@ export default {
 // 使用完整表名
 await befly.db.getList({
     table: "addon_admin_role", // addon_{name}_{table}
-    columns: ["id", "name", "code"]
+    fields: ["id", "name", "code"]
 });
 ```
 

package/docs/reference/table.md

@@ -535,7 +535,7 @@ await syncTable(ctx, sources.tables);
    └─ 保留字段检查
 
 2. 建立数据库连接
-   └─ 检查数据库版本（MySQL 8+, PostgreSQL 17+）
+    └─ 检查数据库版本（MySQL 8+, PostgreSQL 17+, SQLite 3.50+）
 
 3. 扫描表定义文件
    ├─ 项目 tables 目录

package/docs/reference/validator.md

@@ -589,30 +589,32 @@ A: 数组类型会验证：
 
 ### Q: 如何在验证前清理数据中的 null/undefined 值？
 
-A: 使用 `befly.tool.cleanFields` 方法：
+A: 使用 `fieldClear` 工具函数：
 
 ```typescript
+import { fieldClear } from "befly/utils/fieldClear";
+
 // 在 API handler 中使用
 handler: async (befly, ctx) => {
     const { nickname, phone, address } = ctx.body;
 
     // 清理 null 和 undefined 值
-    const cleanData = befly.tool.cleanFields({
+    const cleanData = fieldClear({
         nickname: nickname,
         phone: phone,
         address: address
-    });
+    }, { excludeValues: [null, undefined] });
 
     // cleanData 只包含有效值
     await befly.db.updData({
         table: "user",
         data: cleanData,
-        where: { id: ctx.user.userId }
+        where: { id: ctx.user?.id }
     });
 
     return Yes("更新成功");
 };
 ```
 
-> **注意**：数据库操作（insData、updData 等）会自动过滤 null/undefined 值，通常不需要手动调用 cleanFields。
+> **注意**：数据库操作（insData、updData 等）会自动过滤 null/undefined 值，通常不需要手动调用 fieldClear。
 > 详见 [database.md](../plugins/database.md#nullundefined-值自动过滤)。

package/package.json

@@ -1,7 +1,7 @@
 {
     "name": "befly",
-    "version": "3.10.14",
-    "gitHead": "c758a3e8a78966ac35043989fd80cf377ad96006",
+    "version": "3.10.16",
+    "gitHead": "f5d17c019a58e82cfacec5ce3a1f04e3225ba838",
     "private": false,
     "description": "Befly - 为 Bun 专属打造的 TypeScript API 接口框架核心引擎",
     "keywords": [
@@ -59,10 +59,10 @@
     },
     "scripts": {
         "test": "bun test",
-        "typecheck": "bunx tsgo --noEmit"
+        "typecheck": "tsc --noEmit"
     },
     "dependencies": {
-        "befly-shared": "^1.3.8",
+        "befly-shared": "^1.3.9",
         "chalk": "^5.6.2",
         "es-toolkit": "^1.43.0",
         "fast-jwt": "^6.1.0",

package/docs/quickstart.md

@@ -1,8 +0,0 @@
-# Quickstart 快速入门（已迁移）
-
-为避免重复内容长期漂移，本 Quickstart 已迁移到权威入口：
-
-- `packages/core/docs/guide/quickstart.md`
-- 在线阅读：[`./guide/quickstart.md`](./guide/quickstart.md)
-
-如你从旧链接跳转到这里，请以 `guide/quickstart.md` 的内容为准（配置字段、同步流程、权限 pathname 规则等都以当前实现为准）。