befly 3.10.18 → 3.11.1

package/docs/guide/quickstart.md

@@ -1,354 +0,0 @@
-# Quickstart 快速入门
-
-> 5 分钟搭建你的第一个 Befly API 服务
-
-## 目录
-
-- [环境准备](#环境准备)
-- [项目结构](#项目结构)
-- [第一个 API](#第一个-api)
-- [配置数据库](#配置数据库)
-- [定义表结构](#定义表结构)
-- [同步数据库](#同步数据库)
-- [启动服务](#启动服务)
-- [下一步](#下一步)
-
----
-
-## 环境准备
-
-### 必需软件
-
-| 软件  | 版本要求 | 说明              |
-| ----- | -------- | ----------------- |
-| Bun   | >= 1.0   | JavaScript 运行时 |
-| MySQL | >= 8.0   | 数据库            |
-| Redis | >= 6.0   | 缓存（可选）      |
-
-### 安装 Bun
-
-```bash
-# Windows (PowerShell)
-powershell -c "irm bun.sh/install.ps1 | iex"
-
-# macOS / Linux
-curl -fsSL https://bun.sh/install | bash
-```
-
-### 创建项目
-
-```bash
-# 克隆模板项目
-git clone https://github.com/chenbimo/befly-tpl.git my-api
-cd my-api
-
-# 安装依赖
-bun install
-```
-
----
-
-## 项目结构
-
-```
-my-api/
-├── apis/                  # API 接口目录
-│   └── user/
-│       └── login.ts       # 用户登录接口
-├── tables/                # 表定义目录
-│   └── user.json          # 用户表定义
-├── configs/               # 配置文件目录
-│   ├── befly.common.json  # 公共配置
-│   ├── befly.development.json  # 开发环境配置
-│   └── befly.production.json   # 生产环境配置
-├── main.ts                # 入口文件
-└── package.json
-```
-
----
-
-## 第一个 API
-
-### 创建 API 文件
-
-在 `apis/user/` 目录下创建 `login.ts`：
-
-```typescript
-import type { ApiRoute } from "befly/types/api";
-
-export default {
-    name: "用户登录",
-    method: "POST",
-    auth: false, // 不需要登录
-    fields: {
-        email: { name: "邮箱", type: "string", min: 5, max: 100, regexp: "@email" },
-        password: { name: "密码", type: "string", min: 6, max: 100 }
-    },
-    required: ["email", "password"],
-    handler: async (befly, ctx) => {
-        // 查询用户
-        const userRes = await befly.db.getOne({
-            table: "user",
-            fields: ["id", "email", "password", "nickname"],
-            where: { email: ctx.body.email }
-        });
-
-        const user = userRes.data;
-
-        if (!user?.id) {
-            return befly.tool.No("用户不存在");
-        }
-
-        // 验证密码
-        const isValid = await befly.cipher.verifyPassword(ctx.body.password, user.password);
-        if (!isValid) {
-            return befly.tool.No("密码错误");
-        }
-
-        // 签发令牌
-        const token = befly.jwt.sign({ id: user.id });
-
-        return befly.tool.Yes("登录成功", { token: token, user: { id: user.id, nickname: user.nickname } });
-    }
-} as ApiRoute;
-```
-
-### API 路由规则
-
-文件路径自动转换为路由：
-
-| 文件路径                | 路由路径                  |
-| ----------------------- | ------------------------- |
-| `apis/user/login.ts`    | `POST /api/user/login`    |
-| `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/...`。
-
----
-
-## 配置数据库
-
-### 编辑配置文件
-
-修改 `configs/befly.development.json`：
-
-```json
-{
-    "db": {
-        "type": "mysql",
-        "host": "127.0.0.1",
-        "port": 3306,
-        "username": "root",
-        "password": "your_password",
-        "database": "my_api"
-    },
-    "redis": {
-        "host": "127.0.0.1",
-        "port": 6379,
-        "password": ""
-    },
-    "auth": {
-        "secret": "your-jwt-secret-change-in-production",
-        "expiresIn": "7d"
-    },
-    "logger": {
-        "debug": 1,
-        "console": 1
-    }
-}
-```
-
-### 创建数据库
-
-```sql
-CREATE DATABASE my_api CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;
-```
-
----
-
-## 定义表结构
-
-### 创建表定义文件
-
-在 `tables/` 目录下创建 `user.json`：
-
-```json
-{
-    "email": "邮箱|string|5|100||true|^[\\w.-]+@[\\w.-]+\\.[a-zA-Z]{2,}$",
-    "password": "密码|string|6|100||true",
-    "nickname": "昵称|string|2|50|用户",
-    "avatar": "头像|string|0|500",
-    "phone": "手机号|string|0|20"
-}
-```
-
-### 字段定义格式
-
-格式：`"字段标签|类型|最小|最大|默认|必填|正则"`
-
-| 位置 | 说明        | 示例                  |
-| ---- | ----------- | --------------------- |
-| 1    | 字段标签    | `邮箱`                |
-| 2    | 数据类型    | `string` / `number`   |
-| 3    | 最小值/长度 | `5`                   |
-| 4    | 最大值/长度 | `100`                 |
-| 5    | 默认值      | `用户`                |
-| 6    | 是否必填    | `true` / `false`      |
-| 7    | 正则验证    | `@email` 或自定义正则 |
-
-### 自动字段
-
-每个表自动添加：
-
-| 字段         | 类型    | 说明                            |
-| ------------ | ------- | ------------------------------- |
-| `id`         | BIGINT  | 主键，自增                      |
-| `created_at` | BIGINT  | 创建时间戳                      |
-| `updated_at` | BIGINT  | 更新时间戳                      |
-| `state`      | TINYINT | 状态（1=正常，0=禁用，-1=删除） |
-
----
-
-## 同步数据库
-
-### 自动同步
-
-服务启动时会在**主进程**自动执行同步流程：
-
-1. `syncTable()`：同步表结构
-2. `syncApi()`：同步接口定义
-3. `syncMenu()`：同步菜单定义
-4. `syncDev()`：同步开发账户/开发角色
-5. `syncCache()`：缓存同步收尾（cacheApis + cacheMenus + rebuildRoleApiPermissions）
-
-如需手动触发，可在代码中调用（一般不建议在请求路径中调用）：
-
-```typescript
-import { syncTable } from "../sync/syncTable.ts";
-import { syncApi } from "../sync/syncApi.ts";
-import { syncMenu } from "../sync/syncMenu.ts";
-import { syncDev } from "../sync/syncDev.ts";
-import { syncCache } from "../sync/syncCache.ts";
-import { checkMenu } from "../checks/checkMenu.ts";
-import { scanSources } from "../utils/scanSources.ts";
-
-// 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 syncApi(ctx, sources.apis as any);
-await syncMenu(ctx, checkedMenus);
-await syncDev(ctx, { devEmail: ctx.config.devEmail, devPassword: ctx.config.devPassword });
-await syncCache(ctx);
-```
-
-### 验证同步结果
-
-```bash
-# 查看数据库
-mysql -u root -p my_api -e "SHOW TABLES;"
-
-# 应该看到：
-# +------------------+
-# | Tables_in_my_api |
-# +------------------+
-# | user             |
-# +------------------+
-```
-
----
-
-## 启动服务
-
-### 开发模式
-
-```bash
-bun run dev
-```
-
-服务启动后：
-
-```
-🚀 Befly 服务已启动
-📍 http://localhost:3000
-```
-
-### 测试 API
-
-```bash
-# 测试登录接口
-curl -X POST http://localhost:3000/api/user/login \
-  -H "Content-Type: application/json" \
-  -d '{"email":"test@example.com","password":"123456"}'
-```
-
-响应示例：
-
-```json
-{
-    "code": 0,
-    "msg": "登录成功",
-    "data": {
-        "token": "eyJhbGciOiJIUzI1NiIs...",
-        "user": {
-            "id": 1,
-            "nickname": "用户"
-        }
-    }
-}
-```
-
----
-
-## 下一步
-
-### 学习更多
-
-| 主题       | 文档                                      | 说明                 |
-| ---------- | ----------------------------------------- | -------------------- |
-| API 开发   | [api.md](../api/api.md)                   | API 定义、字段、权限 |
-| 表结构     | [table.md](../reference/table.md)         | 表定义格式详解       |
-| 数据库操作 | [database.md](../plugins/database.md)     | CRUD 操作            |
-| 配置系统   | [config.md](../reference/config.md)       | 配置文件说明         |
-| 插件开发   | [plugin.md](../plugins/plugin.md)         | 自定义插件           |
-| Hook 开发  | [hook.md](../hooks/hook.md)               | 请求处理钩子         |
-| 验证系统   | [validator.md](../reference/validator.md) | 参数验证             |
-| 日志系统   | [logger.md](../reference/logger.md)       | 日志配置             |
-| 加密工具   | [cipher.md](../plugins/cipher.md)         | 加密与 JWT           |
-| 同步命令   | [sync.md](../reference/sync.md)           | 数据库同步           |
-
-### 常用命令
-
-```bash
-# 开发
-bun run dev          # 启动开发服务
-
-# 生产
-bun run build        # 构建
-bun run start        # 启动生产服务
-```
-
-### 项目示例
-
-```
-apis/
-├── user/
-│   ├── login.ts      # 登录
-│   ├── register.ts   # 注册
-│   ├── info.ts       # 获取信息
-│   └── update.ts     # 更新信息
-├── article/
-│   ├── list.ts       # 文章列表
-│   ├── detail.ts     # 文章详情
-│   ├── create.ts     # 创建文章
-│   └── delete.ts     # 删除文章
-└── common/
-    └── upload.ts     # 文件上传
-
-tables/
-├── user.json         # 用户表
-├── article.json      # 文章表
-└── category.json     # 分类表
-```

package/docs/hooks/auth.md

@@ -1,38 +0,0 @@
-# auth Hook - 身份认证
-
-> 解析/校验 JWT Token，并将用户信息写入 `ctx.user`。
-
-## 作用
-
-- 从请求头中解析鉴权信息（常见为 `Authorization` 或 `token`）
-- 校验 token 合法性与过期
-- 将 token payload 写入 `ctx.user`，供后续 `permission` / 业务 handler 使用
-
-## 何时生效
-
-- API 请求进入 hook pipeline 时执行
-- 如果某个 API 路由显式声明 `auth: false`，则该接口跳过登录态要求（但 hook 仍可能解析 token，以便后续使用）
-
-## 配置
-
-JWT 的核心配置来自 `beflyConfig.auth`：
-
-```json
-{
-    "auth": {
-        "secret": "your-jwt-secret-change-in-production",
-        "expiresIn": "7d",
-        "algorithm": "HS256"
-    }
-}
-```
-
-## 行为要点
-
-- token 无效/过期时：通常不会在这里直接判权限，而是由后续 `permission` 按接口是否需要登录来决定是否拦截
-- hook 写入：`ctx.user`（后续统一依赖这个字段）
-
-## 常见问题
-
-- Q: 为什么我 `auth:false` 的接口也能拿到 `ctx.user`？
-    - A: 接口不要求登录 ≠ 不解析 token；只要你带了 token，框架仍可解析出来给你用。

package/docs/hooks/cors.md

@@ -1,28 +0,0 @@
-# cors Hook - 跨域处理
-
-> 统一设置 CORS 响应头，并处理 `OPTIONS` 预检请求。
-
-## 作用
-
-- 根据配置生成并写入 `ctx.corsHeaders`
-- 对 `OPTIONS` 预检请求直接返回 204，避免进入后续 hook / handler
-
-## 配置
-
-```json
-{
-    "cors": {
-        "origin": "*",
-        "methods": "GET, POST, PUT, DELETE, OPTIONS",
-        "allowedHeaders": "Content-Type, Authorization, authorization, token",
-        "exposedHeaders": "Content-Range, X-Content-Range, Authorization, authorization, token",
-        "maxAge": 86400,
-        "credentials": "true"
-    }
-}
-```
-
-## 行为要点
-
-- `OPTIONS`：不计入业务逻辑，不进入后续处理链
-- 正常请求：仅设置 CORS 相关头，不改变业务响应体