befly 3.9.13 → 3.9.21

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/api.md

@@ -24,7 +24,7 @@
         - [ErrorResponse - Hook 中断响应](#errorresponse---hook-中断响应)
         - [FinalResponse - 最终响应](#finalresponse---最终响应)
     - [字段定义与验证](#字段定义与验证)
-        - [默认字段](#默认字段)
+        - [预定义字段](#预定义字段)
         - [字段定义格式](#字段定义格式)
         - [字段类型](#字段类型)
         - [验证规则](#验证规则)
@@ -308,37 +308,39 @@ ctx.response = ErrorResponse(ctx, '未授权', 1, null);
 
 ## 字段定义与验证
 
-### 默认字段
+### 预定义字段
 
-所有 API 自动包含以下默认字段，无需重复定义：
+框架提供了一套预定义字段系统，通过 `@` 符号引用常用字段，避免重复定义。
+
+#### 可用预定义字段
 
 ```typescript
-const DEFAULT_API_FIELDS = {
-    id: {
+const PRESET_FIELDS = {
+    '@id': {
         name: 'ID',
         type: 'number',
         min: 1,
         max: null
     },
-    page: {
+    '@page': {
         name: '页码',
         type: 'number',
         min: 1,
         max: 9999
     },
-    limit: {
+    '@limit': {
         name: '每页数量',
         type: 'number',
         min: 1,
         max: 100
     },
-    keyword: {
+    '@keyword': {
         name: '关键词',
         type: 'string',
         min: 1,
         max: 50
     },
-    state: {
+    '@state': {
         name: '状态',
         type: 'number',
         min: 0,
@@ -347,6 +349,192 @@ const DEFAULT_API_FIELDS = {
 };
 ```
 
+#### 预定义字段说明
+
+| 字段       | 类型     | 范围      | 说明                                 |
+| ---------- | -------- | --------- | ------------------------------------ |
+| `@id`      | `number` | >= 1      | 通用 ID 字段，用于详情/删除等        |
+| `@page`    | `number` | 1-9999    | 分页页码，默认从 1 开始              |
+| `@limit`   | `number` | 1-100     | 每页数量，最大 100 条                |
+| `@keyword` | `string` | 1-50 字符 | 搜索关键词                           |
+| `@state`   | `number` | 0-2       | 状态字段（0=软删除，1=正常，2=禁用） |
+
+#### 使用方式
+
+在 `fields` 中使用 `@` 符号引用预定义字段：
+
+```typescript
+// 方式一：直接字符串引用
+fields: {
+    id: '@id',
+    page: '@page',
+    limit: '@limit',
+    keyword: '@keyword',
+    state: '@state'
+}
+
+// 方式二：与自定义字段混用
+fields: {
+    page: '@page',
+    limit: '@limit',
+    categoryId: { name: '分类ID', type: 'number', min: 0 }
+}
+```
+
+#### 加载机制
+
+1. **按需引用**：只有在 `fields` 中显式声明的预定义字段才会生效
+2. **自动替换**：在 API 加载时，`@` 引用会被自动替换为完整的字段定义
+3. **验证生效**：引用的预定义字段会自动应用验证规则
+
+#### 使用预定义字段示例
+
+**列表查询接口**
+
+```typescript
+// apis/article/list.ts
+export default {
+    name: '文章列表',
+    auth: true,
+    fields: {
+        page: '@page',
+        limit: '@limit',
+        keyword: '@keyword',
+        state: '@state',
+        categoryId: { name: '分类ID', type: 'number', min: 0 }
+    },
+    handler: async (befly, ctx) => {
+        const { page, limit, keyword, categoryId } = ctx.body;
+
+        const where: Record<string, any> = { state: 1 };
+        if (categoryId) where.categoryId = categoryId;
+        if (keyword) where.title = { $like: `%${keyword}%` };
+
+        const result = await befly.db.getList({
+            table: 'article',
+            columns: ['id', 'title', 'summary', 'createdAt'],
+            where: where,
+            page: page || 1,
+            limit: limit || 10,
+            orderBy: { id: 'desc' }
+        });
+
+        return befly.tool.Yes('获取成功', result);
+    }
+} as ApiRoute;
+```
+
+**详情/删除接口**
+
+```typescript
+// apis/article/detail.ts
+export default {
+    name: '文章详情',
+    auth: false,
+    fields: {
+        id: '@id'
+    },
+    required: ['id'],
+    handler: async (befly, ctx) => {
+        const article = await befly.db.getDetail({
+            table: 'article',
+            where: { id: ctx.body.id, state: 1 }
+        });
+
+        if (!article?.id) {
+            return befly.tool.No('文章不存在');
+        }
+
+        return befly.tool.Yes('获取成功', article);
+    }
+} as ApiRoute;
+```
+
+```typescript
+// apis/article/delete.ts
+export default {
+    name: '删除文章',
+    auth: true,
+    fields: {
+        id: '@id'
+    },
+    required: ['id'],
+    handler: async (befly, ctx) => {
+        await befly.db.delData({
+            table: 'article',
+            where: { id: ctx.body.id }
+        });
+
+        return befly.tool.Yes('删除成功');
+    }
+} as ApiRoute;
+```
+
+#### 覆盖预定义字段
+
+如需修改预定义字段的验证规则，在 `fields` 中重新定义即可：
+
+```typescript
+export default {
+    name: '大数据列表',
+    fields: {
+        page: '@page',
+        // 覆盖默认的 @limit，允许更大的分页
+        limit: {
+            name: '每页数量',
+            type: 'number',
+            min: 1,
+            max: 500 // 修改最大值为 500
+        }
+    },
+    handler: async (befly, ctx) => {
+        // ctx.body.limit 最大可以是 500
+        return befly.tool.Yes('获取成功');
+    }
+} as ApiRoute;
+```
+
+#### 预定义字段最佳实践
+
+**推荐使用场景**
+
+| API 类型 | 推荐字段                            | 说明               |
+| -------- | ----------------------------------- | ------------------ |
+| 列表查询 | `page`, `limit`, `keyword`, `state` | 完整的查询字段组合 |
+| 获取详情 | `id`                                | 只需 ID 参数       |
+| 删除操作 | `id`                                | 只需 ID 参数       |
+| 更新操作 | `id` + 表字段                       | ID + 业务字段      |
+| 添加操作 | 表字段（无需预定义字段）            | 只需业务字段       |
+
+**使用建议**
+
+```typescript
+// ✅ 推荐：列表查询使用完整预定义字段
+fields: {
+    page: '@page',
+    limit: '@limit',
+    keyword: '@keyword',
+    state: '@state'
+}
+
+// ✅ 推荐：详情/删除只使用 id
+fields: {
+    id: '@id'
+}
+
+// ✅ 推荐：更新接口混用预定义和表字段
+fields: {
+    id: '@id',
+    ...articleTable
+}
+
+// ❌ 避免：添加接口不需要预定义字段
+fields: {
+    page: '@page', // 添加操作不需要分页
+    ...articleTable
+}
+```
+
 ### 字段定义格式
 
 ```typescript
@@ -838,6 +1026,52 @@ interface BeflyContext {
 }
 ```
 
+### 常用工具方法
+
+#### befly.db.cleanFields - 清理数据字段
+
+清理对象中的 `null` 和 `undefined` 值，适用于处理可选参数：
+
+```typescript
+// 方法签名
+befly.db.cleanFields<T>(
+    data: T,                           // 要清理的数据对象
+    excludeValues?: any[],             // 要排除的值，默认 [null, undefined]
+    keepValues?: Record<string, any>   // 强制保留的键值对
+): Partial<T>
+```
+
+**基本用法：**
+
+```typescript
+// 默认排除 null 和 undefined
+const cleanData = befly.db.cleanFields({
+    name: 'John',
+    age: null,
+    email: undefined,
+    phone: ''
+});
+// 结果: { name: 'John', phone: '' }
+```
+
+**自定义排除值：**
+
+```typescript
+// 同时排除 null、undefined 和空字符串
+const cleanData = befly.db.cleanFields({ name: 'John', phone: '', age: null }, [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 }
+```
+
+> **注意**：`insData`、`updData` 和 `where` 条件会自动调用 `cleanFields`，通常无需手动调用。
+
 ---
 
 ## 最佳实践
@@ -846,8 +1080,10 @@ interface BeflyContext {
 
 ```typescript
 fields: {
-    // 1. 首选：使用默认字段（id, page, limit, keyword, state）
-    // 无需定义，自动包含
+    // 1. 首选：使用预定义字段（@id, @page, @limit, @keyword, @state）
+    page: '@page',
+    limit: '@limit',
+    keyword: '@keyword',
 
     // 2. 次选：引用表字段
     email: adminTable.email,

package/docs/database.md

@@ -9,6 +9,12 @@
     - [核心概念](#核心概念)
         - [DbHelper](#dbhelper)
         - [自动转换](#自动转换)
+        - [自动过滤 null 和 undefined](#自动过滤-null-和-undefined)
+            - [写入时自动过滤](#写入时自动过滤)
+            - [更新时自动过滤](#更新时自动过滤)
+            - [Where 条件自动过滤](#where-条件自动过滤)
+            - [实际应用示例](#实际应用示例)
+            - [手动清理字段](#手动清理字段)
     - [字段命名规范](#字段命名规范)
     - [查询方法](#查询方法)
         - [getOne - 查询单条](#getone---查询单条)
@@ -79,6 +85,126 @@ handler: async (befly, ctx) => {
 - **字段名**：写入时小驼峰转下划线，查询时下划线转小驼峰
 - **BIGINT 字段**：`id`、`*Id`、`*_id`、`*At`、`*_at` 自动转为 number
 
+### 自动过滤 null 和 undefined
+
+所有写入方法（`insData`、`insBatch`、`updData`）和条件查询（`where`）都会**自动过滤值为 `null` 或 `undefined` 的字段**。
+
+这意味着：
+
+- 传入 `undefined` 或 `null` 的字段会被忽略，不会写入数据库
+- `where` 条件中值为 `undefined` 或 `null` 的条件会被忽略
+- 这使得处理可选参数变得非常简单，无需手动判断
+
+#### 写入时自动过滤
+
+```typescript
+// 用户提交的数据可能部分字段为空
+await befly.db.insData({
+    table: 'user',
+    data: {
+        username: 'john',
+        email: 'john@example.com',
+        phone: undefined, // ❌ 自动忽略，不会写入
+        avatar: null, // ❌ 自动忽略，不会写入
+        nickname: '' // ✅ 空字符串会写入（不是 null/undefined）
+    }
+});
+// 实际 SQL: INSERT INTO user (username, email, nickname, ...) VALUES ('john', 'john@example.com', '', ...)
+```
+
+#### 更新时自动过滤
+
+```typescript
+// 只更新用户提交的字段
+await befly.db.updData({
+    table: 'user',
+    data: {
+        nickname: ctx.body.nickname, // 如果用户传了值，会更新
+        avatar: ctx.body.avatar, // 如果为 undefined，自动忽略
+        bio: ctx.body.bio // 如果为 null，自动忽略
+    },
+    where: { id: ctx.user.id }
+});
+// 只有非 null/undefined 的字段会被更新
+```
+
+#### Where 条件自动过滤
+
+```typescript
+// 条件筛选：用户可能只传部分筛选条件
+const result = await befly.db.getList({
+    table: 'article',
+    where: {
+        categoryId: ctx.body.categoryId, // 如果未传，值为 undefined，自动忽略
+        status: ctx.body.status, // 如果未传，值为 undefined，自动忽略
+        authorId: ctx.body.authorId // 如果未传，值为 undefined，自动忽略
+    },
+    page: 1,
+    limit: 10
+});
+// 只有非 null/undefined 的条件会参与 WHERE 构建
+```
+
+#### 实际应用示例
+
+```typescript
+// API: 用户列表（带可选筛选条件）
+export default {
+    name: '用户列表',
+    fields: {
+        keyword: { name: '关键词', type: 'string', max: 50 },
+        roleId: { name: '角色ID', type: 'number' },
+        state: { name: '状态', type: 'number' }
+    },
+    handler: async (befly, ctx) => {
+        // 直接使用请求参数，无需判断是否存在
+        // null/undefined 的条件会被自动过滤
+        const result = await befly.db.getList({
+            table: 'user',
+            where: {
+                roleId: ctx.body.roleId, // 未传时为 undefined，自动忽略
+                state: ctx.body.state, // 未传时为 undefined，自动忽略
+                username$like: ctx.body.keyword ? `%${ctx.body.keyword}%` : undefined // 无关键词时忽略
+            },
+            page: ctx.body.page || 1,
+            limit: ctx.body.limit || 10
+        });
+
+        return befly.tool.Yes('查询成功', result);
+    }
+};
+```
+
+#### 手动清理字段
+
+如需手动清理数据，可以使用 `cleanFields` 方法：
+
+```typescript
+// 默认排除 null 和 undefined
+const cleanData = befly.db.cleanFields({
+    name: 'John',
+    age: null,
+    email: undefined,
+    phone: ''
+});
+// 结果: { name: 'John', phone: '' }
+
+// 自定义排除值（如同时排除空字符串）
+const cleanData2 = befly.db.cleanFields(
+    { name: 'John', phone: '', age: null },
+    [null, undefined, ''] // 排除这些值
+);
+// 结果: { name: 'John' }
+
+// 保留特定字段的特定值（即使在排除列表中）
+const cleanData3 = befly.db.cleanFields(
+    { name: 'John', status: null, count: 0 },
+    [null, undefined], // 排除 null 和 undefined
+    { status: null } // 但保留 status 字段的 null 值
+);
+// 结果: { name: 'John', status: null, count: 0 }
+```
+
 ---
 
 ## 字段命名规范
@@ -889,14 +1015,32 @@ orderBy: ['sort#ASC', 'id#DESC'];
 
 ### 默认 State 过滤
 
-所有查询方法默认添加 `state > 0` 条件，自动过滤已删除的数据。
+所有查询方法默认添加 `state > 0` 条件，**仅过滤软删除的数据（state=0）**。
+
+**过滤效果**：
+
+| state 值 | 默认查询结果        |
+| -------- | ------------------- |
+| 0        | ❌ 被过滤（软删除） |
+| 1        | ✅ 可查询（正常）   |
+| 2        | ✅ 可查询（禁用）   |
+
+> ⚠️ **注意**：禁用数据（state=2）默认**可以**查询到，如需过滤禁用数据，需显式指定 `state: 1`。
 
 ```typescript
-// 实际执行
+// 默认查询：state > 0，包含正常和禁用数据
 getOne({ table: 'user', where: { id: 1 } });
 // → WHERE id = 1 AND state > 0
 
-// 如需查询所有状态，显式指定 state 条件
+// 只查询正常状态的数据
+getList({ table: 'user', where: { state: 1 } });
+// → WHERE state = 1
+
+// 只查询禁用状态的数据
+getList({ table: 'user', where: { state: 2 } });
+// → WHERE state = 2
+
+// 查询所有状态（包括软删除）
 getOne({ table: 'user', where: { id: 1, state$gte: 0 } });
 // → WHERE id = 1 AND state >= 0
 ```

package/docs/examples.md

@@ -284,10 +284,10 @@ export default {
     auth: true,
     permission: 'user:list',
     fields: {
-        page: { name: '页码', type: 'number', min: 1, default: 1 },
-        limit: { name: '每页数量', type: 'number', min: 1, max: 100, default: 20 },
-        keyword: { name: '关键词', type: 'string', max: 50 },
-        state: { name: '状态', type: 'number', min: -1, max: 1 },
+        page: '@page',
+        limit: '@limit',
+        keyword: '@keyword',
+        state: '@state',
         role: { name: '角色', type: 'string', max: 20 }
     },
     handler: async (befly, ctx) => {
@@ -429,7 +429,7 @@ export default {
     method: 'POST',
     auth: true,
     fields: {
-        id: { name: '文章ID', type: 'number', min: 1 },
+        id: '@id',
         title: { name: '标题', type: 'string', min: 2, max: 200 },
         content: { name: '内容', type: 'text', min: 1, max: 100000 },
         summary: { name: '摘要', type: 'string', max: 500 },
@@ -510,7 +510,7 @@ export default {
     method: 'POST',
     auth: true,
     fields: {
-        id: { name: '文章ID', type: 'number', min: 1 }
+        id: '@id'
     },
     required: ['id'],
     handler: async (befly, ctx) => {
@@ -561,11 +561,11 @@ export default {
     method: 'POST',
     auth: false,
     fields: {
-        page: { name: '页码', type: 'number', min: 1, default: 1 },
-        limit: { name: '每页数量', type: 'number', min: 1, max: 50, default: 10 },
+        page: '@page',
+        limit: '@limit',
+        keyword: '@keyword',
         categoryId: { name: '分类', type: 'number', min: 0 },
         authorId: { name: '作者', type: 'number', min: 0 },
-        keyword: { name: '关键词', type: 'string', max: 50 },
         isTop: { name: '置顶', type: 'number', min: 0, max: 1 },
         isRecommend: { name: '推荐', type: 'number', min: 0, max: 1 },
         orderBy: { name: '排序', type: 'string', max: 20 }
@@ -615,7 +615,7 @@ export default {
     method: 'GET',
     auth: false,
     fields: {
-        id: { name: '文章ID', type: 'number', min: 1 }
+        id: '@id'
     },
     required: ['id'],
     handler: async (befly, ctx) => {
@@ -771,6 +771,99 @@ export default {
 
 ---
 
+## 代码优化技巧
+
+### 利用自动过滤简化更新操作
+
+数据库操作会**自动过滤 null 和 undefined 值**，因此可以大幅简化代码。
+
+#### 传统写法（繁琐）
+
+```typescript
+// ❌ 手动检查每个字段
+const updateData: Record<string, any> = {};
+if (ctx.body.nickname !== undefined) updateData.nickname = ctx.body.nickname;
+if (ctx.body.avatar !== undefined) updateData.avatar = ctx.body.avatar;
+if (ctx.body.phone !== undefined) updateData.phone = ctx.body.phone;
+if (ctx.body.gender !== undefined) updateData.gender = ctx.body.gender;
+
+if (Object.keys(updateData).length === 0) {
+    return No('没有需要更新的字段');
+}
+
+await befly.db.updData({
+    table: 'user',
+    data: updateData,
+    where: { id: ctx.user.userId }
+});
+```
+
+#### 优化写法（简洁）
+
+```typescript
+// ✅ 直接传入，undefined 值自动过滤
+const { nickname, avatar, phone, gender, birthday, bio } = ctx.body;
+
+const data = { nickname: nickname, avatar: avatar, phone: phone, gender: gender, birthday: birthday, bio: bio };
+
+// 使用 cleanFields 检查是否有有效数据
+const cleanData = befly.tool.cleanFields(data);
+if (Object.keys(cleanData).length === 0) {
+    return No('没有需要更新的字段');
+}
+
+await befly.db.updData({
+    table: 'user',
+    data: cleanData,
+    where: { id: ctx.user.userId }
+});
+```
+
+### 使用 cleanFields 进行精细控制
+
+当需要保留特定值（如 0、空字符串）时，使用 `cleanFields` 的高级参数：
+
+```typescript
+const { nickname, sort, state, remark } = ctx.body;
+
+// 保留 0 值（sort 和 state 允许为 0）
+const data = befly.tool.cleanFields(
+    { nickname: nickname, sort: sort, state: state, remark: remark },
+    [null, undefined], // 排除 null 和 undefined
+    { sort: true, state: true } // 保留这些字段的 0 值
+);
+
+await befly.db.updData({
+    table: 'menu',
+    data: data,
+    where: { id: ctx.body.id }
+});
+```
+
+### 查询条件的自动过滤
+
+where 条件同样支持自动过滤：
+
+```typescript
+// ✅ 可选筛选条件，undefined 自动忽略
+const { keyword, state, categoryId, startDate, endDate } = ctx.body;
+
+const result = await befly.db.getList({
+    table: 'article',
+    columns: ['id', 'title', 'createdAt'],
+    where: {
+        state: state, // undefined 时忽略
+        categoryId: categoryId, // undefined 时忽略
+        title: keyword ? { $like: `%${keyword}%` } : undefined, // 无关键词时忽略
+        createdAt: startDate && endDate ? { $gte: startDate, $lte: endDate } : undefined
+    },
+    page: ctx.body.page || 1,
+    limit: ctx.body.limit || 20
+});
+```
+
+---
+
 ## 完整目录结构
 
 ```

package/docs/validator.md

@@ -586,3 +586,33 @@ A: 数组类型会验证：
 1. 值是否为数组
 2. 元素数量是否在 min/max 范围内
 3. 如果有 regexp，每个元素都会进行正则验证
+
+### Q: 如何在验证前清理数据中的 null/undefined 值？
+
+A: 使用 `befly.tool.cleanFields` 方法：
+
+```typescript
+// 在 API handler 中使用
+handler: async (befly, ctx) => {
+    const { nickname, phone, address } = ctx.body;
+
+    // 清理 null 和 undefined 值
+    const cleanData = befly.tool.cleanFields({
+        nickname: nickname,
+        phone: phone,
+        address: address
+    });
+
+    // cleanData 只包含有效值
+    await befly.db.updData({
+        table: 'user',
+        data: cleanData,
+        where: { id: ctx.user.userId }
+    });
+
+    return Yes('更新成功');
+};
+```
+
+> **注意**：数据库操作（insData、updData 等）会自动过滤 null/undefined 值，通常不需要手动调用 cleanFields。
+> 详见 [database.md](./database.md#nullundefined-值自动过滤)。

package/loader/loadApis.ts

@@ -20,42 +20,39 @@ import { projectApiDir } from '../paths.js';
 import type { ApiRoute } from '../types/api.js';
 
 /**
- * API 默认字段定义
- * 这些字段会自动合并到所有 API 的 fields 中
- * API 自定义的同名字段可以覆盖这些默认值
+ * 预定义的默认字段
  */
-const DEFAULT_API_FIELDS = {
-    id: {
-        name: 'ID',
-        type: 'number',
-        min: 1,
-        max: null
-    },
-    page: {
-        name: '页码',
-        type: 'number',
-        min: 1,
-        max: 9999
-    },
-    limit: {
-        name: '每页数量',
-        type: 'number',
-        min: 1,
-        max: 100
-    },
-    keyword: {
-        name: '关键词',
-        type: 'string',
-        min: 1,
-        max: 50
-    },
-    state: {
-        name: '状态',
-        type: 'number',
-        min: 0,
-        max: 2
+const PRESET_FIELDS: Record<string, any> = {
+    '@id': { name: 'ID', type: 'number', min: 1, max: null },
+    '@page': { name: '页码', type: 'number', min: 1, max: 9999 },
+    '@limit': { name: '每页数量', type: 'number', min: 1, max: 100 },
+    '@keyword': { name: '关键词', type: 'string', min: 1, max: 50 },
+    '@state': { name: '状态', type: 'number', min: 0, max: 2 }
+};
+
+/**
+ * 处理字段定义，将 @ 符号引用替换为实际字段定义
+ */
+function processFields(fields: Record<string, any>): Record<string, any> {
+    if (!fields || typeof fields !== 'object') return fields;
+
+    const processed: Record<string, any> = {};
+    for (const [key, value] of Object.entries(fields)) {
+        // 如果值是字符串且以 @ 开头，则查找预定义字段
+        if (typeof value === 'string' && value.startsWith('@')) {
+            if (PRESET_FIELDS[value]) {
+                processed[key] = PRESET_FIELDS[value];
+            } else {
+                // 未找到预定义字段，保持原值
+                processed[key] = value;
+            }
+        } else {
+            // 普通字段定义，保持原样
+            processed[key] = value;
+        }
     }
-} as const;
+    return processed;
+}
 
 /**
  * 加载所有 API 路由
@@ -113,8 +110,8 @@ export async function loadApis(apis: Map<string, ApiRoute>): Promise<void> {
                 // 设置默认值
                 const methodStr = (api.method || 'POST').toUpperCase();
                 api.auth = api.auth !== undefined ? api.auth : true;
-                // 合并默认字段：默认字段作为基础，API 自定义字段优先级更高
-                api.fields = { ...DEFAULT_API_FIELDS, ...(api.fields || {}) };
+                // 处理字段定义，将 @ 引用替换为实际字段定义
+                api.fields = processFields(api.fields || {});
                 api.required = api.required || [];
 
                 // 构建路由路径（不含方法）

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "befly",
-    "version": "3.9.13",
+    "version": "3.9.21",
     "description": "Befly - 为 Bun 专属打造的 TypeScript API 接口框架核心引擎",
     "type": "module",
     "private": false,
@@ -74,7 +74,7 @@
         "pino": "^10.1.0",
         "pino-roll": "^4.0.0"
     },
-    "gitHead": "f0dc38476a87163a9de1d5ddcefa42304b1ee09b",
+    "gitHead": "d0825d638bbb779137fb8860049bcc1b3200a5dc",
     "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) {