@dangao/bun-server 1.7.1 → 1.8.0

package/docs/zh/guards.md

@@ -0,0 +1,376 @@
+# 守卫（Guards）
+
+守卫是控制应用程序路由访问的强大机制。它们在路由处理器之前执行，决定请求是否应该被处理。
+
+## 概述
+
+守卫实现 `CanActivate` 接口，返回一个布尔值来指示请求是否应该被允许继续。与中间件不同，守卫可以访问 `ExecutionContext`，它提供了当前请求上下文的丰富信息。
+
+### 何时使用守卫
+
+- **认证**：验证用户是否已认证
+- **授权**：检查用户是否具有所需的角色或权限
+- **限流**：实现自定义限流逻辑
+- **功能开关**：根据条件启用/禁用功能
+- **请求验证**：在处理前验证请求元数据
+
+## 基本用法
+
+### 创建守卫
+
+```typescript
+import { Injectable } from '@dangao/bun-server';
+import type { CanActivate, ExecutionContext } from '@dangao/bun-server';
+
+@Injectable()
+class AuthGuard implements CanActivate {
+  canActivate(context: ExecutionContext): boolean | Promise<boolean> {
+    const request = context.switchToHttp().getRequest();
+    const token = request.getHeader('authorization');
+    
+    // 验证 token 并返回 true/false
+    return !!token;
+  }
+}
+```
+
+### 应用守卫
+
+守卫可以在不同级别应用：
+
+#### 控制器级别
+
+```typescript
+import { Controller, GET, UseGuards } from '@dangao/bun-server';
+
+@Controller('/api/users')
+@UseGuards(AuthGuard)
+class UserController {
+  @GET('/')
+  getUsers() {
+    return { users: [] };
+  }
+}
+```
+
+#### 方法级别
+
+```typescript
+@Controller('/api')
+class ApiController {
+  @GET('/public')
+  publicEndpoint() {
+    return { message: '公开' };
+  }
+
+  @GET('/private')
+  @UseGuards(AuthGuard)
+  privateEndpoint() {
+    return { message: '私有' };
+  }
+}
+```
+
+#### 全局守卫
+
+```typescript
+import { SecurityModule } from '@dangao/bun-server';
+
+SecurityModule.forRoot({
+  jwt: { secret: 'your-secret' },
+  globalGuards: [AuthGuard, RolesGuard],
+});
+```
+
+## 执行顺序
+
+守卫按以下顺序执行：
+
+1. **全局守卫**（按注册顺序）
+2. **控制器守卫**（按装饰器顺序）
+3. **方法守卫**（按装饰器顺序）
+
+```
+HTTP 请求
+    ↓
+中间件管道
+    ↓
+安全过滤器（Token 提取和认证）
+    ↓
+守卫（全局 → 控制器 → 方法）
+    ↓
+拦截器（前置）
+    ↓
+路由处理器
+    ↓
+拦截器（后置）
+    ↓
+HTTP 响应
+```
+
+## 内置守卫
+
+### AuthGuard
+
+检查用户是否已认证：
+
+```typescript
+import { Controller, GET, UseGuards, AuthGuard } from '@dangao/bun-server';
+
+@Controller('/api/profile')
+@UseGuards(AuthGuard)
+class ProfileController {
+  @GET('/')
+  getProfile() {
+    // 只有已认证的用户可以访问
+    return { profile: {} };
+  }
+}
+```
+
+### OptionalAuthGuard
+
+允许未认证访问，但如果有 token 会进行验证：
+
+```typescript
+import { Controller, GET, UseGuards, OptionalAuthGuard } from '@dangao/bun-server';
+
+@Controller('/api/posts')
+class PostController {
+  @GET('/')
+  @UseGuards(OptionalAuthGuard)
+  getPosts() {
+    // 无论是否认证都允许访问
+    return { posts: [] };
+  }
+}
+```
+
+### RolesGuard
+
+检查用户是否具有所需角色：
+
+```typescript
+import { Controller, GET, UseGuards, AuthGuard, RolesGuard, Roles } from '@dangao/bun-server';
+
+@Controller('/api/admin')
+@UseGuards(AuthGuard, RolesGuard)
+class AdminController {
+  @GET('/dashboard')
+  @Roles('admin')
+  dashboard() {
+    return { message: '管理员仪表板' };
+  }
+
+  @GET('/super')
+  @Roles('admin', 'superadmin')  // 任一角色即可访问
+  superAdmin() {
+    return { message: '超级管理员' };
+  }
+}
+```
+
+## 自定义守卫
+
+### 基本自定义守卫
+
+```typescript
+import { Injectable } from '@dangao/bun-server';
+import type { CanActivate, ExecutionContext } from '@dangao/bun-server';
+
+@Injectable()
+class ApiKeyGuard implements CanActivate {
+  private readonly validApiKeys = ['key1', 'key2'];
+
+  canActivate(context: ExecutionContext): boolean {
+    const request = context.switchToHttp().getRequest();
+    const apiKey = request.getHeader('x-api-key');
+    
+    return this.validApiKeys.includes(apiKey || '');
+  }
+}
+```
+
+### 异步守卫
+
+```typescript
+@Injectable()
+class SubscriptionGuard implements CanActivate {
+  constructor(private readonly subscriptionService: SubscriptionService) {}
+
+  async canActivate(context: ExecutionContext): Promise<boolean> {
+    const request = context.switchToHttp().getRequest();
+    const userId = request.auth?.user?.id;
+    
+    if (!userId) return false;
+    
+    const subscription = await this.subscriptionService.getSubscription(userId);
+    return subscription?.isActive ?? false;
+  }
+}
+```
+
+### 访问元数据的守卫
+
+```typescript
+@Injectable()
+class FeatureFlagGuard implements CanActivate {
+  constructor(private readonly reflector: Reflector) {}
+
+  canActivate(context: ExecutionContext): boolean {
+    const feature = this.reflector.getAllAndOverride<string>(
+      'feature',
+      context.getClass(),
+      context.getMethodName(),
+    );
+    
+    if (!feature) return true;
+    
+    return this.isFeatureEnabled(feature);
+  }
+
+  private isFeatureEnabled(feature: string): boolean {
+    // 检查功能开关状态
+    return true;
+  }
+}
+```
+
+## ExecutionContext
+
+`ExecutionContext` 提供以下访问能力：
+
+### HTTP 上下文
+
+```typescript
+const httpHost = context.switchToHttp();
+const request = httpHost.getRequest();  // Context 对象
+const response = httpHost.getResponse(); // ResponseBuilder（如果可用）
+```
+
+### 控制器和方法信息
+
+```typescript
+const controllerClass = context.getClass();    // 控制器类
+const handler = context.getHandler();          // 方法函数
+const methodName = context.getMethodName();    // 方法名字符串
+```
+
+### 元数据访问
+
+```typescript
+const metadata = context.getMetadata<string[]>('roles');
+// 先检查方法，再检查类
+```
+
+## Reflector 工具类
+
+`Reflector` 类帮助检索元数据：
+
+```typescript
+import { Reflector, REFLECTOR_TOKEN } from '@dangao/bun-server';
+
+@Injectable()
+class MyGuard implements CanActivate {
+  constructor(@Inject(REFLECTOR_TOKEN) private readonly reflector: Reflector) {}
+
+  canActivate(context: ExecutionContext): boolean {
+    // 获取元数据，方法优先
+    const roles = this.reflector.getAllAndOverride<string[]>(
+      ROLES_METADATA_KEY,
+      context.getClass(),
+      context.getMethodName(),
+    );
+    
+    // 合并类和方法的元数据
+    const permissions = this.reflector.getAllAndMerge<string[]>(
+      'permissions',
+      context.getClass(),
+      context.getMethodName(),
+    );
+    
+    return true;
+  }
+}
+```
+
+## 自定义角色守卫工厂
+
+创建自定义的角色守卫：
+
+```typescript
+import { createRolesGuard } from '@dangao/bun-server';
+
+// 要求所有角色而不是任一角色
+const AllRolesGuard = createRolesGuard({ matchAll: true });
+
+// 自定义角色提取
+const CustomRolesGuard = createRolesGuard({
+  getRoles: (context) => {
+    const request = context.switchToHttp().getRequest();
+    return request.auth?.user?.permissions || [];
+  },
+});
+```
+
+## 错误处理
+
+守卫可以抛出异常来拒绝请求：
+
+```typescript
+import { ForbiddenException, UnauthorizedException } from '@dangao/bun-server';
+
+@Injectable()
+class StrictAuthGuard implements CanActivate {
+  canActivate(context: ExecutionContext): boolean {
+    const request = context.switchToHttp().getRequest();
+    
+    if (!request.auth?.isAuthenticated) {
+      throw new UnauthorizedException('需要认证');
+    }
+    
+    if (!this.hasPermission(request.auth.user)) {
+      throw new ForbiddenException('权限不足');
+    }
+    
+    return true;
+  }
+}
+```
+
+## 最佳实践
+
+1. **保持守卫专注**：每个守卫应该只处理一个关注点
+2. **使用依赖注入**：对于复杂逻辑，注入服务
+3. **优先抛出异常**：比返回 false 提供更好的错误消息
+4. **顺序很重要**：在 RolesGuard 之前应用 AuthGuard
+5. **使用内置守卫**：尽可能使用 AuthGuard 和 RolesGuard
+6. **测试你的守卫**：为守卫逻辑编写单元测试
+
+## 与 SecurityModule 集成
+
+守卫与 SecurityModule 无缝配合：
+
+```typescript
+import { Application, SecurityModule, AuthGuard, RolesGuard } from '@dangao/bun-server';
+
+const app = new Application();
+
+app.registerModule(
+  SecurityModule.forRoot({
+    jwt: {
+      secret: 'your-jwt-secret',
+      accessTokenExpiresIn: 3600,
+    },
+    excludePaths: ['/public', '/health'],
+    globalGuards: [AuthGuard],  // 应用于所有路由
+  }),
+);
+```
+
+## 参见
+
+- [请求生命周期](./request-lifecycle.md)
+- [安全模块](./guide.md#security-module)
+- [自定义装饰器](./custom-decorators.md)
+

package/docs/zh/guide.md

@@ -2,6 +2,16 @@
 
 涵盖从零开始构建 Bun Server 应用的关键步骤。
 
+## 请求生命周期概览
+
+在深入实现细节之前，了解 Bun Server 如何处理请求会很有帮助：
+
+```
+HTTP 请求 → 中间件 → 安全 → 路由 → 拦截器(前置) → 验证 → 处理器 → 拦截器(后置) → 异常过滤器 → HTTP 响应
+```
+
+详细的生命周期文档请参阅 [请求生命周期](./request-lifecycle.md)。
+
 ## 1. 初始化应用
 
 ```ts
@@ -357,7 +367,305 @@ app.listen();
 
 这种模式特别适合大型项目，可以轻松替换实现而不影响使用方代码。
 
-## 9. 测试建议
+## 9. 守卫（Guards）
+
+守卫提供对路由的细粒度访问控制。它们在中间件之后、拦截器之前执行，决定请求是否应该继续。
+
+### 内置守卫
+
+```ts
+import {
+  AuthGuard,
+  Controller,
+  GET,
+  Roles,
+  RolesGuard,
+  UseGuards,
+} from "@dangao/bun-server";
+
+@Controller("/api/admin")
+@UseGuards(AuthGuard, RolesGuard)
+class AdminController {
+  @GET("/dashboard")
+  @Roles("admin")
+  public dashboard() {
+    return { message: "管理员仪表板" };
+  }
+
+  @GET("/users")
+  @Roles("admin", "moderator") // 任一角色即可访问
+  public listUsers() {
+    return { users: [] };
+  }
+}
+```
+
+### 自定义守卫
+
+```ts
+import { Injectable } from "@dangao/bun-server";
+import type { CanActivate, ExecutionContext } from "@dangao/bun-server";
+
+@Injectable()
+class ApiKeyGuard implements CanActivate {
+  canActivate(context: ExecutionContext): boolean {
+    const request = context.switchToHttp().getRequest();
+    const apiKey = request.getHeader("x-api-key");
+    return apiKey === "valid-api-key";
+  }
+}
+
+@Controller("/api/external")
+@UseGuards(ApiKeyGuard)
+class ExternalApiController {
+  @GET("/data")
+  public getData() {
+    return { data: [] };
+  }
+}
+```
+
+### 全局守卫
+
+```ts
+SecurityModule.forRoot({
+  jwt: { secret: "your-secret" },
+  globalGuards: [AuthGuard], // 应用于所有路由
+});
+```
+
+详细文档请参阅 [守卫](./guards.md)。
+
+## 10. 事件系统
+
+事件模块提供了强大的事件驱动架构，用于构建松耦合的应用。
+
+### 基本用法
+
+```ts
+import {
+  EventModule,
+  Injectable,
+  Inject,
+  OnEvent,
+  EVENT_EMITTER_TOKEN,
+} from "@dangao/bun-server";
+import type { EventEmitter } from "@dangao/bun-server";
+
+// 定义事件
+const USER_CREATED = Symbol("user.created");
+
+interface UserCreatedEvent {
+  userId: string;
+  email: string;
+}
+
+// 发布事件的服务
+@Injectable()
+class UserService {
+  public constructor(
+    @Inject(EVENT_EMITTER_TOKEN) private readonly eventEmitter: EventEmitter,
+  ) {}
+
+  public async createUser(email: string) {
+    const userId = "user-123";
+
+    // 发布事件
+    this.eventEmitter.emit<UserCreatedEvent>(USER_CREATED, {
+      userId,
+      email,
+    });
+
+    return { userId, email };
+  }
+}
+
+// 监听事件的服务
+@Injectable()
+class NotificationService {
+  @OnEvent(USER_CREATED)
+  public handleUserCreated(payload: UserCreatedEvent) {
+    console.log(`欢迎邮件已发送至 ${payload.email}`);
+  }
+
+  @OnEvent(USER_CREATED, { async: true, priority: 10 })
+  public async trackUserCreation(payload: UserCreatedEvent) {
+    await this.analytics.track("user_created", payload);
+  }
+}
+```
+
+### 模块配置
+
+```ts
+EventModule.forRoot({
+  wildcard: true, // 启用通配符匹配
+  maxListeners: 20, // 每个事件的最大监听器数量
+  onError: (error, event, payload) => {
+    console.error(`事件 ${String(event)} 发生错误:`, error);
+  },
+});
+
+// 注册监听器类
+EventModule.registerListeners([NotificationService, AnalyticsService]);
+
+@Module({
+  imports: [EventModule],
+  providers: [UserService, NotificationService, AnalyticsService],
+})
+class AppModule {}
+
+const app = new Application();
+app.registerModule(AppModule);
+
+// 模块注册后初始化事件监听器
+EventModule.initializeListeners(app.getContainer());
+```
+
+### 通配符事件
+
+```ts
+// 匹配任何用户事件: user.created, user.updated, user.deleted
+@OnEvent("user.*")
+handleAnyUserEvent(payload: unknown) {}
+
+// 匹配嵌套事件: order.created, order.item.added, order.payment.completed
+@OnEvent("order.**")
+handleAllOrderEvents(payload: unknown) {}
+```
+
+### 异步事件发布
+
+```ts
+// 触发即忘（异步监听器被触发但不等待）
+this.eventEmitter.emit("order.created", orderData);
+
+// 等待所有监听器完成
+await this.eventEmitter.emitAsync("order.created", orderData);
+```
+
+详细文档请参阅 [事件系统](./events.md)。
+
+## 11. 全局模块
+
+全局模块允许您在所有模块之间共享提供者，无需显式导入。这对于常用的服务（如配置、日志或缓存）非常有用。
+
+### 创建全局模块
+
+使用 `@Global()` 装饰器将模块标记为全局模块：
+
+```ts
+import { Global, Injectable, Module } from "@dangao/bun-server";
+
+const CONFIG_TOKEN = Symbol("config");
+
+@Injectable()
+class ConfigService {
+  public get(key: string): string {
+    return `config:${key}`;
+  }
+}
+
+@Global()
+@Module({
+  providers: [
+    {
+      provide: CONFIG_TOKEN,
+      useClass: ConfigService,
+    },
+  ],
+  exports: [CONFIG_TOKEN],
+})
+class GlobalConfigModule {}
+```
+
+### 使用全局模块导出
+
+其他模块可以使用导出的提供者，无需导入全局模块：
+
+```ts
+@Injectable()
+class UserService {
+  public constructor(
+    @Inject(CONFIG_TOKEN) private readonly config: ConfigService,
+  ) {}
+
+  public getAppName(): string {
+    return this.config.get("app.name");
+  }
+}
+
+// UserModule 不需要导入 GlobalConfigModule
+@Module({
+  providers: [UserService],
+})
+class UserModule {}
+```
+
+### 注册全局模块
+
+全局模块必须在应用中注册，通常在根模块中：
+
+```ts
+@Module({
+  imports: [
+    GlobalConfigModule, // 只需注册一次全局模块
+    GlobalLoggerModule,
+    UserModule, // UserModule 可以使用 ConfigService，无需导入它
+    ProductModule,
+  ],
+})
+class AppModule {}
+
+const app = new Application();
+app.registerModule(AppModule);
+```
+
+### 关键要点
+
+- **单次注册**：全局模块只需要注册一次（通常在根模块中）
+- **自动可用**：全局模块的导出对所有其他模块自动可用
+- **单例共享**：全局模块提供者在整个应用中保持单例行为
+- **无需导入**：其他模块不需要将全局模块添加到其 `imports` 数组中
+
+### 使用场景
+
+全局模块非常适合：
+
+- **配置服务**：全应用范围的配置访问
+- **日志服务**：集中式日志记录
+- **缓存服务**：共享缓存层
+- **数据库连接**：共享数据库访问
+- **事件发射器**：应用范围的事件总线
+
+### 示例：多个全局模块
+
+```ts
+@Global()
+@Module({
+  providers: [{ provide: LOGGER_TOKEN, useClass: LoggerService }],
+  exports: [LOGGER_TOKEN],
+})
+class GlobalLoggerModule {}
+
+@Global()
+@Module({
+  providers: [{ provide: CACHE_TOKEN, useClass: CacheService }],
+  exports: [CACHE_TOKEN],
+})
+class GlobalCacheModule {}
+
+// AppService 可以使用两者，无需显式导入
+@Injectable()
+class AppService {
+  public constructor(
+    @Inject(LOGGER_TOKEN) private readonly logger: LoggerService,
+    @Inject(CACHE_TOKEN) private readonly cache: CacheService,
+  ) {}
+}
+```
+
+## 12. 测试建议
 
 - 使用 `tests/utils/test-port.ts` 获取自增端口，避免本地冲突。
 - 在 `afterEach` 钩子中调用 `RouteRegistry.getInstance().clear()` 和