faasjs-api-jobs

FaasJS API 与任务

默认工作流

1. 将 API 和任务文件放在负责相应行为的功能切片中。
2. 在边界处定义外部输入架构，并通过 params.key 保持业务输入清晰可见。
3. 对预期的 API 失败使用带有明确状态码的 HttpError；仅将普通 Error 用于内部失败。
4. 使用注入的 HTTP 辅助工具处理 Cookie、会话、请求头、状态码、请求体和内容类型。
5. 将任务视为至少执行一次，明确执行入队操作，并确保生成的路径与运行时发现机制一致。

加载以下参考资料

• .api.ts、defineApi、架构、params、错误、注入字段和类型生成：references/guidelines/define-api.md。
• Cookie、会话、响应辅助工具和 HTTP 插件配置：references/guidelines/http-plugin.md。
• 静态文件服务和中间件：references/guidelines/middleware.md。
• .job.ts、defineJob、enqueueJob、进程所有权和与事务绑定的入队操作：references/guidelines/jobs.md。
• 生成的任务路径、params 类型、类型生成、重复路径和发现根目录：references/guidelines/job-types-and-paths.md。
• Cron 表达式、调度器去重、重试、尝试次数和租约过期：references/guidelines/job-scheduling-and-retries.md。
• 直接处理器、队列、工作进程、调度器、事务、类型和发现机制测试：references/guidelines/job-testing.md。

注意事项

• 仅解构处理器上下文的顶层字段，例如 handler({ params })；不要从 params 中解构业务字段。
• 添加、重命名、移动或删除 .api.ts 或 .job.ts 文件后，运行 npx faas types；普通处理器编辑不会改变路径声明。
• 不要将动态字符串强制转换为生成的任务路径，也不要在回调结束后保留事务客户端。
• 读取或修改数据前，检查用户、租户、组织、项目、角色或权限范围。
• 不要记录机密、令牌、密码、Cookie、完整的敏感负载或未经脱敏的第三方响应。

验证

• 使用 vp test <pattern> 运行针对性的 API 或任务测试。
• API 或任务路径结构发生变化后，运行 npx faas types。
• 后端文件发生变更后，交接前运行 vp check --fix。