@lark-apaas/nestjs-trigger

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

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

功能特性

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

安装

``bash
npm install @lark-apaas/nestjs-trigger


或


yarn add @lark-apaas/nestjs-trigger
`

快速开始

$3

在根模块中导入 AutomationModule：

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

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

$3

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

`typescript
// 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：

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

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

核心概念

$3

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

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

$3

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

参数：

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

使用示例：

`typescript
@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 参考

$3

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

接口详情：

`http
POST /innerapi/automation/invoke
`

请求体：

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

响应：

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

状态码说明：

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

与 trigger-server 集成

$3

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

开发与测试

$3

`bash


安装依赖

yarn install

构建

yarn build

`

$3

`bash


获取调试列表

curl -X GET /dev/logs/trace/trigger/list?trigger=xx&triggerID=xx

获取调试详情

curl -X GET /dev/logs/trace/trigger/:instanceID
``

许可证

MIT