@dangao/bun-server 1.7.1 → 1.8.0

package/docs/zh/validation.md

@@ -0,0 +1,407 @@
+# 验证系统
+
+Bun Server Framework 提供了强大的验证系统，用于验证请求参数、DTO 和复杂数据结构。
+
+## 目录
+
+- [基础验证](#基础验证)
+- [验证规则](#验证规则)
+  - [对象规则](#对象规则)
+  - [数组规则](#数组规则)
+  - [通用规则](#通用规则)
+  - [条件规则](#条件规则)
+- [类级别验证](#类级别验证)
+- [嵌套对象验证](#嵌套对象验证)
+- [自定义验证器](#自定义验证器)
+- [内置扩展验证器](#内置扩展验证器)
+- [错误处理](#错误处理)
+
+## 基础验证
+
+在控制器方法参数上使用 `@Validate()` 装饰器：
+
+```typescript
+import { Controller, GET, Query, Validate, IsString, IsEmail, IsOptional, MinLength } from '@dangao/bun-server';
+
+@Controller('/api/users')
+class UserController {
+  @GET('/search')
+  public search(
+    @Query('email') @Validate(IsEmail()) email: string,
+    @Query('name') @Validate(IsOptional(), IsString(), MinLength(2)) name?: string,
+  ) {
+    return { email, name };
+  }
+}
+```
+
+## 验证规则
+
+### 对象规则
+
+```typescript
+import { IsObject, IsNotEmpty, IsNotEmptyObject, ValidateNested } from '@dangao/bun-server';
+
+// 验证值是否为对象
+IsObject()
+
+// 验证值是否非空（null、undefined、空字符串、空数组、空对象）
+IsNotEmpty()
+
+// 验证值是否为非空对象
+IsNotEmptyObject()
+
+// 标记属性需要嵌套验证
+ValidateNested({ each?: boolean })  // each: true 用于数组元素
+```
+
+### 数组规则
+
+```typescript
+import { 
+  IsArray, ArrayMinSize, ArrayMaxSize, ArrayUnique, 
+  ArrayContains, ArrayNotContains, ArrayNotEmpty 
+} from '@dangao/bun-server';
+
+// 验证值是否为数组
+IsArray()
+
+// 验证数组最小长度
+ArrayMinSize(2)
+
+// 验证数组最大长度
+ArrayMaxSize(10)
+
+// 验证数组元素是否唯一
+ArrayUnique()
+
+// 验证数组是否包含指定值
+ArrayContains([1, 2])
+
+// 验证数组是否不包含指定值
+ArrayNotContains(['banned'])
+
+// 验证数组是否非空
+ArrayNotEmpty()
+```
+
+### 通用规则
+
+```typescript
+import {
+  IsString, IsNumber, IsBoolean, IsInt, IsPositive, IsNegative,
+  Min, Max, IsDate, IsUUID, Length, MaxLength, MinLength,
+  Matches, IsIn, IsNotIn, IsUrl, IsJSON, IsEmail,
+  Equals, NotEquals, IsDefined, IsAlphanumeric, IsAlpha, IsNumberString
+} from '@dangao/bun-server';
+
+// 类型验证
+IsString()
+IsNumber()
+IsBoolean()
+IsInt()
+IsDate()
+
+// 数字验证
+IsPositive()
+IsNegative()
+Min(0)
+Max(100)
+
+// 字符串验证
+IsEmail()
+IsUUID('4')  // '3', '4', '5', 或 'all'
+Length(2, 10)
+MinLength(2)
+MaxLength(10)
+Matches(/^[a-z]+$/)
+IsUrl()
+IsJSON()
+IsAlphanumeric()
+IsAlpha()
+IsNumberString()
+
+// 值验证
+IsIn(['a', 'b', 'c'])
+IsNotIn(['x', 'y', 'z'])
+Equals('expected')
+NotEquals('forbidden')
+IsDefined()
+```
+
+### 条件规则
+
+```typescript
+import { ValidateIf, Transform } from '@dangao/bun-server';
+
+// 条件验证 - 仅当条件为 true 时执行验证
+ValidateIf((value, obj) => obj.type === 'premium')
+
+// 验证前转换值
+Transform((value) => String(value).trim())
+Transform((value) => Number(value))
+```
+
+使用示例：
+
+```typescript
+@ValidateClass()
+class UpdateUserDto {
+  @Property(ValidateIf((_, obj) => obj.type === 'premium'), IsEmail())
+  premiumEmail?: string;
+
+  @Property(Transform((v) => String(v).trim()), IsString(), MinLength(1))
+  name: string;
+
+  @Property(Transform((v) => Number(v)), IsInt(), Min(0))
+  age: number;
+}
+```
+
+## 类级别验证
+
+对于 DTO 类，使用 `@ValidateClass()` 和 `@Property()` 装饰器：
+
+```typescript
+import { ValidateClass, Property, IsString, IsEmail, IsOptional, IsInt, Min, Max, MinLength } from '@dangao/bun-server';
+
+@ValidateClass()
+class CreateUserDto {
+  @Property(IsString(), MinLength(2))
+  name: string;
+
+  @Property(IsEmail())
+  email: string;
+
+  @Property(IsOptional(), IsInt(), Min(0), Max(150))
+  age?: number;
+}
+```
+
+手动验证对象：
+
+```typescript
+import { validateObject, validateObjectSync, ValidationError } from '@dangao/bun-server';
+
+// 失败时抛出 ValidationError
+try {
+  validateObject(data, CreateUserDto);
+} catch (error) {
+  if (error instanceof ValidationError) {
+    console.log(error.issues);
+  }
+}
+
+// 返回验证结果而不抛出异常
+const result = validateObjectSync(data, CreateUserDto);
+if (!result.valid) {
+  console.log(result.issues);
+}
+```
+
+## 嵌套对象验证
+
+用于嵌套对象和数组：
+
+```typescript
+import { ValidateClass, Property, NestedProperty, ArrayNestedProperty, IsString, IsNumber, Min, IsArray, ArrayMinSize } from '@dangao/bun-server';
+
+@ValidateClass()
+class AddressDto {
+  @Property(IsString())
+  city: string;
+
+  @Property(IsString())
+  street: string;
+}
+
+@ValidateClass()
+class ItemDto {
+  @Property(IsString())
+  name: string;
+
+  @Property(IsNumber(), Min(0))
+  price: number;
+}
+
+@ValidateClass()
+class CreateOrderDto {
+  @Property(IsString())
+  userId: string;
+
+  // 嵌套对象验证
+  @NestedProperty(AddressDto)
+  shippingAddress: AddressDto;
+
+  // 嵌套对象数组验证
+  @Property(IsArray(), ArrayMinSize(1))
+  @ArrayNestedProperty(ItemDto)
+  items: ItemDto[];
+}
+```
+
+## 自定义验证器
+
+### 简单自定义验证器
+
+```typescript
+import { createSimpleValidator } from '@dangao/bun-server';
+
+const IsEven = createSimpleValidator(
+  'isEven',
+  (value) => typeof value === 'number' && value % 2 === 0,
+  '必须是偶数'
+);
+
+// 使用
+@Property(IsEven())
+count: number;
+```
+
+### 带参数的自定义验证器
+
+```typescript
+import { createCustomValidator } from '@dangao/bun-server';
+
+const IsDivisibleBy = createCustomValidator(
+  'isDivisibleBy',
+  (value: unknown, divisor: number) => typeof value === 'number' && value % divisor === 0,
+  (divisor: number) => `必须能被 ${divisor} 整除`
+);
+
+// 使用
+@Property(IsDivisibleBy(5)())
+value: number;
+```
+
+### 正则表达式自定义验证器
+
+```typescript
+import { createRegexValidator } from '@dangao/bun-server';
+
+const IsSlug = createRegexValidator(
+  'isSlug',
+  /^[a-z0-9]+(?:-[a-z0-9]+)*$/,
+  '必须是有效的 slug 格式'
+);
+
+// 使用
+@Property(IsSlug())
+slug: string;
+```
+
+## 内置扩展验证器
+
+框架提供了多个预置验证器用于常见场景：
+
+```typescript
+import {
+  IsPhoneNumber,    // 中国手机号
+  IsIdCard,         // 中国身份证号
+  IsIPv4,           // IPv4 地址
+  IsPort,           // 端口号 (0-65535)
+  IsPostalCode,     // 中国邮政编码
+  IsCreditCard,     // 信用卡号（Luhn 算法）
+  IsHexColor,       // 十六进制颜色值（#fff 或 #ffffff）
+  IsMacAddress,     // MAC 地址
+  IsSemVer,         // 语义化版本号
+  IsDivisibleBy,    // 能被指定数字整除
+  IsBetween,        // 数字在范围内
+  Contains,         // 字符串包含子串
+  NotContains,      // 字符串不包含子串
+} from '@dangao/bun-server';
+
+// 使用示例
+@Property(IsPhoneNumber())
+phone: string;
+
+@Property(IsIPv4())
+ip: string;
+
+@Property(IsBetween(1, 100)())
+percentage: number;
+
+@Property(Contains('http')())
+url: string;
+```
+
+## 错误处理
+
+### ValidationError
+
+验证失败时会抛出 `ValidationError`：
+
+```typescript
+import { ValidationError, ValidationIssue } from '@dangao/bun-server';
+
+try {
+  validateObject(data, MyDto);
+} catch (error) {
+  if (error instanceof ValidationError) {
+    // 访问验证问题列表
+    console.log(error.issues);
+    
+    // 获取扁平化的错误（对嵌套对象有用）
+    console.log(error.getFlattened());
+    
+    // 转换为 JSON
+    console.log(error.toJSON());
+  }
+}
+```
+
+### ValidationIssue 结构
+
+```typescript
+interface ValidationIssue {
+  index?: number;       // 参数索引（用于参数验证）
+  property?: string;    // 属性路径（如 'user.address.city'）
+  rule: string;         // 失败的规则名称
+  message: string;      // 错误消息
+  value?: unknown;      // 验证失败的值
+  children?: ValidationIssue[];  // 嵌套错误
+}
+```
+
+### 控制器集成
+
+验证错误会被自动捕获并返回 400 Bad Request 响应：
+
+```typescript
+@Controller('/api/users')
+class UserController {
+  @POST('/')
+  public async createUser(@Body() @Validate(IsObject()) body: unknown) {
+    const dto = body as CreateUserDto;
+    validateObject(dto, CreateUserDto);
+    // ... 创建用户
+  }
+}
+```
+
+## 最佳实践
+
+1. **复杂验证使用 DTO**：对于具有多个字段的请求体，使用 `@ValidateClass()` 装饰的 DTO。
+
+2. **组合规则**：链式组合多个规则以进行全面验证：
+   ```typescript
+   @Property(IsString(), MinLength(2), MaxLength(50), Matches(/^[a-zA-Z\s]+$/))
+   name: string;
+   ```
+
+3. **IsOptional() 放在最前**：始终将 `IsOptional()` 放在规则链的开头：
+   ```typescript
+   @Property(IsOptional(), IsString(), MinLength(2))
+   nickname?: string;
+   ```
+
+4. **先转换后验证**：使用 `Transform()` 在验证前规范化数据：
+   ```typescript
+   @Property(Transform((v) => String(v).toLowerCase().trim()), IsEmail())
+   email: string;
+   ```
+
+5. **自定义错误消息**：提供清晰、用户友好的错误消息：
+   ```typescript
+   IsEmail({ message: '请输入有效的邮箱地址' })
+   ```

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dangao/bun-server",
-  "version": "1.7.1",
+  "version": "1.8.0",
   "type": "module",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",

package/src/di/decorators.ts

@@ -9,6 +9,11 @@ import type { Constructor } from "@/core/types";
 const DEPENDENCY_METADATA_KEY = Symbol("dependency:metadata");
 const INJECTABLE_METADATA_KEY = Symbol("injectable");
 
+/**
+ * 全局模块元数据键
+ */
+export const GLOBAL_MODULE_METADATA_KEY = Symbol("@dangao/bun-server:global-module");
+
 /**
  * 类型引用映射（用于保存构造函数类型，避免 Reflect.defineMetadata 序列化问题）
  */
@@ -226,3 +231,44 @@ export function getTypeReference(
   }
   return undefined as unknown as Constructor<unknown>;
 }
+
+/**
+ * Global 装饰器
+ * 标记模块为全局模块，其导出的提供者可在任何模块中使用，无需显式导入
+ *
+ * @example
+ * ```typescript
+ * @Global()
+ * @Module({
+ *   providers: [ConfigService],
+ *   exports: [ConfigService],
+ * })
+ * class GlobalConfigModule {}
+ *
+ * // 其他模块无需导入 GlobalConfigModule 即可使用 ConfigService
+ * @Module({
+ *   controllers: [UserController],
+ *   providers: [UserService],
+ * })
+ * class UserModule {}
+ *
+ * @Injectable()
+ * class UserService {
+ *   constructor(private readonly config: ConfigService) {}
+ * }
+ * ```
+ */
+export function Global(): ClassDecorator {
+  return (target) => {
+    Reflect.defineMetadata(GLOBAL_MODULE_METADATA_KEY, true, target);
+  };
+}
+
+/**
+ * 检查模块是否为全局模块
+ * @param target - 目标模块类
+ * @returns 是否为全局模块
+ */
+export function isGlobalModule(target: Constructor<unknown>): boolean {
+  return Reflect.getMetadata(GLOBAL_MODULE_METADATA_KEY, target) === true;
+}

package/src/di/index.ts

@@ -1,5 +1,14 @@
 export { Container } from './container';
-export { Injectable, Inject, getDependencyMetadata, isInjectable, getLifecycle } from './decorators';
+export {
+  Injectable,
+  Inject,
+  getDependencyMetadata,
+  isInjectable,
+  getLifecycle,
+  Global,
+  isGlobalModule,
+  GLOBAL_MODULE_METADATA_KEY,
+} from './decorators';
 export {
   Lifecycle,
   INSTANCE_POST_PROCESSOR_TOKEN,

package/src/di/module-registry.ts

@@ -2,6 +2,7 @@ import { ControllerRegistry } from '../controller/controller';
 import { Container } from './container';
 import { Lifecycle } from './types';
 import { getModuleMetadata, type ModuleClass, type ModuleProvider, type ProviderToken } from './module';
+import { isGlobalModule } from './decorators';
 import type { Constructor } from '@/core/types';
 import type { ApplicationExtension } from '../extensions/types';
 import type { Middleware } from '../middleware';
@@ -14,6 +15,10 @@ interface ModuleRef {
   attachedParents: Set<Container>;
   extensions: ApplicationExtension[];
   middlewares: Middleware[];
+  /**
+   * 是否为全局模块
+   */
+  isGlobal: boolean;
 }
 
 export class ModuleRegistry {
@@ -21,6 +26,10 @@ export class ModuleRegistry {
   private readonly moduleRefs = new Map<ModuleClass, ModuleRef>();
   private readonly processing = new Set<ModuleClass>();
   private rootContainer?: Container;
+  /**
+   * 存储全局模块列表，用于在其他模块注册时自动附加全局 exports
+   */
+  private readonly globalModules = new Set<ModuleClass>();
 
   public static getInstance(): ModuleRegistry {
     if (!ModuleRegistry.instance) {
@@ -43,9 +52,17 @@ export class ModuleRegistry {
   public clear(): void {
     this.moduleRefs.clear();
     this.processing.clear();
+    this.globalModules.clear();
     this.rootContainer = undefined;
   }
 
+  /**
+   * 获取所有全局模块
+   */
+  public getGlobalModules(): ModuleClass[] {
+    return Array.from(this.globalModules);
+  }
+
   private processModule(moduleClass: ModuleClass, parentContainer: Container): ModuleRef {
     if (this.processing.has(moduleClass)) {
       throw new Error(`Circular module dependency detected for ${moduleClass.name}`);
@@ -69,6 +86,7 @@ export class ModuleRegistry {
       throw new Error('ModuleRegistry is not initialized with a root container');
     }
     const metadata = getModuleMetadata(moduleClass);
+    const isGlobal = isGlobalModule(moduleClass);
     const container = new Container({ parent: this.rootContainer });
     this.registerProviders(container, metadata.providers);
     ref = {
@@ -79,12 +97,33 @@ export class ModuleRegistry {
       attachedParents: new Set<Container>(),
       extensions: metadata.extensions ?? [],
       middlewares: metadata.middlewares ?? [],
+      isGlobal,
     };
     this.registerControllers(ref);
     this.moduleRefs.set(moduleClass, ref);
+
+    // 如果是全局模块，注册到根容器并记录
+    if (isGlobal) {
+      this.globalModules.add(moduleClass);
+      this.registerGlobalExports(ref);
+    }
+
     return ref;
   }
 
+  /**
+   * 将全局模块的 exports 注册到根容器
+   * 这样所有模块都可以访问全局模块导出的提供者
+   */
+  private registerGlobalExports(moduleRef: ModuleRef): void {
+    if (!this.rootContainer) {
+      return;
+    }
+    for (const exportedToken of moduleRef.metadata.exports) {
+      this.registerExport(this.rootContainer, moduleRef, exportedToken);
+    }
+  }
+
   private registerProviders(container: Container, providers: ModuleProvider[]): void {
     for (const provider of providers) {
       if (typeof provider === 'function') {

package/src/events/decorators.ts

@@ -0,0 +1,103 @@
+import 'reflect-metadata';
+import {
+  ON_EVENT_METADATA_KEY,
+  EVENT_LISTENER_CLASS_METADATA_KEY,
+  type OnEventMethodMetadata,
+} from './types';
+
+/**
+ * OnEvent 装饰器选项
+ */
+export interface OnEventOptions {
+  /**
+   * 是否异步处理
+   * @default false
+   */
+  async?: boolean;
+
+  /**
+   * 监听器优先级（数值越大优先级越高）
+   * @default 0
+   */
+  priority?: number;
+}
+
+/**
+ * 事件监听器装饰器
+ * 用于标记方法为事件监听器
+ *
+ * @param event - 事件名称或标识符
+ * @param options - 监听选项
+ *
+ * @example
+ * ```typescript
+ * @Injectable()
+ * class NotificationService {
+ *   @OnEvent('user.created')
+ *   handleUserCreated(payload: UserCreatedEvent) {
+ *     console.log('User created:', payload.userId);
+ *   }
+ *
+ *   @OnEvent(USER_DELETED, { async: true, priority: 10 })
+ *   async handleUserDeleted(payload: UserDeletedEvent) {
+ *     await this.cleanup(payload.userId);
+ *   }
+ * }
+ * ```
+ */
+export function OnEvent(
+  event: string | symbol,
+  options: OnEventOptions = {},
+): MethodDecorator {
+  return (
+    target: object,
+    propertyKey: string | symbol,
+    descriptor: PropertyDescriptor,
+  ): PropertyDescriptor => {
+    const methodName = String(propertyKey);
+    const constructor = target.constructor;
+
+    // 获取类上已有的事件监听器元数据
+    const existingMetadata: OnEventMethodMetadata[] =
+      Reflect.getMetadata(ON_EVENT_METADATA_KEY, constructor) || [];
+
+    // 添加新的监听器元数据
+    const metadata: OnEventMethodMetadata = {
+      methodName,
+      event,
+      async: options.async ?? false,
+      priority: options.priority ?? 0,
+    };
+
+    Reflect.defineMetadata(
+      ON_EVENT_METADATA_KEY,
+      [...existingMetadata, metadata],
+      constructor,
+    );
+
+    // 标记类为事件监听器类
+    Reflect.defineMetadata(EVENT_LISTENER_CLASS_METADATA_KEY, true, constructor);
+
+    return descriptor;
+  };
+}
+
+/**
+ * 获取类的事件监听器元数据
+ * @param target - 目标类
+ */
+export function getOnEventMetadata(
+  target: Function,
+): OnEventMethodMetadata[] | undefined {
+  return Reflect.getMetadata(ON_EVENT_METADATA_KEY, target);
+}
+
+/**
+ * 检查类是否为事件监听器类
+ * @param target - 目标类
+ */
+export function isEventListenerClass(target: Function): boolean {
+  return (
+    Reflect.getMetadata(EVENT_LISTENER_CLASS_METADATA_KEY, target) === true
+  );
+}