befly 3.8.19 → 3.8.21

package/tests/validator.test.ts

@@ -0,0 +1,148 @@
+import { describe, test, expect } from 'bun:test';
+import { Validator } from '../lib/validator';
+
+const validator = new Validator();
+
+describe('Validator - 基本验证', () => {
+    test('验证通过', () => {
+        const data = { username: 'john' };
+        const rules = { username: { name: '用户名', type: 'string', min: 2, max: 20 } };
+        const result = validator.validate(data, rules);
+        expect(result.code).toBe(0);
+        expect(Object.keys(result.fields).length).toBe(0);
+    });
+
+    test('验证失败 - 必填字段缺失', () => {
+        const data = {};
+        const rules = { username: { name: '用户名', type: 'string', min: 2, max: 20 } };
+        const required = ['username'];
+        const result = validator.validate(data, rules, required);
+        expect(result.code).toBe(1);
+        expect(result.fields.username).toContain('必填项');
+    });
+
+    test('验证失败 - 字段值为空', () => {
+        const data = { username: '' };
+        const rules = { username: { name: '用户名', type: 'string', min: 2, max: 20 } };
+        const required = ['username'];
+        const result = validator.validate(data, rules, required);
+        expect(result.code).toBe(1);
+        expect(result.fields.username).toBeDefined();
+    });
+});
+
+describe('Validator - 类型验证', () => {
+    test('string 类型', () => {
+        const data = { name: 'test' };
+        const rules = { name: { name: '名称', type: 'string', min: 2, max: 10 } };
+        const result = validator.validate(data, rules);
+        expect(result.code).toBe(0);
+    });
+
+    test('number 类型', () => {
+        const data = { age: 25 };
+        const rules = { age: { name: '年龄', type: 'number', min: 0, max: 150 } };
+        const result = validator.validate(data, rules);
+        expect(result.code).toBe(0);
+    });
+
+    test('email 验证', () => {
+        const data = { email: 'test@example.com' };
+        const rules = { email: { name: '邮箱', type: 'string', regexp: '@email' } };
+        const result = validator.validate(data, rules);
+        expect(result.code).toBe(0);
+    });
+
+    test('phone 验证', () => {
+        const data = { phone: '13800138000' };
+        const rules = { phone: { name: '手机号', type: 'string', regexp: '@phone' } };
+        const result = validator.validate(data, rules);
+        expect(result.code).toBe(0);
+    });
+});
+
+describe('Validator - 长度验证', () => {
+    test('string 最小长度', () => {
+        const data = { name: 'a' };
+        const rules = { name: { name: '名称', type: 'string', min: 2, max: 10 } };
+        const result = validator.validate(data, rules);
+        expect(result.code).toBe(1);
+        expect(result.fields.name).toBeDefined();
+    });
+
+    test('string 最大长度', () => {
+        const data = { name: 'a'.repeat(20) };
+        const rules = { name: { name: '名称', type: 'string', min: 2, max: 10 } };
+        const result = validator.validate(data, rules);
+        expect(result.code).toBe(1);
+        expect(result.fields.name).toBeDefined();
+    });
+
+    test('number 范围验证', () => {
+        const data = { age: 200 };
+        const rules = { age: { name: '年龄', type: 'number', min: 0, max: 150 } };
+        const result = validator.validate(data, rules);
+        expect(result.code).toBe(1);
+        expect(result.fields.age).toBeDefined();
+    });
+});
+
+describe('Validator - 正则验证', () => {
+    test('正则别名 @email - 有效邮箱', () => {
+        const data = { email: 'test@example.com' };
+        const rules = { email: { name: '邮箱', type: 'string', regexp: '@email' } };
+        const result = validator.validate(data, rules);
+        expect(result.code).toBe(0);
+    });
+
+    test('正则别名 @email - 无效邮箱', () => {
+        const data = { email: 'invalid-email' };
+        const rules = { email: { name: '邮箱', type: 'string', regexp: '@email' } };
+        const result = validator.validate(data, rules);
+        expect(result.code).toBe(1);
+        expect(result.fields.email).toBeDefined();
+    });
+
+    test('正则别名 @phone - 有效手机号', () => {
+        const data = { phone: '13800138000' };
+        const rules = { phone: { name: '手机号', type: 'string', regexp: '@phone' } };
+        const result = validator.validate(data, rules);
+        expect(result.code).toBe(0);
+    });
+
+    test('正则别名 @phone - 无效手机号', () => {
+        const data = { phone: '12345' };
+        const rules = { phone: { name: '手机号', type: 'string', regexp: '@phone' } };
+        const result = validator.validate(data, rules);
+        expect(result.code).toBe(1);
+        expect(result.fields.phone).toBeDefined();
+    });
+
+    test('自定义正则 - 纯数字', () => {
+        const data = { code: '12a' };
+        const rules = { code: { name: '验证码', type: 'string', regexp: '^\\d+$' } };
+        const result = validator.validate(data, rules);
+        expect(result.code).toBe(1);
+        expect(result.fields.code).toBeDefined();
+    });
+});
+
+describe('Validator - 参数检查', () => {
+    test('data 不是对象', () => {
+        const result = validator.validate(null as any, {});
+        expect(result.code).toBe(1);
+        expect(result.fields.error).toContain('对象格式');
+    });
+
+    test('rules 不是对象', () => {
+        const result = validator.validate({}, null as any);
+        expect(result.code).toBe(1);
+        expect(result.fields.error).toContain('对象格式');
+    });
+
+    test('required 不是数组', () => {
+        const result = validator.validate({}, {}, 'invalid' as any);
+        expect(result.code).toBe(1);
+        expect(result.fields.error).toContain('数组格式');
+    });
+});

