imean-service-engine 2.0.0 → 2.0.2

package/src/plugins/route/types.ts

@@ -1,72 +0,0 @@
-import { MiddlewareHandler } from "hono";
-import { ContentfulStatusCode } from "hono/utils/http-status";
-
-// HTTP方法类型
-export type HTTPMethod =
-  | "GET"
-  | "POST"
-  | "PUT"
-  | "DELETE"
-  | "PATCH"
-  | "HEAD"
-  | "OPTIONS";
-/**
- * Route装饰器配置选项
- */
-export interface RouteOptions {
-  /**
-   * HTTP方法（可选，默认为 GET）
-   * 如果未指定，则默认为 GET 方法
-   */
-  method?: HTTPMethod | HTTPMethod[]; // HTTP方法
-  /**
-   * 路由路径（支持单个路径或多个路径）
-   * 如果提供数组，将为每个路径注册相同的处理器
-   */
-  path: string | string[]; // 路由路径
-  /**
-   * 路由专属中间件
-   */
-  middlewares?: MiddlewareHandler[]; // 路由专属中间件
-  /**
-   * 路由描述（用于文档和日志）
-   */
-  description?: string;
-  /**
-   * 请求参数校验规则
-   */
-  validate?: {
-    query?: Record<string, any>;
-    body?: Record<string, any>;
-    params?: Record<string, any>;
-  };
-  /**
-   * 响应配置
-   */
-  response?: {
-    status?: ContentfulStatusCode;
-    type?: "json" | "text" | "html";
-  };
-}
-
-/**
- * RoutePlugin的Module配置
- * 注意：配置直接平铺在 Module options 中，不使用 route 命名空间
- * 插件作者需要确保字段名不与其他插件冲突
- */
-export interface RouteModuleOptions {
-  routePrefix?: string; // 模块级路由前缀（使用 routePrefix 避免与其他插件的 prefix 冲突）
-  routeMiddlewares?: MiddlewareHandler[]; // 模块级路由中间件（使用 routeMiddlewares 避免冲突）
-}
-
-/**
- * RoutePlugin 配置选项
- */
-export interface RoutePluginOptions {
-  /**
-   * 全局中间件（应用于所有路由）
-   * 执行顺序：全局中间件 -> 模块级中间件 -> 路由级中间件
-   * 常用于鉴权、日志等全局功能
-   */
-  globalMiddlewares?: MiddlewareHandler[];
-}

package/src/plugins/schedule/README.md

