@lark-apaas/nestjs-trigger

@lark-apaas/nestjs-trigger

为 NestJS 应用提供声明式自动化任务注册与执行能力的核心模块。

基于 TriggerClient 实现，提供 @Automation/@BindTrigger 装饰器、自动发现机制、REST 触发接口，以及与 trigger-server 的完整集成。

功能特性

• 🎯 声明式 API - 使用 @Automation 和 @BindTrigger 装饰器定义自动化任务
• 🔍 自动发现 - 应用启动时自动扫描并注册所有自动化任务
• 📝 强类型 - 完整的 TypeScript 类型定义与类型推断
• 🔒 1:1 绑定 - 强制每个 triggerName 只能绑定一个方法，避免冲突
• 📡 日志上报 - 集成观测系统，自动上报执行状态
• 📊 日志跟踪 - 完整的执行生命周期日志记录

安装

npm install @lark-apaas/nestjs-trigger
# 或
yarn add @lark-apaas/nestjs-trigger

快速开始

1. 导入模块

在根模块中导入 AutomationModule：

import { Module } from '@nestjs/common';
import { AutomationModule } from '@lark-apaas/nestjs-trigger';

@Module({
  imports: [AutomationModule.forRoot()],
})
export class AppModule {}

2. 定义自动化任务

使用 @Automation() 和 @BindTrigger() 装饰器定义任务：

// xxx.automation.ts
import { Automation, BindTrigger } from '@lark-apaas/nestjs-trigger';

@Automation()
export class MyAutomationService {
  /**
   * 简单的问候任务
   */
  @BindTrigger('task-hello', { 
    actionName: 'HelloTask', 
    actionDesc: 'Print hello message' 
  })
  async hello(name: string) {
    return `Hello, ${name}!`;
  }

  /**
   * 定时任务示例 - 每周五15:00执行
   */
  @BindTrigger('cron1[0 15 * * Fri]', {
    actionName: 'SendWeeklyEmail',
    actionDesc: '每周五15:00发送邮件'
  })
  async sendWeeklyEmail() {
    // 每周五发送邮件逻辑
    return { success: true, sentAt: new Date() };
  }
}

3. 导入

在 XXXModule 中导入 MyAutomationService：

import { Module } from '@nestjs/common';
import { XController } from './x.controller';
import { MyAutomationService } from './my.automation';

@Module({
  controllers: [XController],
  providers: [MyAutomationService],
})
export class XModule {}

核心概念

@Automation()

类装饰器，标记一个类为自动化任务控制器。

@Automation()
@Injectable()
export class EmailAutomation {
  // 任务方法定义
}

@BindTrigger()

方法装饰器，将方法绑定到指定的 trigger。

参数：

@BindTrigger(trigger: string, options?: {
  actionName?: string;    // 任务名称
  actionDesc?: string;    // 任务描述
})

使用示例：

@Automation()
export class NotificationAutomation {
  @BindTrigger('cron1[0 15 * * Fri]', {
    actionName: 'SendWelcomeEmail',
    actionDesc: '每周五15:00发送欢迎邮件'
  })
  async sendWelcomeEmail(userId: string, email: string) {
    // 发送欢迎邮件逻辑
    return { success: true, userId };
  }

  @BindTrigger('process-payment', {
    actionName: 'ProcessPayment',
    actionDesc: 'Process user payment'
  })
  async processPayment(orderId: string, amount: number) {
    // 处理支付逻辑
    return { success: true, orderId, amount };
  }
}

重要特性：

• 1:1 绑定约束：每个 trigger 只能绑定一个方法，重复绑定会抛出错误
• 自动注册：应用启动时自动扫描并注册所有绑定的任务
• 类型安全：支持完整的 TypeScript 类型推断

API 参考

AutomationController

提供 REST API 接口，用于接收 trigger-server 的请求。

接口详情：

POST /innerapi/automation/invoke

请求体：

export interface TriggerExecutionDto {
  trigger?: string;
  triggerID?: string;
  triggerType?: string; // cron
  instanceID?: string;
  startAt?: number;
  parameter?: string;
}

响应：

{
  "code": 200,
  "message": ""
}

状态码说明：

• 200: 接收成功，异步执行
• 400: 缺少必填字段
• 404: triggerID 未注册
• 500: 内部错误

与 trigger-server 集成

集成架构

Trigger Server → HTTP POST /innerapi/automation/invoke
                    ↓
         AutomationController
                    ↓
         AutomationService.executeAction()
                    ↓
         TriggerClient.executeAction()
                    ↓
         实际任务方法执行
                    ↓
         TriggerClient.report() → 观测系统

开发与测试

本地开发

# 安装依赖
yarn install

# 构建
yarn build

本地调试接口

# 获取调试列表
curl -X GET /dev/logs/trace/trigger/list?trigger=xx&triggerID=xx

# 获取调试详情
curl -X GET /dev/logs/trace/trigger/:instanceID

许可证

MIT