package/tests/xml.test.ts

@@ -0,0 +1,101 @@
+import { describe, test, expect } from 'bun:test';
+import { Xml } from '../lib/xml';
+
+describe('Xml - 基本解析', () => {
+    test('解析简单元素', () => {
+        const xml = new Xml();
+        const result = xml.parse('<root>Hello</root>');
+        expect(result).toBe('Hello');
+    });
+
+    test('解析嵌套元素', () => {
+        const xml = new Xml();
+        const result = xml.parse('<root><child>Value</child></root>');
+        expect(result).toEqual({ child: 'Value' });
+    });
+
+    test('解析多个同名元素', () => {
+        const xml = new Xml();
+        const result = xml.parse('<root><item>A</item><item>B</item></root>');
+        expect(result).toEqual({ item: ['A', 'B'] });
+    });
+
+    test('解析空元素', () => {
+        const xml = new Xml();
+        const result = xml.parse('<root></root>');
+        expect(result).toBe('');
+    });
+
+    test('解析自闭合标签', () => {
+        const xml = new Xml();
+        const result = xml.parse('<root><item/></root>');
+        expect(result).toEqual({ item: '' });
+    });
+});
+
+describe('Xml - 属性解析', () => {
+    test('解析元素属性', () => {
+        const xml = new Xml();
+        const result = xml.parse('<root id="1">Value</root>') as any;
+        expect(result['@id']).toBe('1');
+        expect(result['#text']).toBe('Value');
+    });
+
+    test('解析多个属性', () => {
+        const xml = new Xml();
+        const result = xml.parse('<user id="123" name="John">Content</user>') as any;
+        expect(result['@id']).toBe('123');
+        expect(result['@name']).toBe('John');
+        expect(result['#text']).toBe('Content');
+    });
+
+    test('忽略属性', () => {
+        const xml = new Xml({ ignoreAttributes: true });
+        const result = xml.parse('<root id="1">Value</root>');
+        expect(result).toBe('Value');
+    });
+});
+
+describe('Xml - 数值解析', () => {
+    test('自动解析数字', () => {
+        const xml = new Xml();
+        const result = xml.parse('<root>123</root>');
+        expect(result).toBe(123);
+    });
+
+    test('自动解析布尔值', () => {
+        const xml = new Xml();
+        const result1 = xml.parse('<root>true</root>');
+        const result2 = xml.parse('<root>false</root>');
+        expect(result1).toBe(true);
+        expect(result2).toBe(false);
+    });
+
+    test('禁用数字解析', () => {
+        const xml = new Xml({ parseNumbers: false });
+        const result = xml.parse('<root>123</root>');
+        expect(result).toBe('123');
+    });
+});
+
+describe('Xml - 错误处理', () => {
+    test('拒绝非字符串输入', () => {
+        const xml = new Xml();
+        expect(() => xml.parse(123 as any)).toThrow('无效的 XML 数据');
+    });
+
+    test('拒绝空字符串', () => {
+        const xml = new Xml();
+        expect(() => xml.parse('')).toThrow('非空字符串');
+    });
+
+    test('拒绝只有空格的字符串', () => {
+        const xml = new Xml();
+        expect(() => xml.parse('   ')).toThrow('非空字符串');
+    });
+
+    test('检测未闭合标签', () => {
+        const xml = new Xml();
+        expect(() => xml.parse('<root><item>')).toThrow('未找到结束标签');
+    });
+});