@@ -1,309 +0,0 @@
-# SchedulePlugin - 调度任务插件
-
-## 概述
-
-`SchedulePlugin` 是一个基于 etcd 选举机制的分布式定时任务插件。它确保在多个微服务实例中，只有一个实例会执行定时任务，避免重复执行。
-
-## 功能特性
-
-- ✅ 基于 etcd 的分布式选举机制
-- ✅ 支持固定频率（FIXED_RATE）和固定延迟（FIXED_DELAY）两种调度模式
-- ✅ 自动故障转移：当 leader 实例宕机时，其他实例会自动接管
-- ✅ 集成 OpenTelemetry 追踪
-- ✅ 优雅关闭：停止时自动清理所有定时器和选举
-
-## 安装依赖
-
-```bash
-npm install etcd3
-```
-
-## 使用方法
-
-### 方式一：使用真实的 etcd（生产环境）
-
-#### 1. 创建 etcd 客户端
-
-```typescript
-import { Etcd3 } from "etcd3";
-
-const etcdClient = new Etcd3({
-  hosts: ["localhost:2379"],
-  // 可选：认证信息
-  auth: {
-    username: "root",
-    password: "password",
-  },
-});
-```
-
-#### 2. 创建引擎并注册插件
-
-```typescript
-import { Factory } from "@imean/service-engine";
-import { SchedulePlugin } from "@imean/service-engine/plugins/schedule";
-import { Etcd3 } from "etcd3";
-
-const etcdClient = new Etcd3({
-  hosts: ["localhost:2379"],
-});
-
-const { Module, Microservice } = Factory.create(
-  new SchedulePlugin({
-    etcdClient,
-  })
-);
-```
-
-### 方式二：使用 Mock Etcd（测试和本地开发）
-
-如果不想依赖真实的 etcd 服务，可以使用内置的 Mock Etcd。Mock Etcd 会自动选举自己作为 leader，适合单实例开发和测试场景。
-
-```typescript
-import { Factory } from "@imean/service-engine";
-import { SchedulePlugin } from "@imean/service-engine/plugins/schedule";
-
-const { Module, Microservice } = Factory.create(
-  new SchedulePlugin({
-    useMockEtcd: true, // 启用 Mock Etcd，无需真实 etcd 服务
-  })
-);
-```
-
-**注意**：
-- `useMockEtcd: true` 时，插件会自动使用内置的 `MockEtcd3`
-- Mock Etcd 始终选举自己作为 leader，适合单实例场景
-- 如果同时提供了 `etcdClient` 和 `useMockEtcd: true`，会优先使用提供的 `etcdClient`
-
-### 3. 使用 @Schedule 装饰器
-
-```typescript
-import { Module } from "./engine";
-import { Schedule, ScheduleMode } from "@imean/service-engine/plugins/schedule";
-
-@Module("user-service")
-class UserService {
-  /**
-   * 固定频率模式：每 5 秒执行一次
-   * 无论任务执行时间多长，都会按照固定间隔执行
-   */
-  @Schedule({
-    interval: 5000, // 5 秒
-    mode: ScheduleMode.FIXED_RATE,
-  })
-  async syncUsers() {
-    console.log("同步用户数据...");
-    // 执行同步逻辑
-  }
-
-  /**
-   * 固定延迟模式：任务执行完成后，等待 10 秒再执行下一次
-   * 如果任务执行了 15 秒，则下次执行在 25 秒后
-   */
-  @Schedule({
-    interval: 10000, // 10 秒
-    mode: ScheduleMode.FIXED_DELAY,
-  })
-  async cleanupExpiredData() {
-    console.log("清理过期数据...");
-    // 执行清理逻辑
-    await new Promise((resolve) => setTimeout(resolve, 5000)); // 模拟耗时操作
-  }
-}
-```
-
-### 4. 启动引擎
-
-```typescript
-const engine = new Microservice({
-  name: "my-service",
-  version: "1.0.0",
-});
-
-await engine.start(3000);
-```
-
-## 调度模式说明
-
-### FIXED_RATE（固定频率）
-
-- **特点**：无论任务执行时间多长，都会按照固定间隔执行
-- **适用场景**：需要定期执行的任务，执行时间较短且稳定
-- **示例**：每 5 秒检查一次系统状态
-
-```typescript
-@Schedule({
-  interval: 5000,
-  mode: ScheduleMode.FIXED_RATE,
-})
-async checkSystemStatus() {
-  // 快速检查系统状态
-}
-```
-
-### FIXED_DELAY（固定延迟）
-
-- **特点**：任务执行完成后，等待固定间隔再执行下一次
-- **适用场景**：任务执行时间不确定，需要等待上次任务完成后再执行
-- **示例**：数据同步任务，需要等待上次同步完成
-
-```typescript
-@Schedule({
-  interval: 60000, // 1 分钟
-  mode: ScheduleMode.FIXED_DELAY,
-})
-async syncData() {
-  // 可能执行 30 秒或更长时间
-  await longRunningTask();
-}
-```
-
-## 选举机制
-
-插件使用 etcd 的选举机制来确保只有一个实例执行任务：
-
-1. **选举键格式**：`/schedule/{serviceName}/{moduleName}/{methodName}`
-2. **服务 ID**：每个实例使用唯一的服务 ID 参与选举
-3. **自动故障转移**：当 leader 实例宕机时，etcd 会自动选择新的 leader
-
-## 注意事项
-
-1. **etcd 配置**：必须正确配置 etcd 客户端，否则调度任务不会启动
-2. **网络连接**：确保所有实例都能连接到 etcd 集群
-3. **任务幂等性**：建议任务设计为幂等的，避免重复执行导致的问题
-4. **资源清理**：引擎停止时会自动清理所有定时器和选举，无需手动处理
-
-## 错误处理
-
-插件会自动记录错误日志，但不会中断引擎的运行：
-
-- 如果 etcd 连接失败，会记录警告日志，但不会启动调度任务
-- 如果任务执行失败，会记录错误日志，但不会影响其他任务
-- 如果选举失败，会记录错误日志，但不会影响其他功能
-
-## 示例：完整的使用场景
-
-```typescript
-import { Factory } from "@imean/service-engine";
-import { SchedulePlugin, Schedule, ScheduleMode } from "@imean/service-engine/plugins/schedule";
-import { Etcd3 } from "etcd3";
-
-// 1. 创建 etcd 客户端
-const etcdClient = new Etcd3({
-  hosts: ["etcd1:2379", "etcd2:2379", "etcd3:2379"],
-});
-
-// 2. 创建引擎
-const { Module, Microservice } = Factory.create(
-  new SchedulePlugin({
-    etcdClient,
-  })
-);
-
-// 3. 定义服务模块
-@Module("data-service")
-class DataService {
-  @Schedule({
-    interval: 30000, // 30 秒
-    mode: ScheduleMode.FIXED_RATE,
-  })
-  async syncData() {
-    console.log("同步数据...");
-    // 同步逻辑
-  }
-
-  @Schedule({
-    interval: 600000, // 10 分钟
-    mode: ScheduleMode.FIXED_DELAY,
-  })
-  async cleanupOldData() {
-    console.log("清理旧数据...");
-    // 清理逻辑
-  }
-}
-
-// 4. 启动引擎
-const engine = new Microservice({
-  name: "data-service",
-  version: "1.0.0",
-});
-
-await engine.start(3000);
-console.log("服务已启动，调度任务已注册");
-```
-
-### 本地开发/测试（使用 Mock Etcd）
-
-```typescript
-import { Factory } from "@imean/service-engine";
-import { SchedulePlugin, Schedule, ScheduleMode } from "@imean/service-engine/plugins/schedule";
-
-// 1. 创建引擎（使用 Mock Etcd，无需真实 etcd 服务）
-const { Module, Microservice } = Factory.create(
-  new SchedulePlugin({
-    useMockEtcd: true, // 启用 Mock Etcd
-  })
-);
-
-// 2. 定义服务模块
-@Module("data-service")
-class DataService {
-  @Schedule({
-    interval: 30000, // 30 秒
-    mode: ScheduleMode.FIXED_RATE,
-  })
-  async syncData() {
-    console.log("同步数据...");
-    // 同步逻辑
-  }
-}
-
-// 3. 启动引擎
-const engine = new Microservice({
-  name: "data-service",
-  version: "1.0.0",
-});
-
-await engine.start(3000);
-console.log("服务已启动，调度任务已注册（使用 Mock Etcd）");
-```
-
-## API 参考
-
-### ScheduleOptions
-
-```typescript
-interface ScheduleOptions {
-  /**
-   * 执行间隔（毫秒）
-   */
-  interval: number;
-
-  /**
-   * 调度模式（默认 FIXED_RATE）
-   */
-  mode?: ScheduleMode;
-}
-```
-
-### SchedulePluginOptions
-
-```typescript
-interface SchedulePluginOptions {
-  /**
-   * Etcd3 客户端实例
-   * 如果未提供且 useMockEtcd 为 false，插件将不会启动调度任务
-   */
-  etcdClient?: Etcd3;
-
-  /**
-   * 是否使用 Mock Etcd（用于测试和本地开发）
-   * 当设置为 true 时，将使用内置的 MockEtcd3，始终选举自己作为 leader
-   * 这样可以在没有真实 etcd 的情况下运行调度任务
-   * 
-   * @default false
-   */
-  useMockEtcd?: boolean;
-}
-```
-

