#定时任务 API

Jobs 在应用就绪后自动调度导出的任务。完整流程、部署与故障排查见定时任务指南，行为约束见定时任务契约。本页是配置与定义字段的完整参考。

#defineJob

import { defineJob, isVextJobDefinition } from "vextjs";
import type {
  VextJobDefinition,
  VextJobDefinitionInput,
  VextJobHandler,
  VextJobContext,
  VextJobDocsConfig,
  VextJobsConfig,
} from "vextjs";

function defineJob(input: VextJobDefinitionInput): VextJobDefinition;
function isVextJobDefinition(value: unknown): value is VextJobDefinition;

type VextJobDefinitionInput = {
  name?: string;
  description?: string;
  tags?: string[];
  docs?: VextJobDocsConfig;
  enabled?: boolean;
  handler: VextJobHandler;
} & (
  | { cron: string; interval?: never; timezone?: string }
  | { interval: number; cron?: never; timezone?: never }
);

type VextJobHandler = (ctx: VextJobContext) => unknown | Promise<unknown>;
interface VextJobContext {
  app: VextApp;
  name: string;
  scheduledAt: Date;
  signal: AbortSignal;
  logger: VextApp["logger"];
}
interface VextJobDocsConfig {
  summary?: string;
  description?: string;
  tags?: string[];
}

未声明的可选字段可采用默认值；显式无效值不会采用默认值。即使 enabled: false，定义也必须包含合法调度和 handler。未知顶层字段会报错。defineJob() 校验并冻结顶层对象，返回带内部识别标记的定义；不能用普通对象冒充。冻结不是对嵌套 docs/tags 的深冻结。

#handler 上下文

#VextJobsConfig

在 src/config/default.ts 或所选 profile 配置的 jobs 字段中填写。配置结构在应用启动时校验，调度发现和 Redis 初始化在 HTTP 监听前完成；配置合并顺序仍适用。

interface VextJobsConfig {
  enabled?: boolean;
  dir?: string;
  include?: string[];
  exclude?: string[];
  timezone?: string;
  redis?: {
    url?: string;
    uri?: string;
    client?: unknown;
    namespace?: string;
    keyPrefix?: string;
    leaseTtl?: number;
  };
}

namespace 归一化会去掉开头 @，把 /、\ 转为 .，把其他不支持字符替换为 -，合并连续分隔符并去首尾分隔符；允许字母、数字与 _ . : -。例如 @team/my-app:production:production 得到 team.my-app:production:production。无法读取有效包名时使用 vextjs-app；归一化结果为空也回退为 vextjs-app。不同应用共用 Redis 时应核对归一化后是否相同。

默认逻辑前缀为 vext:<namespace>:job:。实际 key 结构、残留触发标记与 Redis Cluster 部署见多副本指南。Jobs 不借用 Session、缓存或限流的 Redis 配置。只有环境 URL 但没有 jobs.redis 对象时不会启用协调；可使用 redis: {} 配合环境变量。

#文档源

openapi.docs.code.jobs: true 默认继承 jobs.dir/include/exclude；显式 Docs 字段分别覆盖相应字段，false 仅关闭文档扫描。定义被关闭仍可生成文档。声明时区、全局时区回退、开关与静态解析状态会显示在项目 Docs 的 Jobs 分类中；这些信息不是运行状态。具体配置、JSDoc 优先级、静态解析边界见文档与 MCP。

#错误与执行边界

• VextJobDefinitionError：定义无效、导入失败、任务文件没有 defineJob() 导出或没有可表示的未来触发点。
• VextJobDuplicateNameError：加载名称冲突，包括关闭的定义。
• 配置错误及活跃 Cluster 缺 Redis：启动拒绝，检查报错中的字段路径。
• 配置 Redis 的活跃任务：初始化验证连接、PING 与 Lua EVAL；失败时拒绝启动。
• 同任务重叠跳过；失败只记录日志；没有队列、自动重试、停机补跑或启动立即执行。
• 关闭在 shutdown.timeout 的总预算内等待并请求取消，不能强行中断忽略 signal 的函数。
• Redis 健康共享状态下协调同一触发点；不保证业务副作用恰好一次。

#测试入口

createTestJobScheduler、CreateTestJobSchedulerOptions、TestJobScheduler 从 vextjs/testing 导入；tick(Date) 使用真实调度规则但不创建真实定时器、不扫描项目任务。普通 createTestApp 也不自动加载 Jobs。详见测试 API与验收和排查。