befly 2.3.3 → 3.0.0

package/types/befly.d.ts

@@ -0,0 +1,234 @@
+/**
+ * Befly 核心框架类型定义
+ */
+
+import type { Plugin } from './plugin.js';
+import type { ApiRoute, HttpMethod } from './api.js';
+import type { KeyValue } from './common.js';
+import type { Logger } from '../utils/logger.js';
+import type { Jwt } from '../utils/jwt.js';
+import type { Validator } from '../utils/validate.js';
+import type { SqlHelper } from '../utils/sqlHelper.js';
+import type { Crypto2 } from '../utils/crypto.js';
+import type { Tool } from '../utils/tool.js';
+
+/**
+ * Befly 应用选项
+ */
+export interface BeflyOptions {
+    /** 应用名称 */
+    name?: string;
+
+    /** 监听主机 */
+    host?: string;
+
+    /** 监听端口 */
+    port?: number;
+
+    /** 是否启用 CORS */
+    cors?: boolean | CorsOptions;
+
+    /** 静态文件目录 */
+    staticDir?: string;
+
+    /** 上传文件目录 */
+    uploadDir?: string;
+
+    /** 最大请求体大小 */
+    maxBodySize?: number;
+
+    /** 自定义配置 */
+    [key: string]: any;
+}
+
+/**
+ * CORS 配置选项
+ */
+export interface CorsOptions {
+    origin?: string | string[] | boolean;
+    methods?: string[];
+    allowedHeaders?: string[];
+    exposedHeaders?: string[];
+    credentials?: boolean;
+    maxAge?: number;
+}
+
+/**
+ * Befly 核心类
+ */
+export interface Befly {
+    /** API 路由映射 */
+    apiRoutes: Map<string, ApiRoute>;
+
+    /** 插件列表 */
+    pluginLists: Plugin[];
+
+    /** 应用上下文 */
+    appContext: KeyValue;
+
+    /** 应用选项 */
+    appOptions: BeflyOptions;
+
+    /** 日志器 */
+    logger: Logger;
+
+    /** JWT 工具 */
+    jwt: Jwt;
+
+    /** 验证器 */
+    validator: Validator;
+
+    /** SQL 管理器 */
+    sql: SqlHelper;
+
+    /** 加密工具 */
+    crypto: Crypto2;
+
+    /** 通用工具 */
+    tool: Tool;
+
+    /** 数据库连接 */
+    db: any;
+
+    /** Redis 连接 */
+    redis: any;
+
+    /**
+     * 初始化检查器
+     */
+    initCheck(): Promise<void>;
+
+    /**
+     * 加载插件
+     */
+    loadPlugins(): Promise<void>;
+
+    /**
+     * 加载 API 路由
+     */
+    loadApis(): Promise<void>;
+
+    /**
+     * 启动服务器
+     */
+    start(): Promise<void>;
+
+    /**
+     * 停止服务器
+     */
+    stop(): Promise<void>;
+
+    /**
+     * 处理请求
+     */
+    handleRequest(request: Request): Promise<Response>;
+
+    /**
+     * 注册中间件
+     */
+    use(middleware: Function): void;
+
+    /**
+     * 获取配置
+     */
+    getConfig(key: string): any;
+
+    /**
+     * 设置配置
+     */
+    setConfig(key: string, value: any): void;
+}
+
+/**
+ * Befly 构造函数类型
+ */
+export interface BeflyConstructor {
+    new (options?: BeflyOptions): Befly;
+}
+
+/**
+ * 服务器启动选项
+ */
+export interface ServerOptions {
+    /** 主机名 */
+    hostname: string;
+
+    /** 端口 */
+    port: number;
+
+    /** 请求处理函数 */
+    fetch: (request: Request) => Promise<Response>;
+
+    /** 错误处理函数 */
+    error?: (error: Error) => Response;
+
+    /** 开发模式 */
+    development?: boolean;
+}
+
+/**
+ * 服务器实例
+ */
+export interface Server {
+    /** 主机名 */
+    hostname: string;
+
+    /** 端口 */
+    port: number;
+
+    /** 停止服务器 */
+    stop(): Promise<void>;
+
+    /** 重启服务器 */
+    reload(options: ServerOptions): void;
+}
+
+/**
+ * 检查函数类型
+ */
+export type CheckFunction = (befly: Befly) => Promise<void> | void;
+
+/**
+ * 检查结果
+ */
+export interface CheckResult {
+    /** 文件名 */
+    filename: string;
+
+    /** 检查名称 */
+    checkName: string;
+
+    /** 是否通过 */
+    passed: boolean;
+
+    /** 执行时间（纳秒） */
+    duration: number;
+
+    /** 错误信息 */
+    error?: Error;
+}
+
+/**
+ * 性能统计
+ */
+export interface PerformanceStats {
+    /** 启动时间 */
+    startTime: number;
+
+    /** 检查时间 */
+    checkTime: number;
+
+    /** 插件加载时间 */
+    pluginTime: number;
+
+    /** API 加载时间 */
+    apiTime: number;
+
+    /** 总时间 */
+    totalTime: number;
+}
+
+/**
+ * 导出 Befly 实例创建函数
+ */
+export function createBefly(options?: BeflyOptions): Befly;