package/tsconfig.json

@@ -33,9 +33,7 @@
         "isolatedModules": true,
 
         // 输出
-        "declaration": true,
-        "declarationMap": true,
-        "sourceMap": true,
+        "noEmit": true,
         "removeComments": false,
         "importHelpers": false,
 
@@ -45,7 +43,7 @@
         "checkJs": false,
 
         // Bun 特定
-        "types": ["bun-types"],
+        "types": ["bun"],
 
         // 路径
         "baseUrl": ".",

package/types/api.d.ts

@@ -84,6 +84,12 @@ export interface ApiRoute<T = any, R = any> {
     /** 必填字段（可选，默认 []） */
     required?: string[];
 
+    /** 缓存配置（可选，单位：秒） */
+    cache?: number;
+
+    /** 限流配置（可选，格式：次数/秒，如 "10/60" 表示 60秒内10次） */
+    rateLimit?: string;
+
     /** 路由路径（运行时生成） */
     route?: string;
 }

package/types/befly.d.ts

@@ -12,46 +12,170 @@ import type { Database } from 'bun:sqlite';
 import type { DbHelper } from '../lib/dbHelper.js';
 import type { RedisHelper } from '../lib/redisHelper.js';
 import type { Cipher } from '../lib/cipher.js';
+import type { CacheHelper } from '../lib/cacheHelper.js';
 
 /**
- * Befly 应用选项
+ * 日志配置
  */
