befly 3.2.0 → 3.3.0

package/lib/middleware.ts

@@ -0,0 +1,271 @@
+/**
+ * 中间件集合
+ * 整合所有请求处理中间件
+ */
+
+import { isEmpty, isPlainObject } from 'es-toolkit/compat';
+import { Env } from '../config/env.js';
+import { Logger } from './logger.js';
+import { Jwt } from './jwt.js';
+import { Xml } from './xml.js';
+import { Validator } from './validator.js';
+import { pickFields } from '../util.js';
+import type { ApiRoute } from '../types/api.js';
+import type { RequestContext } from '../types/context.js';
+import type { Plugin } from '../types/plugin.js';
+import type { BeflyContext } from '../types/befly.js';
+
+// ========================================
+// JWT 认证中间件
+// ========================================
+
+/**
+ * 从请求头中提取并验证JWT token
+ */
+export async function authenticate(ctx: RequestContext): Promise<void> {
+    const authHeader = ctx.request.headers.get('authorization');
+
+    if (authHeader && authHeader.startsWith('Bearer ')) {
+        const token = authHeader.substring(7);
+
+        try {
+            const payload = await Jwt.verify(token);
+            ctx.user = payload;
+        } catch (error: any) {
+            ctx.user = {};
+        }
+    } else {
+        ctx.user = {};
+    }
+}
+
+// ========================================
+// CORS 中间件
+// ========================================
+
+export interface CorsResult {
+    headers: Record<string, string>;
+}
+
+/**
+ * 设置 CORS 选项
+ * 根据环境变量或请求头动态设置跨域配置
+ * @param req - 请求对象
+ * @returns CORS 配置对象
+ */
+export const setCorsOptions = (req: Request): CorsResult => {
+    return {
+        headers: {
+            'Access-Control-Allow-Origin': Env.ALLOWED_ORIGIN || req.headers.get('origin') || '*',
+            'Access-Control-Allow-Methods': Env.ALLOWED_METHODS || 'GET, POST, PUT, DELETE, OPTIONS',
+            'Access-Control-Allow-Headers': Env.ALLOWED_HEADERS || 'Content-Type, Authorization, authorization, token',
+            'Access-Control-Expose-Headers': Env.EXPOSE_HEADERS || 'Content-Range, X-Content-Range, Authorization, authorization, token',
+            'Access-Control-Max-Age': Env.MAX_AGE || 86400,
+            'Access-Control-Allow-Credentials': Env.ALLOW_CREDENTIALS || 'true'
+        }
+    };
+};
+
+/**
+ * 处理OPTIONS预检请求
+ * @param corsOptions - CORS 配置对象
+ * @returns 204 响应
+ */
+export function handleOptionsRequest(corsOptions: CorsResult): Response {
+    return new Response(null, {
+        status: 204,
+        headers: corsOptions.headers
+    });
+}
+
+// ========================================
+// 参数解析中间件
+// ========================================
+
+/**
+ * 解析GET请求参数
+ */
+export function parseGetParams(api: ApiRoute, ctx: RequestContext): void {
+    const url = new URL(ctx.request.url);
+
+    if (isPlainObject(api.fields) && !isEmpty(api.fields)) {
+        ctx.body = pickFields(Object.fromEntries(url.searchParams), Object.keys(api.fields));
+    } else {
+        ctx.body = Object.fromEntries(url.searchParams);
+    }
+}
+
+/**
+ * 解析POST请求参数
+ */
+export async function parsePostParams(api: ApiRoute, ctx: RequestContext): Promise<boolean> {
+    try {
+        const contentType = ctx.request.headers.get('content-type') || '';
+
+        if (contentType.indexOf('json') !== -1) {
+            try {
+                ctx.body = await ctx.request.json();
+            } catch (err) {
+                // 如果没有 body 或 JSON 解析失败，默认为空对象
+                ctx.body = {};
+            }
+        } else if (contentType.indexOf('xml') !== -1) {
+            const textData = await ctx.request.text();
+            const xmlData = Xml.parse(textData);
+            ctx.body = xmlData?.xml ? xmlData.xml : xmlData;
+        } else if (contentType.indexOf('form-data') !== -1) {
+            ctx.body = await ctx.request.formData();
+        } else if (contentType.indexOf('x-www-form-urlencoded') !== -1) {
+            const text = await ctx.request.text();
+            const formData = new URLSearchParams(text);
+            ctx.body = Object.fromEntries(formData);
+        } else {
+            ctx.body = {};
+        }
+
+        if (isPlainObject(api.fields) && !isEmpty(api.fields)) {
+            ctx.body = pickFields(ctx.body, Object.keys(api.fields));
+        }
+
+        return true;
+    } catch (err: any) {
+        Logger.error('处理请求参数时发生错误', err);
+        return false;
+    }
+}
+
+// ========================================
+// 权限验证中间件
+// ========================================
+
+export interface PermissionResult {
+    code: 0 | 1;
+    msg: string;
+    data: any;
+    [key: string]: any;
+}
+
+/**
+ * 检查权限
+ *
+ * 验证流程:
+ * 1. auth=false → 公开接口，直接通过
+ * 2. auth=true → 需要登录认证
+ *    - 未登录 → 拒绝
+ *    - roleCode='dev' → 超级管理员，拥有所有权限
+ *    - 其他角色 → 检查接口是否在角色的可访问接口列表中（通过 Redis SISMEMBER 预判断）
+ *
+ * @param api - API 路由配置
+ * @param ctx - 请求上下文
+ * @param hasPermission - 是否有权限（通过 Redis SISMEMBER 预先判断）
+ * @returns 统一的响应格式 { code: 0/1, msg, data, ...extra }
+ */
+export function checkPermission(api: ApiRoute, ctx: RequestContext, hasPermission: boolean = false): PermissionResult {
+    // 1. 公开接口（auth=false），无需验证
+    if (api.auth === false) {
+        return { code: 0, msg: '', data: {} };
+    }
+
+    // 2. 需要登录的接口（auth=true）
+    // 2.1 检查是否登录
+    if (!ctx.user?.id) {
+        return {
+            code: 1,
+            msg: '未登录',
+            data: {},
+            login: 'no'
+        };
+    }
+
+    // 2.2 dev 角色拥有所有权限（超级管理员）
+    if (ctx.user.roleCode === 'dev') {
+        return { code: 0, msg: '', data: {} };
+    }
+
+    // 2.3 检查接口权限（基于 Redis SISMEMBER 预判断结果）
+    if (!hasPermission) {
+        return {
+            code: 1,
+            msg: '没有权限访问此接口',
+            data: {}
+        };
+    }
+
+    // 验证通过
+    return { code: 0, msg: '', data: {} };
+}
+
+// ========================================
+// 插件钩子中间件
+// ========================================
+
+/**
+ * 执行所有插件的onGet钩子
+ */
+export async function executePluginHooks(pluginLists: Plugin[], appContext: BeflyContext, ctx: RequestContext): Promise<void> {
+    for await (const plugin of pluginLists) {
+        try {
+            if (typeof plugin?.onGet === 'function') {
+                await plugin?.onGet(appContext, ctx, ctx.request);
+            }
+        } catch (error: any) {
+            Logger.error('插件处理请求时发生错误', error);
+        }
+    }
+}
+
+// ========================================
+// 请求日志中间件
+// ========================================
+
+/**
+ * 过滤日志字段（内部函数）
+ * 用于从请求体中排除敏感字段（如密码、令牌等）
+ * @param body - 请求体对象
+ * @param excludeFields - 要排除的字段名（逗号分隔）
+ * @returns 过滤后的对象
+ */
+function filterLogFields(body: any, excludeFields: string = ''): any {
+    if (!body || (!isPlainObject(body) && !Array.isArray(body))) return body;
+
+    const fieldsArray = excludeFields
+        .split(',')
+        .map((field) => field.trim())
+        .filter((field) => field.length > 0);
+
+    const filtered: any = {};
+    for (const [key, value] of Object.entries(body)) {
+        if (!fieldsArray.includes(key)) {
+            filtered[key] = value;
+        }
+    }
+    return filtered;
+}
+
+/**
+ * 记录请求日志
+ */
+export function logRequest(apiPath: string, ctx: RequestContext): void {
+    Logger.info({
+        msg: '通用接口日志',
+        请求路径: apiPath,
+        请求方法: ctx.request.method,
+        用户信息: ctx.user,
+        请求参数: filterLogFields(ctx.body, Env.LOG_EXCLUDE_FIELDS),
+        耗时: Date.now() - ctx.startTime + 'ms'
+    });
+}
+
+// ========================================
+// 参数验证中间件
+// ========================================
+
+// 创建全局validator实例
+const validator = new Validator();
+
+/**
+ * 验证请求参数
+ */
+export function validateParams(api: ApiRoute, ctx: RequestContext) {
+    return validator.validate(ctx.body, api.fields, api.required);
+}