package/types/common.d.ts

@@ -0,0 +1,215 @@
+/**
+ * Befly 框架通用类型定义
+ */
+
+/**
+ * 响应结果类型
+ */
+export interface ResponseResult<T = any> {
+    code: number;
+    msg: string;
+    data?: T;
+    error?: any;
+}
+
+/**
+ * 验证结果类型
+ */
+export interface ValidationResult {
+    code: 0 | 1;
+    fields: Record<string, any>;
+}
+
+/**
+ * 字段规则字符串
+ * 格式: "字段名|类型|最小值|最大值|默认值|是否索引|正则约束"
+ *
+ * @example
+ * "用户名|string|2|50|null|1|^[a-zA-Z0-9_]+$"
+ * "年龄|number|0|150|18|0|null"
+ */
+export type FieldRule = string;
+
+/**
+ * 表定义类型
+ */
+export type TableDefinition = Record<string, FieldRule>;
+
+/**
+ * 解析后的字段规则
+ */
+export interface ParsedFieldRule {
+    name: string; // 字段名称
+    type: 'string' | 'number' | 'text' | 'array';
+    min: number | null; // 最小值
+    max: number | null; // 最大值
+    default: any; // 默认值
+    index: 0 | 1; // 是否索引
+    regex: string | null; // 正则约束
+}
+
+/**
+ * SQL 查询参数类型
+ */
+export type SqlValue = string | number | boolean | null | Date;
+export type SqlParams = SqlValue[];
+
+/**
+ * 排序方向
+ */
+export type OrderDirection = 'ASC' | 'DESC' | 'asc' | 'desc';
+
+/**
+ * 比较运算符
+ */
+export type ComparisonOperator = '=' | '>' | '<' | '>=' | '<=' | '!=' | '<>' | 'LIKE' | 'IN' | 'NOT IN' | 'IS NULL' | 'IS NOT NULL';
+
+/**
+ * JOIN 类型
+ */
+export type JoinType = 'INNER' | 'LEFT' | 'RIGHT' | 'FULL';
+
+/**
+ * 数据库配置类型
+ */
+export interface DatabaseConfig {
+    host: string;
+    port: number;
+    user: string;
+    password: string;
+    database: string;
+    connectionLimit?: number;
+}
+
+/**
+ * Redis 配置类型
+ */
+export interface RedisConfig {
+    host: string;
+    port: number;
+    password?: string;
+    db?: number;
+}
+
+/**
+ * 日志级别
+ */
+export type LogLevel = 'trace' | 'debug' | 'info' | 'warn' | 'error' | 'fatal';
+
+/**
+ * 日志配置
+ */
+export interface LoggerConfig {
+    level?: LogLevel;
+    transport?: {
+        target: string;
+        options?: Record<string, any>;
+    };
+}
+
+/**
+ * 环境变量类型
+ */
+export interface EnvConfig {
+    // 服务配置
+    appName: string;
+    appHost: string;
+    appPort: number;
+
+    // 数据库配置
+    mysqlHost: string;
+    mysqlPort: number;
+    mysqlUsername: string;
+    mysqlPassword: string;
+    mysqlDatabase: string;
+
+    // Redis 配置
+    redisHost?: string;
+    redisPort?: number;
+    redisPassword?: string;
+
+    // JWT 配置
+    jwtSecret: string;
+    jwtExpires?: string;
+
+    // 其他配置
+    [key: string]: any;
+}
+
+/**
+ * 工具函数返回类型
+ */
+export interface ToolResponse<T = any> {
+    success: boolean;
+    data?: T;
+    error?: string;
+}
+
+/**
+ * 分页参数
+ */
+export interface PaginationParams {
+    page: number;
+    limit: number;
+}
+
+/**
+ * 分页结果
+ */
+export interface PaginatedResult<T = any> {
+    total: number;
+    page: number;
+    limit: number;
+    data: T[];
+}
+
+/**
+ * 通用键值对
+ */
+export type KeyValue<T = any> = Record<string, T>;
+
+/**
+ * 可选字段
+ */
+export type Optional<T> = T | null | undefined;
+
+/**
+ * 深度可选
+ */
+export type DeepPartial<T> = T extends object ? { [P in keyof T]?: DeepPartial<T[P]> } : T;
+
+/**
+ * 保留字段（系统自动管理）
+ */
+export type ReservedFields = 'id' | 'created_at' | 'updated_at' | 'deleted_at' | 'state';
+
+/**
+ * 排除保留字段
+ */
+export type ExcludeReserved<T> = Omit<T, ReservedFields>;
+
+/**
+ * 数据库记录基础类型
+ */
+export interface BaseRecord {
+    id: number;
+    created_at: Date;
+    updated_at: Date;
+    deleted_at: Date | null;
+    state: number;
+}
+
+/**
+ * 异步函数类型
+ */
+export type AsyncFunction<T = any> = (...args: any[]) => Promise<T>;
+
+/**
+ * 同步函数类型
+ */
+export type SyncFunction<T = any> = (...args: any[]) => T;
+
+/**
+ * 通用回调函数
+ */
+export type Callback<T = any> = (error: Error | null, result?: T) => void;