-export interface BeflyOptions {
-    /** 应用名称 */
-    name?: string;
+export interface LoggerConfig {
+    /** 是否开启调试模式 (0: 关闭, 1: 开启) @default 1 */
+    debug?: number;
+    /** 日志排除字段 (逗号分隔) @default 'password,token,secret' */
+    excludeFields?: string;
+    /** 日志目录 @default './logs' */
+    dir?: string;
+    /** 是否输出到控制台 (0: 关闭, 1: 开启) @default 1 */
+    console?: number;
+    /** 单个日志文件最大大小 (字节) @default 10485760 (10MB) */
+    maxSize?: number;
+}
 
-    /** 监听主机 */
+/**
+ * 数据库配置
+ */
+export interface DatabaseConfig {
+    /** 是否启用数据库 (0: 关闭, 1: 开启) @default 0 */
+    enable?: number;
+    /** 数据库类型 ('mysql' | 'postgres' | 'sqlite') @default 'sqlite' */
+    type?: string;
+    /** 数据库主机 @default '127.0.0.1' */
     host?: string;
-
-    /** 监听端口 */
+    /** 数据库端口 @default 3306 */
     port?: number;
+    /** 数据库用户名 @default 'root' */
+    username?: string;
+    /** 数据库密码 @default '' */
+    password?: string;
+    /** 数据库名称 @default 'befly' */
+    database?: string;
+    /** 连接池最大连接数 @default 1 */
+    poolMax?: number;
+}
 
-    /** 是否启用 CORS */
-    cors?: boolean | CorsOptions;
-
-    /** 静态文件目录 */
-    staticDir?: string;
+/**
+ * Redis 配置
+ */
+export interface RedisConfig {
+    /** Redis 主机 @default '127.0.0.1' */
+    host?: string;
+    /** Redis 端口 @default 6379 */
+    port?: number;
+    /** Redis 用户名 @default '' */
+    username?: string;
+    /** Redis 密码 @default '' */
+    password?: string;
+    /** Redis 数据库索引 @default 0 */
+    db?: number;
+    /** Redis Key 前缀 @default 'befly:' */
+    prefix?: string;
+}
 
-    /** 上传文件目录 */
-    uploadDir?: string;
+/**
+ * JWT 配置
+ */
+export interface AuthConfig {
+    /** JWT 密钥 @default 'befly-secret' */
+    secret?: string;
+    /** 过期时间 @default '7d' */
+    expiresIn?: string | number;
+    /** 签名算法 @default 'HS256' */
+    algorithm?: string;
+}
 
-    /** 最大请求体大小 */
-    maxBodySize?: number;
+/**
+ * CORS 配置
+ */
+export interface CorsConfig {
+    /** 允许的来源 @default '*' */
+    origin?: string;
+    /** 允许的方法 @default 'GET,HEAD,PUT,PATCH,POST,DELETE' */
+    methods?: string;
+    /** 允许的头 @default 'Content-Type,Authorization' */
+    allowedHeaders?: string;
+    /** 暴露的头 @default '' */
+    exposedHeaders?: string;
+    /** 预检请求缓存时间 (秒) @default 86400 */
+    maxAge?: number;
+    /** 是否允许凭证 @default 'true' */
+    credentials?: string;
+}
 
-    /** 自定义配置 */
+/**
+ * Befly 构造函数选项（最多 2 级结构）
+ */
+export interface BeflyOptions {
+    // ========== 核心参数 ==========
+    /** 运行环境 ('development' | 'production') @default 'development' */
+    nodeEnv?: string;
+    /** 应用名称 @default 'Befly App' */
+    appName?: string;
+    /** 应用端口 @default 3000 */
+    appPort?: number;
+    /** 应用主机 @default '0.0.0.0' */
+    appHost?: string;
+    /** 开发者邮箱 (用于 syncDev) @default 'dev@qq.com' */
+    devEmail?: string;
+    /** 开发者密码 (用于 syncDev) */
+    devPassword?: string;
+    /** 请求体大小限制 (字节) @default 1048576 (1MB) */
+    bodyLimit?: number;
+    /** 时区 @default 'Asia/Shanghai' */
+    tz?: string;
+
+    // ========== 插件配置 ==========
+    /** 日志插件配置 */
+    logger?: LoggerConfig;
+    /** 数据库插件配置 */
+    db?: DatabaseConfig;
+    /** Redis 插件配置 */
+    redis?: RedisConfig;
+    /** 认证插件配置 */
+    auth?: AuthConfig;
+    /** CORS 插件配置 */
+    cors?: CorsConfig;
+    /** 禁用的钩子列表 */
+    disableHooks?: string[];
+    /** 禁用的插件列表 */
+    disablePlugins?: string[];
+    /** 其他插件配置 */
     [key: string]: any;
 }
 
 /**
- * CORS 配置选项
- */
-export interface CorsOptions {
-    origin?: string | string[] | boolean;
-    methods?: string[];
-    allowedHeaders?: string[];
-    exposedHeaders?: string[];
-    credentials?: boolean;
-    maxAge?: number;
+ * Befly 应用上下文
+ * 包含所有插件挂载的实例
+ */
+export interface BeflyContext extends KeyValue {
+    // ========== 核心插件（带下划线前缀） ==========
+    /** 数据库助手 (db 插件) */
+    _db?: DbHelper;
+
+    /** Redis 助手 (redis 插件) */
+    _redis?: RedisHelper;
+
+    /** 日志器 (logger 插件) */
+    _logger?: typeof Logger;
+
+    /** 缓存助手 (cache 插件) */
+    _cache?: CacheHelper;
+
+    // ========== 核心插件便捷访问（无前缀） ==========
+    /** 数据库助手便捷访问 */
+    db?: DbHelper;
+
+    /** Redis 助手便捷访问 */
+    redis?: RedisHelper;
+
+    /** 日志器便捷访问 */
+    logger?: typeof Logger;
+
+    /** 缓存助手便捷访问 */
+    cache?: CacheHelper;
+
+    // ========== 动态插件 ==========
+    /** 组件插件：addon_{addonName}_{pluginName} */
+    /** 项目插件：app_{pluginName} */
+    [key: string]: any;
 }
 
 /**
@@ -122,9 +246,9 @@ export interface Befly {
     handleRequest(request: Request): Promise<Response>;
 
     /**
-     * 注册中间件
+     * 注册钩子
      */
-    use(middleware: Function): void;
+    use(hook: Function): void;
 
     /**
      * 获取配置

package/types/context.d.ts

@@ -1,7 +1,33 @@
 /**
  * 请求上下文类型定义
- * 实现代码位于 util.ts，类型定义位于 types/util.d.ts
  */
 
-// 重新导出 RequestContext 接口
-export type { RequestContext } from './util.js';
+import type { ApiRoute } from './api.js';
+
+/**
+ * 请求上下文接口
+ */
+export interface RequestContext {
+    /** 请求体参数 */
+    body: Record<string, any>;
+    /** 用户信息 */
+    user: Record<string, any>;
+    /** 原始请求对象 */
+    req: Request;
+    /** 请求开始时间（毫秒） */
+    now: number;
+    /** 客户端 IP 地址 */
+    ip?: string;
+    /** API 路由路径（如 POST/api/user/login） */
+    route?: string;
+    /** 当前请求的 API 路由对象 */
+    api?: ApiRoute;
+    /** 响应对象（如果设置了此属性，将直接返回该响应） */
+    response?: Response;
+    /** 原始处理结果（未转换为 Response 对象前） */
+    result?: any;
+    /** 请求唯一 ID */
+    requestId?: string;
+    /** CORS 响应头 */
+    corsHeaders?: Record<string, string>;
+}

package/types/hook.d.ts

@@ -0,0 +1,35 @@
+/**
+ * Befly 钩子系统类型定义
+ */
+
+import type { BeflyContext } from './befly.js';
+import type { RequestContext } from './context.js';
+
+/**
+ * 钩子处理函数类型
+ */
+export type Next = () => Promise<void>;
+export type HookHandler = (befly: BeflyContext, ctx: RequestContext, next: Next) => Promise<void> | void;
+
+/**
+ * 钩子配置类型
+ */
+export interface Hook {
+    /** 钩子名称（运行时动态添加，由文件名生成） */
+    name?: string;
+
+    /** 依赖的钩子列表（在这些钩子之后执行） */
+    after?: string[];
+
+    /** 执行顺序（数字越小越先执行，同级别时使用） */
+    order?: number;
+
+    /** 钩子处理函数 */
+    handler: HookHandler;
+
+    /** 钩子配置 */
+    config?: Record<string, any>;
+
+    /** 钩子描述 */
+    description?: string;
+}

package/types/index.ts

@@ -2,4 +2,17 @@
  * 类型定义导出
  */
 
-export * from './env.js';
+export * from './addon.js';
+export * from './api.js';
+export * from './befly.js';
+export * from './common.js';
+export * from './context.js';
+export * from './crypto.js';
+export * from './database.js';
+export * from './jwt.js';
+export * from './logger.js';
+export * from './plugin.js';
+export * from './redis.js';
+export * from './tool.js';
+export * from './validator.js';
+export * from './sync.js';

package/types/plugin.d.ts

@@ -13,16 +13,15 @@ export type PluginInitFunction = (befly: BeflyContext) => Promise<any> | any;
 /**
  * 插件请求处理钩子函数类型
  */
-export type PluginGetHook = (befly: BeflyContext, ctx: RequestContext, req: Request) => Promise<void> | void;
+export type Next = () => Promise<void>;
 
 /**
  * 插件配置类型
  */
 export interface Plugin {
-    /** 插件名称 */
-    name: string;
-
-    /** 插件名称（运行时动态添加，与 name 相同） */
+    /** 插件名称（运行时动态添加，由文件名生成） */
+    name?: string;
+    /** @deprecated use name instead */
     pluginName?: string;
 
     /** 依赖的插件列表（在这些插件之后执行） */
@@ -31,8 +30,8 @@ export interface Plugin {
     /** 插件初始化函数 */
     onInit?: PluginInitFunction;
 
-    /** 请求处理钩子（在每个 API 请求时执行） */
-    onGet?: PluginGetHook;
+    /** 插件配置 */
+    config?: Record<string, any>;
 
     /** 插件描述 */
     description?: string;