package/{utils → lib}/redisHelper.ts

@@ -5,8 +5,8 @@
 
 import { RedisClient } from 'bun';
 import { Env } from '../config/env.js';
-import { Logger } from './logger.js';
-import { getRedis } from './database.js';
+import { Logger } from '../lib/logger.js';
+import { Database } from './database.js';
 
 /**
  * Redis 键前缀
@@ -19,9 +19,9 @@ const prefix = Env.REDIS_KEY_PREFIX ? `${Env.REDIS_KEY_PREFIX}:` : '';
  * @throws 如果客户端未初始化
  */
 function getClient(): RedisClient {
-    const client = getRedis();
+    const client = Database.getRedis();
     if (!client) {
-        throw new Error('Redis 客户端未初始化，请先调用 initDatabase() 或 initRedisOnly()');
+        throw new Error('Redis 客户端未初始化，请先调用 Database.connectRedis()');
     }
     return client;
 }

package/{utils/validate.ts → lib/validator.ts}

@@ -1,18 +1,80 @@
 /**
- * 数据验证器 - TypeScript 版本
- * 提供类型安全的字段验证功能
+ * 数据验证器 - Befly 项目专用
+ * 内置 RegexAliases，直接使用 util.ts 中的 parseRule
  */
 
-import { isType } from './helper.js';
-import { parseRule } from './helper.js';
-import { RegexAliases } from '../config/regexAliases.js';
-import type { TableDefinition, FieldRule, ParsedFieldRule } from '../types/common.js';
+import { parseRule } from '../util.js';
+import type { TableDefinition, FieldRule } from '../types/common.js';
 import type { ValidationResult, ValidationError } from '../types/validator';
 
 /**
- * 验证器类
+ * 内置正则表达式别名（项目专用）
+ */
+const RegexAliases = {
+    // 数字类型
+    number: '^\\d+$',
+    integer: '^-?\\d+$',
+    float: '^-?\\d+(\\.\\d+)?$',
+    positive: '^[1-9]\\d*$',
+    negative: '^-\\d+$',
+    zero: '^0$',
+
+    // 字符串类型
+    word: '^[a-zA-Z]+$',
+    alphanumeric: '^[a-zA-Z0-9]+$',
+    alphanumeric_: '^[a-zA-Z0-9_]+$',
+    lowercase: '^[a-z]+$',
+    uppercase: '^[A-Z]+$',
+
+    // 中文
+    chinese: '^[\\u4e00-\\u9fa5]+$',
+    chinese_word: '^[\\u4e00-\\u9fa5a-zA-Z]+$',
+
+    // 常用格式
+    email: '^[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\\.[a-zA-Z]{2,}$',
+    phone: '^1[3-9]\\d{9}$',
+    url: '^https?://',
+    ip: '^((25[0-5]|2[0-4]\\d|[01]?\\d\\d?)\\.){3}(25[0-5]|2[0-4]\\d|[01]?\\d\\d?)$',
+    domain: '^(?:[a-zA-Z0-9](?:[a-zA-Z0-9-]{0,61}[a-zA-Z0-9])?\\.)+[a-zA-Z]{2,}$',
+
+    // 特殊格式
+    uuid: '^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$',
+    hex: '^[0-9a-fA-F]+$',
+    base64: '^[A-Za-z0-9+/=]+$',
+    md5: '^[a-f0-9]{32}$',
+    sha1: '^[a-f0-9]{40}$',
+    sha256: '^[a-f0-9]{64}$',
+
+    // 日期时间
+    date: '^\\d{4}-\\d{2}-\\d{2}$',
+    time: '^\\d{2}:\\d{2}:\\d{2}$',
+    datetime: '^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}',
+    year: '^\\d{4}$',
+    month: '^(0[1-9]|1[0-2])$',
+    day: '^(0[1-9]|[12]\\d|3[01])$',
+
+    // 代码相关
+    variable: '^[a-zA-Z_][a-zA-Z0-9_]*$',
+    constant: '^[A-Z][A-Z0-9_]*$',
+    package: '^[a-z][a-z0-9-]*$',
+
+    // 证件相关
+    id_card: '^\\d{17}[\\dXx]$',
+    passport: '^[a-zA-Z0-9]{5,17}$',
+
+    // 空值
+    empty: '^$',
+    notempty: '.+'
+} as const;
+
+/**
+ * 验证器类（Befly 项目专用）
+ * 内置 RegexAliases，直接使用 util.ts 中的 parseRule
  */
 export class Validator {
+    /** 正则别名映射（内置） */
+    private readonly regexAliases: Record<string, string> = RegexAliases;
+
     /**
      * 验证数据
      * @param data - 要验证的数据对象
@@ -107,25 +169,18 @@ export class Validator {
 
     /**
      * 解析 regex 别名
-     * 如果 regex 以 @ 开头，则从别名表中获取实际正则表达式
-     * @param regex - 原始 regex 或别名（如 @number）
-     * @returns 实际的正则表达式字符串
      */
     private resolveRegexAlias(regex: string | null): string | null {
         if (!regex || typeof regex !== 'string') {
             return regex;
         }
 
-        // 检查是否是别名（以 @ 开头）
         if (regex.startsWith('@')) {
             const aliasName = regex.substring(1);
-            const resolvedRegex = RegexAliases[aliasName as keyof typeof RegexAliases];
-
+            const resolvedRegex = this.regexAliases[aliasName];
             if (resolvedRegex) {
                 return resolvedRegex;
             }
-
-            // 别名不存在，返回原值（让后续验证报错）
             return regex;
         }
 
@@ -139,14 +194,12 @@ export class Validator {
         const parsed = parseRule(rule);
         let { name, type, min, max, regex } = parsed;
 
-        // 解析 regex 别名
         regex = this.resolveRegexAlias(regex);
 
         switch (type.toLowerCase()) {
             case 'number':
                 return this.validateNumber(value, name, min, max, regex, fieldName);
             case 'string':
-                return this.validateString(value, name, min, max, regex, fieldName);
             case 'text':
                 return this.validateString(value, name, min, max, regex, fieldName);
             case 'array_string':
@@ -162,7 +215,7 @@ export class Validator {
      */
     private validateNumber(value: any, name: string, min: number | null, max: number | null, spec: string | null, fieldName: string): ValidationError {
         try {
-            if (isType(value, 'number') === false) {
+            if (typeof value !== 'number' || Number.isNaN(value)) {
                 return `${name}(${fieldName})必须是数字`;
             }
 
@@ -196,7 +249,7 @@ export class Validator {
      */
     private validateString(value: any, name: string, min: number | null, max: number | null, spec: string | null, fieldName: string): ValidationError {
         try {
-            if (isType(value, 'string') === false) {
+            if (typeof value !== 'string') {
                 return `${name}(${fieldName})必须是字符串`;
             }
 
@@ -262,64 +315,39 @@ export class Validator {
     }
 
     /**
-     * 快速验证（静态方法）
-     * @param data - 要验证的数据
-     * @param rules - 验证规则
-     * @param required - 必填字段
-     * @returns 验证结果
+     * 验证单个值
      */
-    static validate(data: Record<string, any>, rules: TableDefinition, required?: string[]): ValidationResult;
-    static validate(value: any, rule: string): { valid: boolean; value: any; errors: string[] };
-    static validate(dataOrValue: any, rulesOrRule: any, required: string[] = []): any {
-        // 如果第二个参数是字符串，则是单值验证
-        if (typeof rulesOrRule === 'string') {
-            return Validator.validateSingleValue(dataOrValue, rulesOrRule);
-        }
-        // 否则是对象验证
-        return validator.validate(dataOrValue, rulesOrRule, required);
-    }
-
-    /**
-     * 验证单个值（静态方法）
-     * @param value - 要验证的值
-     * @param rule - 验证规则字符串
-     * @returns 验证结果 { valid: boolean, value: any, errors: string[] }
-     */
-    static validateSingleValue(value: any, rule: string): { valid: boolean; value: any; errors: string[] } {
+    validateSingleValue(value: any, rule: string): { valid: boolean; value: any; errors: string[] } {
         const parsed = parseRule(rule);
         let { name, type, min, max, regex, default: defaultValue } = parsed;
 
-        // 解析 regex 别名
-        if (regex && typeof regex === 'string' && regex.startsWith('@')) {
-            const aliasName = regex.substring(1);
-            const resolvedRegex = RegexAliases[aliasName as keyof typeof RegexAliases];
-            if (resolvedRegex) {
-                regex = resolvedRegex;
-            }
-        }
+        regex = this.resolveRegexAlias(regex);
 
         // 处理 undefined/null 值，使用默认值
         if (value === undefined || value === null) {
             if (defaultValue !== 'null' && defaultValue !== null) {
-                // 特殊处理数组类型的默认值字符串
                 if ((type === 'array_string' || type === 'array_text') && typeof defaultValue === 'string') {
                     if (defaultValue === '[]') {
                         return { valid: true, value: [], errors: [] };
                     }
-                    // 尝试解析 JSON 格式的数组字符串
                     try {
                         const parsedArray = JSON.parse(defaultValue);
                         if (Array.isArray(parsedArray)) {
                             return { valid: true, value: parsedArray, errors: [] };
                         }
                     } catch {
-                        // 解析失败，使用空数组
                         return { valid: true, value: [], errors: [] };
                     }
                 }
+                // 数字类型默认值转换
+                if (type === 'number' && typeof defaultValue === 'string') {
+                    const numValue = Number(defaultValue);
+                    if (!isNaN(numValue)) {
+                        return { valid: true, value: numValue, errors: [] };
+                    }
+                }
                 return { valid: true, value: defaultValue, errors: [] };
             }
-            // 如果没有默认值，根据类型返回默认值
             if (type === 'number') {
                 return { valid: true, value: 0, errors: [] };
             } else if (type === 'array_string' || type === 'array_text') {
@@ -344,7 +372,7 @@ export class Validator {
         // 类型验证
         switch (type.toLowerCase()) {
             case 'number':
-                if (!isType(convertedValue, 'number')) {
+                if (typeof convertedValue !== 'number' || Number.isNaN(convertedValue)) {
                     errors.push(`${name || '值'}必须是数字`);
                 }
                 if (min !== null && convertedValue < min) {
@@ -359,15 +387,15 @@ export class Validator {
                         if (!regExp.test(String(convertedValue))) {
                             errors.push(`${name || '值'}格式不正确`);
                         }
-                    } catch {
-                        errors.push(`${name || '值'}的正则表达式格式错误`);
+                    } catch (e: any) {
+                        errors.push(`${name || '值'}的正则表达式格式错误: ${e.message}`);
                     }
                 }
                 break;
 
             case 'string':
             case 'text':
-                if (!isType(convertedValue, 'string')) {
+                if (typeof convertedValue !== 'string') {
                     errors.push(`${name || '值'}必须是字符串`);
                 }
                 if (min !== null && convertedValue.length < min) {
@@ -422,13 +450,25 @@ export class Validator {
         };
     }
 
+    /**
+     * 静态方法：快速验证
+     */
+    static validate(data: Record<string, any>, rules: TableDefinition, required?: string[]): ValidationResult;
+    static validate(value: any, rule: string): { valid: boolean; value: any; errors: string[] };
+    static validate(dataOrValue: any, rulesOrRule: any, required?: string[]): any {
+        const validator = new Validator();
+
+        if (typeof rulesOrRule === 'string') {
+            return validator.validateSingleValue(dataOrValue, rulesOrRule);
+        }
+
+        return validator.validate(dataOrValue, rulesOrRule, required || []);
+    }
+
     /**
      * 检查验证是否通过
-     * @param result - 验证结果
-     * @returns 是否通过
      */
     static isPassed(result: ValidationResult | { valid: boolean; value: any; errors: string[] }): boolean {
-        // 支持两种结果格式
         if ('valid' in result) {
             return result.valid === true;
         }
@@ -437,8 +477,6 @@ export class Validator {
 
     /**
      * 检查验证是否失败
-     * @param result - 验证结果
-     * @returns 是否失败
      */
     static isFailed(result: ValidationResult): boolean {
         return result.code === 1;
@@ -446,15 +484,11 @@ export class Validator {
 
     /**
      * 获取第一个错误信息
-     * @param result - 验证结果
-     * @returns 错误信息
      */
     static getFirstError(result: ValidationResult | { valid: boolean; value: any; errors: string[] }): string | null {
-        // 单值验证结果
         if ('valid' in result) {
             return result.errors.length > 0 ? result.errors[0] : null;
         }
-        // 对象验证结果
         if (result.code === 0) return null;
         if (!result.fields) return null;
         const errors = Object.values(result.fields);
@@ -463,15 +497,11 @@ export class Validator {
 
     /**
      * 获取所有错误信息
-     * @param result - 验证结果
-     * @returns 错误信息数组
      */
     static getAllErrors(result: ValidationResult | { valid: boolean; value: any; errors: string[] }): string[] {
-        // 单值验证结果
         if ('valid' in result) {
             return result.errors;
         }
-        // 对象验证结果
         if (result.code === 0) return [];
         if (!result.fields) return [];
         return Object.values(result.fields);
@@ -479,15 +509,8 @@ export class Validator {
 
     /**
      * 获取错误字段列表
-     * @param result - 验证结果
-     * @returns 错误字段名数组
      */
     static getErrorFields(result: ValidationResult): string[] {
         return result.code === 0 ? [] : Object.keys(result.fields);
     }
 }
-
-/**
- * 导出验证器实例
- */
-export const validator = new Validator();

package/lifecycle/bootstrap.ts

@@ -0,0 +1,63 @@
+/**
+ * 服务启动引导器
+ * 负责组装和启动Bun HTTP服务器
+ */
+
+import { Logger } from '../lib/logger.js';
+import { calcPerfTime, No } from '../util.js';
+import { Env } from '../config/env.js';
+import { rootHandler } from '../router/root.js';
+import { apiHandler } from '../router/api.js';
+import { staticHandler } from '../router/static.js';
+
+import type { Server } from 'bun';
+import type { BeflyContext } from '../types/befly.js';
+import type { ApiRoute } from '../types/api.js';
+import type { Plugin } from '../types/plugin.js';
+
+/**
+ * 引导器类
+ */
+export class Bootstrap {
+    /**
+     * 启动HTTP服务器
+     * @param befly - Befly实例（需要访问 apiRoutes, pluginLists, appContext, appOptions）
+     * @param callback - 启动后的回调函数
+     */
+    static async start(
+        befly: {
+            apiRoutes: Map<string, ApiRoute>;
+            pluginLists: Plugin[];
+            appContext: BeflyContext;
+            appOptions: any;
+        },
+        callback?: (server: Server) => void
+    ): Promise<Server> {
+        const startTime = Bun.nanoseconds();
+
+        const server = Bun.serve({
+            port: Env.APP_PORT,
+            hostname: Env.APP_HOST,
+            routes: {
+                '/': rootHandler,
+                '/api/*': apiHandler(befly.apiRoutes, befly.pluginLists, befly.appContext),
+                '/*': staticHandler,
+                ...(befly.appOptions.routes || {})
+            },
+            error: (error: Error) => {
+                Logger.error('服务启动时发生错误', error);
+                return Response.json(No('内部服务器错误'));
+            }
+        });
+
+        const finalStartupTime = calcPerfTime(startTime);
+        Logger.info(`Befly 服务器启动成功! 服务器启动耗时: ${finalStartupTime}`);
+        Logger.info(`服务器监听地址: http://${Env.APP_HOST}:${Env.APP_PORT}`);
+
+        if (callback && typeof callback === 'function') {
+            callback(server);
+        }
+
+        return server;
+    }
+}