befly 2.3.3 → 3.0.1

package/scripts/syncDb/types.ts

@@ -0,0 +1,92 @@
+/**
+ * syncDb 类型定义模块
+ *
+ * 集中管理核心类型定义
+ */
+
+// ==================== 数据库相关类型 ====================
+
+/**
+ * 列信息接口
+ */
+export interface ColumnInfo {
+    type: string;
+    columnType: string;
+    length: number | null;
+    nullable: boolean;
+    defaultValue: any;
+    comment: string | null;
+}
+
+/**
+ * 索引信息接口（键为索引名，值为列名数组）
+ */
+export interface IndexInfo {
+    [indexName: string]: string[];
+}
+
+// ==================== 变更相关类型 ====================
+
+/**
+ * 字段变更接口
+ */
+export interface FieldChange {
+    type: 'length' | 'datatype' | 'comment' | 'default';
+    current: any;
+    expected: any;
+}
+
+/**
+ * 索引操作接口
+ */
+export interface IndexAction {
+    action: 'create' | 'drop';
+    indexName: string;
+    fieldName: string;
+}
+
+/**
+ * 表变更计划接口
+ */
+export interface TablePlan {
+    changed: boolean;
+    addClauses: string[];
+    modifyClauses: string[];
+    defaultClauses: string[];
+    indexActions: IndexAction[];
+    commentActions?: string[];
+}
+
+// ==================== 统计相关类型 ====================
+
+/**
+ * 全局统计对象
+ */
+export interface GlobalStats {
+    processedTables: number;
+    createdTables: number;
+    modifiedTables: number;
+    addFields: number;
+    nameChanges: number;
+    typeChanges: number;
+    minChanges: number;
+    maxChanges: number;
+    defaultChanges: number;
+    indexCreate: number;
+    indexDrop: number;
+}
+
+// ==================== 解析相关类型 ====================
+
+/**
+ * 解析后的字段规则
+ */
+export interface ParsedFieldRule {
+    name: string;
+    type: string;
+    min: any;
+    max: any;
+    default: any;
+    index: number;
+    regex: string;
+}

package/scripts/syncDb/version.ts

@@ -0,0 +1,73 @@
+/**
+ * syncDb 数据库版本检查模块
+ *
+ * 包含：
+ * - 数据库版本验证（MySQL/PostgreSQL/SQLite）
+ */
+
+import { Logger } from '../../utils/logger.js';
+import { Env } from '../../config/env.js';
+import { DB_VERSION_REQUIREMENTS, IS_MYSQL, IS_PG, IS_SQLITE } from './constants.js';
+import type { SQL } from 'bun';
+
+/**
+ * 数据库版本检查（按方言）
+ *
+ * 根据当前数据库类型检查版本是否符合最低要求：
+ * - MySQL: >= 8.0
+ * - PostgreSQL: >= 17
+ * - SQLite: >= 3.50.0
+ *
+ * @param sql - SQL 客户端实例
+ * @throws {Error} 如果数据库版本不符合要求或无法获取版本信息
+ */
+export async function ensureDbVersion(sql: SQL): Promise<void> {
+    if (!sql) throw new Error('SQL 客户端未初始化');
+
+    if (IS_MYSQL) {
+        const r = await sql`SELECT VERSION() AS version`;
+        if (!r || r.length === 0 || !r[0]?.version) {
+            throw new Error('无法获取 MySQL 版本信息');
+        }
+        const version = r[0].version;
+        const majorVersion = parseInt(String(version).split('.')[0], 10);
+        if (!Number.isFinite(majorVersion) || majorVersion < DB_VERSION_REQUIREMENTS.MYSQL_MIN_MAJOR) {
+            throw new Error(`此脚本仅支持 MySQL ${DB_VERSION_REQUIREMENTS.MYSQL_MIN_MAJOR}.0+，当前版本: ${version}`);
+        }
+        Logger.info(`MySQL 版本: ${version}`);
+        return;
+    }
+
+    if (IS_PG) {
+        const r = await sql`SELECT version() AS version`;
+        if (!r || r.length === 0 || !r[0]?.version) {
+            throw new Error('无法获取 PostgreSQL 版本信息');
+        }
+        const versionText = r[0].version;
+        Logger.info(`PostgreSQL 版本: ${versionText}`);
+        const m = /PostgreSQL\s+(\d+)/i.exec(versionText);
+        const major = m ? parseInt(m[1], 10) : NaN;
+        if (!Number.isFinite(major) || major < DB_VERSION_REQUIREMENTS.POSTGRES_MIN_MAJOR) {
+            throw new Error(`此脚本要求 PostgreSQL >= ${DB_VERSION_REQUIREMENTS.POSTGRES_MIN_MAJOR}，当前: ${versionText}`);
+        }
+        return;
+    }
+
+    if (IS_SQLITE) {
+        const r = await sql`SELECT sqlite_version() AS version`;
+        if (!r || r.length === 0 || !r[0]?.version) {
+            throw new Error('无法获取 SQLite 版本信息');
+        }
+        const version = r[0].version;
+        Logger.info(`SQLite 版本: ${version}`);
+        // 强制最低版本：SQLite ≥ 3.50.0
+        const [maj, min, patch] = String(version)
+            .split('.')
+            .map((v) => parseInt(v, 10) || 0);
+        const vnum = maj * 10000 + min * 100 + patch; // 3.50.0 -> 35000
+        if (!Number.isFinite(vnum) || vnum < DB_VERSION_REQUIREMENTS.SQLITE_MIN_VERSION_NUM) {
+            throw new Error(`此脚本要求 SQLite >= ${DB_VERSION_REQUIREMENTS.SQLITE_MIN_VERSION}，当前: ${version}`);
+        }
+        return;
+    }
+}

