befly 2.3.2 → 3.0.0

package/types/api.d.ts

@@ -0,0 +1,246 @@
+/**
+ * Befly API 类型定义
+ */
+
+import type { BeflyContext } from './befly.js';
+import type { KeyValue, TableDefinition } from './common.js';
+import type { RequestContext } from './context.js';
+
+/**
+ * HTTP 方法类型
+ */
+export type HttpMethod = 'GET' | 'POST' | 'PUT' | 'DELETE' | 'PATCH' | 'HEAD' | 'OPTIONS';
+
+/**
+ * 请求上下文类型（已废弃，使用 RequestContext 类）
+ * @deprecated 使用 RequestContext 类替代
+ */
+export interface RequestContext<T = any> {
+    /** 请求对象 */
+    request: Request;
+
+    /** 请求体参数 */
+    body: T;
+
+    /** URL 参数 */
+    query: KeyValue<string>;
+
+    /** 路径参数 */
+    pathParams: KeyValue<string>;
+
+    /** 请求头 */
+    headers: Headers;
+
+    /** 用户信息（认证后） */
+    user?: UserInfo;
+
+    /** 客户端 IP */
+    ip?: string;
+
+    /** User-Agent */
+    userAgent?: string;
+
+    /** 请求 ID */
+    requestId?: string;
+
+    /** 开始时间 */
+    startTime: number;
+}
+
+/**
+ * 用户信息类型
+ */
+export interface UserInfo {
+    id: number;
+    username?: string;
+    email?: string;
+    role?: string;
+    [key: string]: any;
+}
+
+/**
+ * 认证类型
+ * - false: 不需要认证
+ * - true: 需要认证（验证 token）
+ * - 'admin': 需要管理员权限
+ * - 'user': 需要普通用户权限
+ * - string[]: 需要特定角色
+ */
+export type AuthType = boolean | 'admin' | 'user' | string[];
+
+/**
+ * API 处理器函数类型
+ */
+export type ApiHandler<T = any, R = any> = (befly: BeflyContext, ctx: RequestContext, req?: Request) => Promise<Response | R> | Response | R;
+
+/**
+ * 字段规则定义
+ * 键为字段名，值为字段规则字符串
+ */
+export type FieldRules = Record<string, string>;
+
+/**
+ * API 配置选项
+ */
+export interface ApiOptions {
+    /** HTTP 方法 */
+    method: HttpMethod;
+    /** 是否需要认证（true/false/角色数组） */
+    auth?: boolean | string[];
+    /** 字段规则 */
+    fields?: FieldRules;
+    /** 必填字段 */
+    required?: string[];
+    /** 处理函数 */
+    handler: ApiHandler;
+}
+
+/**
+ * API 路由配置
+ */
+export interface ApiRoute<T = any, R = any> {
+    /** HTTP 方法 */
+    method: HttpMethod;
+
+    /** 接口名称 */
+    name: string;
+
+    /** 路由路径（运行时生成） */
+    route?: string;
+
+    /** 认证类型 */
+    auth: boolean | string | string[];
+
+    /** 字段定义（验证规则） */
+    fields: TableDefinition;
+
+    /** 必填字段 */
+    required: string[];
+
+    /** 处理器函数 */
+    handler: ApiHandler<T, R>;
+}
+
+/**
+ * API 构建器接口
+ */
+export interface ApiBuilder {
+    /** 设置 HTTP 方法 */
+    method(method: HttpMethod): this;
+
+    /** 设置路径 */
+    path(path: string): this;
+
+    /** 设置描述 */
+    description(desc: string): this;
+
+    /** 设置认证 */
+    auth(auth: AuthType): this;
+
+    /** 设置验证规则 */
+    rules(rules: KeyValue<string>): this;
+
+    /** 设置必填字段 */
+    required(fields: string[]): this;
+
+    /** 设置处理器 */
+    handler(handler: ApiHandler): this;
+
+    /** 构建路由 */
+    build(): ApiRoute;
+}
+
+/**
+ * API 响应辅助函数
+ */
+export interface ApiResponse {
+    /** 成功响应 */
+    success<T = any>(message: string, data?: T): Response;
+
+    /** 失败响应 */
+    error(message: string, error?: any): Response;
+
+    /** JSON 响应 */
+    json<T = any>(data: T, status?: number): Response;
+
+    /** 文本响应 */
+    text(text: string, status?: number): Response;
+
+    /** HTML 响应 */
+    html(html: string, status?: number): Response;
+
+    /** 重定向 */
+    redirect(url: string, status?: number): Response;
+}
+
+/**
+ * 路由匹配结果
+ */
+export interface RouteMatch {
+    /** 路由配置 */
+    route: ApiRoute;
+
+    /** 路径参数 */
+    params: KeyValue<string>;
+}
+
+/**
+ * 路由器接口
+ */
+export interface Router {
+    /** 添加路由 */
+    add(route: ApiRoute): void;
+
+    /** 匹配路由 */
+    match(method: HttpMethod, path: string): RouteMatch | null;
+
+    /** 获取所有路由 */
+    getRoutes(): ApiRoute[];
+
+    /** 删除路由 */
+    remove(method: HttpMethod, path: string): boolean;
+}
+
+// ========== API 响应数据类型 ==========
+
+/**
+ * 令牌检测响应数据
+ */
+export interface TokenCheckData {
+    /** 令牌是否有效 */
+    valid: boolean;
+    /** JWT 载荷（有效时返回） */
+    payload?: any;
+    /** 过期时间（秒） */
+    expiresIn?: number;
+}
+
+/**
+ * 健康检查响应数据
+ */
+export interface HealthInfo {
+    /** 服务状态 */
+    status: string;
+    /** 时间戳 */
+    timestamp: string;
+    /** 运行时长（秒） */
+    uptime: number;
+    /** 内存使用情况 */
+    memory: NodeJS.MemoryUsage;
+    /** 运行时名称 */
+    runtime: string;
+    /** 版本号 */
+    version: string;
+    /** 平台 */
+    platform: string;
+    /** 架构 */
+    arch: string;
+    /** Redis 状态 */
+    redis?: string;
+    /** Redis 错误信息 */
+    redisError?: string;
+    /** 数据库状态 */
+    database?: string;
+    /** 数据库错误信息 */
+    databaseError?: string;
+}

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;