ARTICLE DETAIL

资讯详情

深耕网站视觉设计与运营推广的一线实战洞察。

agenda-rest 使用指南:为 Node.js 任务调度器 Agenda 构建 REST API 管理服务

agenda-rest 使用指南:为 Node.js 任务调度器 Agenda 构建 REST API 管理服务 【免费下载链接】agendaLightweight job scheduling for Node.js项目地址https://gitcode.com/gh_mirrors/ag/agenda点击查看免费下载agenda-rest 是 Agenda 生态中一个轻量级 REST API 服务用于通过 HTTP 接口定义、调度和管理 Agenda 任务Job。本文将以 packages/agenda-rest/README.md 为核心结合该包源码与测试完整讲解如何从仓库启动服务、以编程方式挂载createServer()、配置X-API-Key认证以及逐一使用 9 个 REST 端点完成任务定义、一次性调度、周期调度与取消操作并深入剖析其底层调用链与错误约定。一、agenda-rest 是什么agenda-rest对外暴露了一个小巧的 Koa 应用提供如下能力定义任务Job Definition通过POST /api/job注册一个任务可携带 webhook 地址任务触发时自动向该地址发起 HTTP 请求调度一次性任务立即执行now或在指定时间执行once调度周期任务按固定间隔重复执行every取消任务按任务名或数据条件批量取消健康检查GET /api/health无需认证即可探测服务存活。它既可以作为独立 CLI 服务在仓库中直接启动也可以作为中间件/应用被createServer()以编程方式挂载到任意 Node.js 服务中这与 README 中的定位完全一致见 packages/agenda-rest/README.md 开头说明。从依赖结构看该包基于 Koa 生态构建koa、koa-router、koa-bodyparser负责 HTTP 层commander负责 CLI 参数解析agenda与agendajs/mongo-backend提供任务调度与 MongoDB 持久化能力见 package.json 的dependencies字段。二、环境要求运行 agenda-rest 需要满足依赖说明Node.js 18 或更高版本源码与engines字段均要求18.0.0见 package.jsonMongoDB 数据库CLI 服务器模式通过 MongoBackend 连接 MongoDB 持久化任务Agenda 实例使用createServer()编程方式挂载时必须传入一个已初始化的 Agenda 实例三、从仓库运行与 CLI 选项3.1 安装、构建与启动在仓库根目录依次执行pnpm install pnpm --filter agenda-rest build pnpm --filter agenda-rest start -- --uri mongodb://localhost:27017/agenda服务默认监听4040端口所有路由挂载在/api前缀下。构建产物输出到dist/CLI 入口由 bin/agenda-rest.js 指向dist/cli.js。3.2 CLI 选项pnpm --filter agenda-rest start -- \ --uri mongodb://localhost:27017/agenda \ --collection agendaJobs \ --port 4040 \ --api-key secret-key选项默认值说明--urimongodb://localhost:27017/agendaMongoDB 连接 URI--collectionagendaJobsAgenda 使用的 MongoDB 集合名--port4040HTTP 服务监听端口--api-key无配置后启用X-API-Key认证--timeout5000请求超时时间毫秒这些选项在 cli.ts 中通过commander定义同时支持短参数别名-u、-c、-p、-k、-t。3.3 CLI 启动流程源码视角从 cli.ts 的.action()实现可以看到完整启动链路解析port与timeout为整数创建new Agenda({ backend: new MongoBackend({ address, collection }) })await agenda.ready等待 MongoDB 连接就绪await agenda.start()启动任务处理器JobProcessor调用createServer({ agenda, apiKey, timeout })得到 Koa 应用app.listen(port)开始监听并在控制台打印全部端点清单注册SIGTERM/SIGINT处理实现优雅关闭先server.close()再await agenda.stop()。四、编程方式使用createServer如果要在现有 Node.js 服务中嵌入 REST API不需要 CLI直接调用createServer()import { Agenda } from agenda; import { MongoBackend } from agendajs/mongo-backend; import { createServer } from agenda-rest; const agenda new Agenda({ backend: new MongoBackend({ address: mongodb://localhost:27017/agenda, collection: agendaJobs }) }); await agenda.ready; await agenda.start(); const app createServer({ agenda, apiKey: secret-key }); app.listen(4040, () { console.log(agenda-rest listening on http://localhost:4040); });createServer返回的是一个标准 Koa 实例app.callback()可直接交给 Node HTTP 服务器或 Express 等框架托管其配置类型AgendaRestConfig定义在 types.ts配置项类型说明agendaAgenda要操作的 Agenda 实例必填缺省会直接抛错mongoUristringMongoDB 连接 URICLI 内部使用dbNamestring数据库名collectionstring任务集合名apiKeystringAPI 密钥用于X-API-Key认证timeoutnumber请求超时毫秒portnumber监听端口CLI 模式使用在 server.ts 中若未传入agendacreateServer会直接抛出Agenda instance is required这也是测试套件统一以{ agenda }构造应用的原因见 api.test.ts。五、认证机制配置apiKey后除健康检查外的所有端点都要求请求头携带X-API-Keycurl -H X-API-Key: secret-key http://localhost:4040/api/job其实现位于 server.ts 的authenticate中间件当apiKey存在且请求头x-api-key不匹配时直接返回403与{ error: Forbidden: Invalid API key }。测试用例覆盖了三种场景无密钥请求返回 403、错误密钥返回 403、正确密钥放行见 api.test.ts。注意两点GET /api/health未挂载authenticate因此无需认证即可访问server.ts若apiKey未配置authenticate直接放行所有请求——生产环境务必配置密钥或在前置网关层做防护。六、端点详解所有端点均位于/api前缀下请求体由koa-bodyparser解析为 JSON。以下结合 server.ts 的实现逐一说明。6.1GET /api/health— 健康检查返回服务健康状态无需认证{ status: ok }对应测试断言res.body.status ok见 api.test.ts。6.2GET /api/job— 列出任务定义返回通过 REST API 创建的内存态任务定义列表注意这里列出的是定义而非数据库中的任务实例curl -H X-API-Key: secret-key http://localhost:4040/api/job响应形如{ jobs: [ { name: ..., url: ..., method: ... } ] }响应结构见 types.ts。实现上定义存放在createServer内部的Mapstring, StoredJobDefinition中server.ts因此重启进程后定义会丢失但已调度进 MongoDB 的任务实例不会丢失。6.3POST /api/job— 创建任务定义curl -X POST http://localhost:4040/api/job \ -H Content-Type: application/json \ -H X-API-Key: secret-key \ -d { name: send-report, url: https://example.com/jobs/send-report, method: POST, headers: { Authorization: Bearer token }, body: { report: daily } }请求体类型为JobDefinitionRequesttypes.ts支持字段字段类型说明namestring任务名必填urlstring任务执行时请求的 webhook 地址methodstringHTTP 方法默认POSTheadersRecordstring, string请求头会自动合并Content-Type: application/jsonbodyunknown默认请求体callback{ url, method?, headers? }可选回调 webhook任务执行完成后上报结果校验规则与状态码均与测试一一对应缺少name返回400 { error: Job name is required }同名定义已存在返回409 { error: Job xxx already exists }创建成功返回200 { success: true, message: Job xxx created }。6.4PUT /api/job/:jobName— 更新任务定义curl -X PUT http://localhost:4040/api/job/send-report \ -H Content-Type: application/json \ -H X-API-Key: secret-key \ -d { url: https://example.com/jobs/send-daily-report }请求体是JobDefinitionRequest的部分字段与已有定义做浅合并{ ...existing, ...body, name: jobName }见 server.ts。目标定义不存在时返回404 { error: Job xxx not found }。6.5DELETE /api/job/:jobName— 删除任务定义curl -X DELETE \ -H X-API-Key: secret-key \ http://localhost:4040/api/job/send-report删除定义的同时会取消所有同名任务实例内部调用await agenda.cancel({ name: jobName })server.ts因此该操作是定义 实例双重清理。定义不存在时返回404。6.6POST /api/job/now— 立即执行curl -X POST http://localhost:4040/api/job/now \ -H Content-Type: application/json \ -H X-API-Key: secret-key \ -d { name: send-report, data: { report: daily } }内部调用agenda.now(name, data)成功后返回{ success: true, jobId }。若任务名尚未定义会先通过ensureJobDefined动态补一个定义再调度。缺少name返回400执行异常返回500并携带错误信息。6.7POST /api/job/once— 定时执行一次curl -X POST http://localhost:4040/api/job/once \ -H Content-Type: application/json \ -H X-API-Key: secret-key \ -d { name: send-report, when: in 1 hour, data: { report: daily } }when字段既支持人类可读的时间表达式如in 1 hour也支持Date对象ScheduleJobRequest.when: string | Date。内部调用agenda.schedule(when, name, data)缺少when时返回400测试见 api.test.ts。6.8POST /api/job/every— 周期执行curl -X POST http://localhost:4040/api/job/every \ -H Content-Type: application/json \ -H X-API-Key: secret-key \ -d { name: send-report, interval: 5 minutes, data: { report: daily } }interval支持类似5 minutes的人类可读间隔由 Agenda 内部的human-interval库解析为毫秒数参见 utils/processEvery.ts。内部调用agenda.every(interval, name, data)every的完整签名含timezone、skipImmediate、skipDays等可选参数定义在 agenda/src/index.ts 中。缺少interval时返回400。6.9POST /api/job/cancel— 取消任务curl -X POST http://localhost:4040/api/job/cancel \ -H Content-Type: application/json \ -H X-API-Key: secret-key \ -d { name: send-report }按任务名或数据条件过滤取消请求体为{ name?, data? }两个条件都为空返回400 { error: name or data is required to cancel jobs }内部调用agenda.cancel({ name, data })server.ts返回{ success: true, message: Cancelled N job(s), cancelledCount: N }。测试中连续调度 2 个同名任务后取消断言cancelledCount 2见 api.test.ts。七、Webhook 执行机制深入这是 agenda-rest 最核心的运行时行为ensureJobDefinedserver.ts会在任务第一次被调度时向 Agenda 注册一个动态处理器若agenda.definitions[name]已存在则跳过保证幂等任务执行时从内存定义中取出url、method默认POST、headers、body用 Node.js 内置fetch向url发起请求请求体取job.attrs.data ?? def.body的 JSON 序列化结果并自动附带Content-Type: application/json若配置了callback.url则在主请求完成后回调该地址上报{ job, status: success | failed, statusCode }请求抛出异常时记录Job xxx failed日志并向上抛错使该任务实例进入失败状态可由 Agenda 的重试/退避机制接管。这意味着纯数据型任务未配置url的定义执行时只做存储/触发不发起任何外部请求适合作为定时数据管道的中转节点。八、开发与测试# 运行包级测试套件 pnpm --filter agenda-rest test # 构建包 pnpm --filter agenda-rest build测试基于vitestsupertest通过mongodb-memory-server起一个内存 MongoDB 完成端到端验证见 test/api.test.ts。测试覆盖矩阵包括健康检查、任务定义的创建/列出/更新/删除含 400/404/409 错误路径、四种调度方式now/once/every/cancel的成功与参数缺失场景、以及 API Key 认证的三种情形。启动测试所需的全局初始化逻辑在 test/helpers/global-setup.tsMongo 模拟环境在 test/helpers/mock-mongodb.ts。九、在 Agenda 生态中的定位agenda-rest 是 Agenda 6.x 生态的组成部分与核心包agenda任务调度引擎、agendajs/mongo-backendMongoDB 持久化后端协同工作。其价值在于将 Agenda 的编程式 APIdefine/schedule/every/cancel封装为 HTTP 接口让非 Node.js 技术栈或解耦的微服务也能通过 REST 方式管理任务。需要理解底层任务调度语义时可进一步阅读 agenda 核心源码 中的every、schedule、cancel实现以及 mongo-backend 的仓库层。十、快速参考端点一览方法路径功能关键入参主要错误码GET/api/health健康检查无—GET/api/job列出任务定义无—POST/api/job创建任务定义name必填url/method/headers/body/callback400、409PUT/api/job/:jobName更新任务定义部分字段404DELETE/api/job/:jobName删除定义并取消同名任务无404POST/api/job/now立即执行name必填data可选400、500POST/api/job/once定时执行一次name、when必填400、500POST/api/job/every周期执行name、interval必填400、500POST/api/job/cancel取消任务name或data至少其一400、500配置了apiKey时除/api/health外所有端点均需携带X-API-Key请求头否则返回403。整个服务可通过 packages/agenda-rest/README.md 与上述源码路径进一步探索。赞分享【免费下载链接】agendaLightweight job scheduling for Node.js项目地址https://gitcode.com/gh_mirrors/ag/agenda点击查看免费下载相关推荐Agenda任务优先级动态调整API构建管理界面Agenda任务优先级动态调整API构建管理界面 你是否曾因高优先级任务被低优先级任务阻塞而困扰运营人员是否需要频繁登录服务器手动调整任务队列本文将带你通Nature Skills 文献检索实战nature-academic-search 多源检索与严格他引审计Nature Skills 文献检索实战nature academic search 多源检索与严格他引审计 做科研最耗时的环节之一就是 文献检索 在 PAI 技能科研AI 应用HestiaCP服务器管理REST API使用完全指南HestiaCP服务器管理REST API使用完全指南 什么是HestiaCP的REST API HestiaCP的REST API是一套强大的接口系统允许后端运维上一篇miniblink49 中 Skia 的集成构建教程gclient DEPS GYP ninja 从零搭建下一篇思源宋体CN完整使用指南7种字重免费商用中文设计一步到位创作声明:本文部分内容由AI辅助生成(AIGC),仅供参考
返回列表