package/src/plugins/schedule/decorator.ts

@@ -1,25 +0,0 @@
-import { Handler } from "../../core/decorators";
-import { ScheduleOptions, ScheduleMode } from "./types";
-
-/**
- * Schedule装饰器
- * 用于标记需要定时调度的方法
- * 
- * @example
- * ```typescript
- * @Schedule({ interval: 5000, mode: ScheduleMode.FIXED_RATE })
- * async syncData() {
- *   // 定时执行的任务
- * }
- * ```
- */
-export function Schedule(options: ScheduleOptions) {
-  return Handler({
-    type: "schedule",
-    options: {
-      interval: options.interval,
-      mode: options.mode || ScheduleMode.FIXED_RATE,
-    },
-  });
-}
-

package/src/plugins/schedule/index.ts

@@ -1,12 +0,0 @@
-export { Schedule } from "./decorator";
-export { SchedulePlugin } from "./plugin";
-export { Scheduler } from "./scheduler";
-export { MockEtcd3 } from "./mock-etcd";
-export {
-  ScheduleMode,
-  ScheduleOptions,
-  ScheduleMetadata,
-  SchedulePluginOptions,
-} from "./types";
-export type { Etcd3, Election, Observer, Campaign } from "./types";
-

package/src/plugins/schedule/mock-etcd.ts

