LooplanSL队列服务

基于Bun的serverless队列服务，提供轻量级异步任务执行功能。

功能特点

• 简单的API接口，易于集成
• 基于Redis的可靠存储
• 自动扫描和执行队列任务
• 支持自定义HTTP头和请求数据
• 应用级别的验证和授权
• 可配置的重试机制和退避策略
• 失败任务的日志记录
• 自动清理已完成和失败的任务
• 支持JSONC格式的配置文件（带注释的JSON）
• 支持配置文件中的尾随逗号（如 {"a": 1,}）
• 支持全局npm/bun安装使用
• 提供初始化命令，自动创建配置文件

安装依赖

本地开发安装

bun install

全局安装

# 使用npm
npm install -g looplan-sl-queue

# 或使用bun
bun install -g looplan-sl-queue

运行服务

本地开发模式

bun run --watch src/index.ts
# 或
bun start

全局安装模式

# 可用命令
looplan-queue help       # 显示帮助信息
looplan-queue init       # 在当前目录创建配置文件
looplan-queue start      # 启动队列服务（默认命令）

# 简单使用方法
cd your-project-dir      # 进入您的项目目录
looplan-queue init       # 创建配置文件
looplan-queue            # 启动队列服务

当使用全局安装模式运行时，将使用当前工作目录下的queue.config.json文件进行配置。如果配置文件不存在，服务将无法启动，请先运行looplan-queue init创建配置文件。

运行测试

bun test

配置文件

服务通过queue.config.json文件进行配置，支持JSONC格式（带注释的JSON）和尾随逗号：

{
  "port": 3000, // 根级端口设置，向后兼容
  /* 
   * 应用配置列表
   * 每个应用必须有name和token
   */
  "apps": [
    {
      "name": "test", // 应用名称
      "token": "1234567890", // 应用验证令牌
      "description": "测试应用", // 应用描述，支持尾随逗号
    }
  ],
  "queue": {
    "defaultRetryTimes": 3, // 默认重试次数
    "retryStrategy": { // 重试策略
      "initialDelay": 60000, // 初始延迟（毫秒）
      "maxDelay": 3600000, // 最大延迟（毫秒）
      "factor": 2, // 指数退避因子，支持尾随逗号
    },
    "scanInterval": 5000, // 扫描间隔（毫秒）
    "logFailedTasks": true, // 记录失败任务日志
    "cleanupInterval": 86400000, // 清理间隔（毫秒）
  },
  "redis": {
    "host": "127.0.0.1",
    "port": 6379,
    "password": "", // 密码，为空表示无密码
    "db": 0, // 数据库索引
  },
  "server": {
    "port": 3000, // 服务端口
    "host": "0.0.0.0", // 主机地址
  },
}

API接口

注册队列任务

POST /register

请求体示例:

{
  "name": "task_name",
  "appName": "test",
  "data": {
    "key": "value"
  },
  "url": "http://your-callback-url.com/endpoint",
  "retryTimes": 3,
  "headers": {
    "Content-Type": "application/json",
    "token": "1234567890"
  }
}

参数说明：

• name: 任务名称（必填）
• appName: 应用名称，必须与配置文件中的应用一致（必填）
• data: 要发送给回调URL的数据（可选）
• url: 要调用的回调URL（必填）
• retryTimes: 失败时最大重试次数，0表示不重试（可选，默认使用配置中的值）
• headers: 调用回调URL时使用的请求头（可选）
  • 请求头中必须包含token或Authorization用于验证

响应示例:

{
  "success": true,
  "queueId": "test-task_name:1634567890123"
}

重试策略

队列服务使用指数退避策略进行重试。每次重试的延迟时间计算公式为：

延迟时间 = min(初始延迟 * (因子 ^ 重试次数), 最大延迟)

例如，使用默认配置（初始延迟=60秒，因子=2，最大延迟=1小时）：

• 第1次重试：60秒后
• 第2次重试：120秒后（60 * 2^1）
• 第3次重试：240秒后（60 * 2^2）
• 以此类推...

客户端调用示例

JavaScript/TypeScript

import axios from 'axios';

await axios.post('http://queue.example.com/register', {
  name: 'email_notification',
  appName: 'email',
  data: {
    userId: 123,
    message: 'Hello world'
  },
  url: 'http://your-service.com/api/process-email',
  retryTimes: 5,
  headers: {
    'Content-Type': 'application/json',
    'token': 'email-token-123'
  }
});

PHP

// 使用Queue类
$queue = Queue::src([
  'app' => 'email',
  'token' => 'email-token-123',
  'base_url' => 'http://localhost:3000'
]);

$result = $queue->register([
  'name' => 'email-notification',
  'data' => [
    'userId' => 123,
    'message' => 'Hello world'
  ],
  'url' => 'http://your-service.com/api/process-email',
  'retryTimes' => 5
]);

环境要求

• Bun运行时环境
• Redis服务器

队列延迟执行功能

队列服务支持以下执行方式：

1. 立即执行：默认方式，队列任务将在注册后立即执行。

2. 延迟执行：通过设置delay参数（毫秒），队列任务将在指定延迟时间后执行。

   {
     "name": "delayed-task",
     "url": "http://your-service/callback",
     "appName": "your-app",
     "delay": 60000, // 延迟60秒执行
     "headers": {
       "token": "your-token"
     }
   }

3. 定时执行：通过设置scheduledTime参数（时间戳，毫秒），队列任务将在指定时间执行。

   {
     "name": "scheduled-task",
     "url": "http://your-service/callback",
     "appName": "your-app",
     "scheduledTime": 1714559438000, // 在指定时间戳执行
     "headers": {
       "token": "your-token"
     }
   }

延迟队列功能适用于：

• 延迟通知和提醒
• 定时任务处理
• 减轻系统峰值负载
• 实现工作流延迟步骤