package/types/context.ts

@@ -0,0 +1,167 @@
+/**
+ * 请求上下文类
+ * 提供统一的请求数据访问接口和类型安全
+ */
+
+/**
+ * 标准请求上下文类
+ */
+export class RequestContext {
+    /** 原始请求对象 */
+    public readonly request: Request;
+
+    /** 请求开始时间（毫秒） */
+    public readonly startTime: number;
+
+    /** 请求体参数 (GET/POST 解析后的数据) */
+    public body: Record<string, any> = {};
+
+    /** 用户信息 (认证后填充) */
+    public user: Record<string, any> = {};
+
+    /** 自定义状态 (用于在中间件间传递数据) */
+    public state: Record<string, any> = {};
+
+    /** 响应数据 (由 handler 设置) */
+    public response?: any;
+
+    constructor(req: Request) {
+        this.request = req;
+        this.startTime = Date.now();
+    }
+
+    // ========== 便捷访问器 ==========
+
+    /**
+     * 获取请求方法
+     */
+    get method(): string {
+        return this.request.method;
+    }
+
+    /**
+     * 获取请求 URL
+     */
+    get url(): string {
+        return this.request.url;
+    }
+
+    /**
+     * 获取请求头对象
+     */
+    get headers(): Headers {
+        return this.request.headers;
+    }
+
+    /**
+     * 获取客户端 IP 地址
+     */
+    get ip(): string | null {
+        return this.request.headers.get('x-forwarded-for') || this.request.headers.get('x-real-ip') || this.request.headers.get('cf-connecting-ip') || null;
+    }
+
+    /**
+     * 获取 User-Agent
+     */
+    get userAgent(): string | null {
+        return this.request.headers.get('user-agent');
+    }
+
+    /**
+     * 获取 Content-Type
+     */
+    get contentType(): string | null {
+        return this.request.headers.get('content-type');
+    }
+
+    // ========== 工具方法 ==========
+
+    /**
+     * 获取请求头
+     * @param name - 请求头名称
+     */
+    header(name: string): string | null {
+        return this.request.headers.get(name);
+    }
+
+    /**
+     * 获取参数值
+     * @param key - 参数键名
+     */
+    get(key: string): any {
+        return this.body[key];
+    }
+
+    /**
+     * 设置参数值
+     * @param key - 参数键名
+     * @param value - 参数值
+     */
+    set(key: string, value: any): void {
+        this.body[key] = value;
+    }
+
+    /**
+     * 检查参数是否存在
+     * @param key - 参数键名
+     */
+    has(key: string): boolean {
+        return key in this.params;
+    }
+
+    /**
+     * 获取所有参数
+     */
+    all(): Record<string, any> {
+        return { ...this.params };
+    }
+
+    /**
+     * 计算请求耗时（毫秒）
+     */
+    getElapsedTime(): number {
+        return Date.now() - this.startTime;
+    }
+
+    /**
+     * 获取格式化的请求信息（用于日志）
+     */
+    getRequestInfo(): Record<string, any> {
+        return {
+            method: this.method,
+            url: this.url,
+            ip: this.ip,
+            userAgent: this.userAgent,
+            elapsedTime: this.getElapsedTime()
+        };
+    }
+
+    /**
+     * 设置响应数据
+     * @param data - 响应数据
+     */
+    setResponse(data: any): void {
+        this.response = data;
+    }
+
+    /**
+     * 判断用户是否已登录
+     */
+    isAuthenticated(): boolean {
+        return !!this.user.id;
+    }
+
+    /**
+     * 获取用户 ID
+     */
+    getUserId(): number | null {
+        return this.user.id || null;
+    }
+
+    /**
+     * 获取用户角色
+     */
+    getUserRole(): string | null {
+        return this.user.role || this.user.role_type || null;
+    }
+}

package/types/crypto.d.ts

@@ -0,0 +1,23 @@
+/**
+ * 加密相关类型定义
+ */
+
+/**
+ * 编码类型
+ */
+export type EncodingType = 'hex' | 'base64' | 'base64url';
+
+/**
+ * 哈希算法类型
+ */
+export type HashAlgorithm = 'md5' | 'sha1' | 'sha256' | 'sha512' | 'sha384' | 'sha224';
+
+/**
+ * 密码哈希选项
+ */
+export interface PasswordHashOptions {
+    algorithm?: 'argon2' | 'bcrypt';
+    memoryCost?: number;
+    timeCost?: number;
+    [key: string]: any;
+}