@@ -1,145 +0,0 @@
-import { Etcd3, Election, Observer, Campaign } from "./types";
-
-/**
- * Mock Etcd3 客户端
- * 用于测试和本地开发，模拟 etcd 的选举机制
- * 始终选举第一个参与选举的候选者作为 leader
- */
-export class MockEtcd3 implements Etcd3 {
-  private elections: Map<string, MockElection> = new Map();
-
-  election(key: string, ttl: number): Election {
-    if (!this.elections.has(key)) {
-      this.elections.set(key, new MockElection(key));
-    }
-    return this.elections.get(key)!;
-  }
-
-  getElection(key: string): MockElection | undefined {
-    return this.elections.get(key);
-  }
-
-  clearElections(): void {
-    this.elections.clear();
-  }
-}
-
-/**
- * Mock Election
- */
-class MockElection implements Election {
-  private observers: MockObserver[] = [];
-  private campaigns: MockCampaign[] = [];
-  private currentLeader: string | null = null;
-
-  constructor(private key: string) {}
-
-  async observe(): Promise<Observer> {
-    const observer = new MockObserver(this);
-    this.observers.push(observer);
-    // 如果已经有 leader，立即通知
-    if (this.currentLeader) {
-      setTimeout(() => {
-        observer.notifyChange(this.currentLeader!);
-      }, 0);
-    }
-    return observer;
-  }
-
-  campaign(candidate: string): Campaign {
-    const campaign = new MockCampaign(candidate, this);
-    this.campaigns.push(campaign);
-
-    // 如果没有当前 leader，异步选举（模拟真实 etcd 行为）
-    // 使用 setTimeout 确保回调有时间注册
-    if (!this.currentLeader) {
-      setTimeout(() => {
-        this.setLeader(candidate);
-      }, 50);
-    }
-
-    return campaign;
-  }
-
-  setLeader(leader: string): void {
-    this.currentLeader = leader;
-    // 通知所有 observers
-    for (const observer of this.observers) {
-      observer.notifyChange(leader);
-    }
-    // 通知被选中的 campaign（异步执行，确保回调已注册）
-    setTimeout(() => {
-      for (const campaign of this.campaigns) {
-        if (campaign.candidate === leader && !campaign.resigned) {
-          campaign.notifyElected();
-        }
-      }
-    }, 50);
-  }
-
-  getCurrentLeader(): string | null {
-    return this.currentLeader;
-  }
-}
-
-/**
- * Mock Observer
- */
-class MockObserver implements Observer {
-  private changeCallbacks: ((leader: string) => void)[] = [];
-
-  constructor(private election: MockElection) {}
-
-  on(event: "change", callback: (leader: string) => void): void {
-    if (event === "change") {
-      this.changeCallbacks.push(callback);
-    }
-  }
-
-  notifyChange(leader: string): void {
-    for (const callback of this.changeCallbacks) {
-      callback(leader);
-    }
-  }
-}
-
-/**
- * Mock Campaign
- */
-class MockCampaign implements Campaign {
-  private errorCallbacks: ((error: any) => void)[] = [];
-  private electedCallbacks: (() => void)[] = [];
-  public resigned: boolean = false;
-
-  constructor(
-    public readonly candidate: string,
-    private election: MockElection
-  ) {}
-
-  on(event: "error" | "elected", callback: (error?: any) => void): void {
-    if (event === "error") {
-      this.errorCallbacks.push(callback);
-    } else if (event === "elected") {
-      this.electedCallbacks.push(callback);
-    }
-  }
-
-  notifyElected(): void {
-    if (!this.resigned) {
-      for (const callback of this.electedCallbacks) {
-        callback();
-      }
-    }
-  }
-
-  notifyError(error: any): void {
-    for (const callback of this.errorCallbacks) {
-      callback(error);
-    }
-  }
-
-  async resign(): Promise<void> {
-    this.resigned = true;
-  }
-}
-