package/scripts/syncDb.ts

@@ -0,0 +1,10 @@
+import { SyncDb } from './syncDb/index.js';
+import { Logger } from '../utils/logger.js';
+
+// 如果直接运行此脚本
+if (import.meta.main) {
+    SyncDb().catch((error) => {
+        Logger.error('数据库同步失败', error);
+        process.exit(1);
+    });
+}

package/tsconfig.json

@@ -0,0 +1,58 @@
+{
+    "compilerOptions": {
+        // 基础配置
+        "target": "ESNext",
+        "module": "ESNext",
+        "lib": ["ESNext"],
+        "moduleResolution": "bundler",
+
+        // 类型检查
+        "strict": true,
+        "noImplicitAny": true,
+        "strictNullChecks": true,
+        "strictFunctionTypes": true,
+        "strictBindCallApply": true,
+        "strictPropertyInitialization": true,
+        "noImplicitThis": true,
+        "alwaysStrict": true,
+
+        // 额外检查
+        "noUnusedLocals": true,
+        "noUnusedParameters": true,
+        "noImplicitReturns": true,
+        "noFallthroughCasesInSwitch": true,
+        "noUncheckedIndexedAccess": false,
+        "noImplicitOverride": true,
+        "noPropertyAccessFromIndexSignature": false,
+
+        // 模块
+        "esModuleInterop": true,
+        "allowSyntheticDefaultImports": true,
+        "forceConsistentCasingInFileNames": true,
+        "resolveJsonModule": true,
+        "isolatedModules": true,
+
+        // 输出
+        "declaration": true,
+        "declarationMap": true,
+        "sourceMap": true,
+        "removeComments": false,
+        "importHelpers": false,
+
+        // 高级
+        "skipLibCheck": true,
+        "allowJs": true,
+        "checkJs": false,
+
+        // Bun 特定
+        "types": ["bun-types"],
+
+        // 路径
+        "baseUrl": ".",
+        "paths": {
+            "@/*": ["./*"]
+        }
+    },
+    "include": ["**/*.ts", "**/*.js"],
+    "exclude": ["node_modules", "dist", "**/*.test.ts", "**/*.test.js"]
+}

package/types/addon.d.ts

@@ -0,0 +1,53 @@
+/**
+ * Addon 配置类型定义
+ */
+
+/**
+ * Addon 作者信息
+ */
+export interface AddonAuthor {
+    /** 作者名称 */
+    name: string;
+    /** 作者邮箱 */
+    email?: string;
+    /** 作者网站 */
+    url?: string;
+}
+
+/**
+ * Addon 配置
+ */
+export interface AddonConfig {
+    /** Addon 唯一标识（小写、短横线或下划线），例如 "admin"、"demo" */
+    name: string;
+
+    /** Addon 人类可读名称，例如 "管理后台" */
+    title: string;
+
+    /** 版本号（语义化版本），例如 "1.0.0" */
+    version?: string;
+
+    /** 简短描述 */
+    description?: string;
+
+    /** 作者信息 */
+    author?: AddonAuthor | string;
+
+    /** 源码仓库链接 */
+    repo?: string;
+
+    /** 关键词（用于搜索和分类） */
+    keywords?: string[];
+
+    /** 主入口文件路径（相对于 addon 目录），例如 "index.ts" */
+    entry?: string;
+
+    /** 是否默认启用 */
+    enabled?: boolean;
+
+    /** 依赖的其他 addon 或核心包 */
+    dependencies?: Record<string, string>;
+
+    /** 许可证 */
+    license?: string;
+}

package/types/api.d.ts

@@ -0,0 +1,249 @@
+/**
+ * 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> {
+    /** 接口名称（必填） */
+    name: string;
+
+    /** 处理器函数（必填） */
+    handler: ApiHandler<T, R>;
+
+    /** HTTP 方法（可选，默认 POST） */
+    method?: HttpMethod;
+
+    /** 认证类型（可选，默认 true）
+     * - true: 需要登录
+     * - false: 公开访问（无需登录）
+     */
+    auth?: boolean;
+
+    /** 字段定义（验证规则）（可选，默认 {}） */
+    fields?: TableDefinition;
+
+    /** 必填字段（可选，默认 []） */
+    required?: string[];
+
+    /** 路由路径（运行时生成） */
+    route?: string;
+}
+
+/**
+ * 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;
+}