befly-tpl 3.9.49 → 3.9.50

package/README.md

@@ -37,12 +37,14 @@ bunx befly init
 
 ```typescript
 // main.ts
-import { Server } from 'befly';
+import { Befly } from 'befly';
 
-await Server({
-    name: 'My API',
-    port: 3000
+const app = new Befly({
+    appName: 'My API',
+    appPort: 3000
 });
+
+await app.start();
 ```
 
 运行项目：
@@ -55,7 +57,7 @@ bun run main.ts
 
 ```typescript
 // apis/user/hello.ts
-import type { ApiRoute } from 'befly';
+import type { ApiRoute } from 'befly/types/index';
 
 export default {
     name: '问候接口',
@@ -79,7 +81,7 @@ export default {
 ### TypeScript 全面支持
 
 ```typescript
-import type { ApiRoute, BeflyContext } from 'befly';
+import type { ApiRoute, BeflyContext } from 'befly/types/index';
 import type { User } from './types/models';
 
 export default {

package/apis/test/typedExample.ts

@@ -0,0 +1,150 @@
+/**
+ * DbHelper 泛型类型使用示例
+ *
+ * 本文件演示如何使用类型安全的数据库操作
+ * 通过扩展 DatabaseTables 接口，可以获得完整的类型推断和智能提示
+ */
+
+import type { BaseTable, TypedWhereConditions } from 'befly/types/table';
+
+// ============================================
+// 步骤 1: 定义表类型
+// ============================================
+
+/**
+ * 用户表类型定义
+ * 只需定义业务字段，系统字段（id, state, createdAt 等）由 BaseTable 自动添加
+ */
+interface UserFields {
+    email: string;
+    username: string;
+    password: string;
+    nickname: string | null;
+    avatar: string | null;
+    roleId: number;
+    lastLoginAt: number | null;
+}
+
+/**
+ * 完整的用户表类型（包含系统字段）
+ */
+type UserTable = BaseTable<UserFields>;
+
+// ============================================
+// 步骤 2: 扩展 DatabaseTables（可选，推荐）
+// ============================================
+
+/**
+ * 在项目的 types/index.d.ts 中添加以下声明：
+ *
+ * declare module 'befly/types/table' {
+ *   interface DatabaseTables {
+ *     user: BaseTable<{
+ *       email: string;
+ *       username: string;
+ *       password: string;
+ *       nickname: string | null;
+ *       avatar: string | null;
+ *       roleId: number;
+ *       lastLoginAt: number | null;
+ *     }>;
+ *   }
+ * }
+ *
+ * 扩展后，db.getOne({ table: 'user' }) 的返回类型会自动推断
+ */
+
+// ============================================
+// 步骤 3: 在 API 中使用类型安全的数据库操作
+// ============================================
+
+export default {
+    name: '类型安全示例',
+    auth: false,
+    handler: async (befly, ctx) => {
+        // ----------------------------------------
+        // 示例 1: 类型安全的 WHERE 条件
+        // ----------------------------------------
+
+        // 定义类型安全的查询条件
+        const where: TypedWhereConditions<UserTable> = {
+            state: 1, // 精确匹配
+            roleId$in: [1, 2, 3], // IN 数组（必须是 number[]）
+            email$like: '%@gmail.com', // LIKE 匹配（必须是 string）
+            lastLoginAt$gte: Date.now() - 86400000 // 大于等于（必须是 number）
+            // roleId$in: 'invalid',               // ❌ 类型错误：应为 number[]
+            // email$like: 123,                    // ❌ 类型错误：应为 string
+        };
+
+        // ----------------------------------------
+        // 示例 2: 使用泛型指定返回类型
+        // ----------------------------------------
+
+        // 方式 A: 手动指定泛型
+        const user = await befly.db.getOne<UserTable>({
+            table: 'user',
+            where: { id: ctx.body.id }
+        });
+
+        if (user) {
+            // 有完整的类型提示
+            const email = user.email; // string
+            const createdAt = user.createdAt; // number（系统字段）
+            const nickname = user.nickname; // string | null
+        }
+
+        // ----------------------------------------
+        // 示例 3: 类型安全的列表查询
+        // ----------------------------------------
+
+        const result = await befly.db.getList<UserTable>({
+            table: 'user',
+            fields: ['id', 'email', 'nickname', 'createdAt'],
+            where: where,
+            orderBy: ['createdAt#DESC'],
+            page: 1,
+            limit: 10
+        });
+
+        // result.lists 类型为 UserTable[]
+        for (const item of result.lists) {
+            // 完整的类型提示
+            console.log(item.email, item.createdAt);
+        }
+
+        // ----------------------------------------
+        // 示例 4: 复杂 WHERE 条件（$or, $and）
+        // ----------------------------------------
+
+        const complexWhere: TypedWhereConditions<UserTable> = {
+            state: 1,
+            $or: [{ email$like: '%@gmail.com' }, { email$like: '%@qq.com' }],
+            $and: [{ roleId$in: [1, 2] }, { lastLoginAt$notNull: true }]
+        };
+
+        const activeUsers = await befly.db.getAll<UserTable>({
+            table: 'user',
+            where: complexWhere,
+            orderBy: ['lastLoginAt#DESC']
+        });
+
+        // ----------------------------------------
+        // 示例 5: BETWEEN 范围查询
+        // ----------------------------------------
+
+        const rangeWhere: TypedWhereConditions<UserTable> = {
+            state: 1,
+            createdAt$between: [
+                Date.now() - 7 * 86400000, // 7天前
+                Date.now() // 现在
+            ],
+            roleId$between: [1, 10] // 角色 ID 1-10
+        };
+
+        return befly.tool.Yes('类型安全示例', {
+            user: user,
+            total: result.total,
+            activeCount: activeUsers.length
+        });
+    }
+};

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "befly-tpl",
-    "version": "3.9.49",
+    "version": "3.9.50",
     "description": "Befly 3.0 TypeScript Template",
     "private": false,
     "publishConfig": {
@@ -28,11 +28,11 @@
     ],
     "type": "module",
     "dependencies": {
-        "@befly-addon/admin": "^1.0.54",
-        "befly": "^3.8.29"
+        "@befly-addon/admin": "^1.0.55",
+        "befly": "^3.8.30"
     },
     "engines": {
         "bun": ">=1.3.0"
     },
-    "gitHead": "1f3cacbe4134ee60654b75338bcaeda535898a84"
+    "gitHead": "2031550167896390ac58c50aeb52b8c23426844e"
 }