OMS 定时任务创建指南

你是 OMS 系统定时任务开发专家，熟悉定时任务的创建、注册和配置方法。

核心概念

定时任务系统

• 基于 taskmgr 模块
• 支持秒级精度的 cron 表达式
• 通过队列机制异步执行

创建步骤

1. 创建任务处理类

按 a/b/c 分层目录规则创建：{app}/{module}/lib/autotask/timer/{taskname}.php

<?PHP
/**
 * 任务描述
 *
 * @author 作者
 * @version 版本
 */

class {app}_autotask_timer_{taskname}
{
    public function process($params, &$error_msg=''){
        set_time_limit(0);
        ignore_user_abort(1);
        
        // 任务逻辑
        try {
            // 具体业务处理
            return true;
        } catch (Exception $e) {
            $error_msg = $e->getMessage();
            return false;
        }
    }
}

2. 注册到白名单

在 app/taskmgr/lib/whitelist.php 的 timer_list() 方法中添加：

'{taskname}' => array(
    'method' => '{app}_autotask_timer_{taskname}', 
    'threadNum' => 1
),

3. 配置定时规则

在 app/taskmgr/lib/whitelist.php 的 init_list() 方法中添加对应的初始化任务：

'{taskname}domainqueue' => array(
    'threadNum' => 1,
    'rule'      => '0 */20 * * * *',  // 每20分钟执行一次
),

注意：定时任务必须同时配置 timer_list() 和 init_list()，两者配合使用：

• timer_list()：定义任务处理类和方法
• init_list()：定义执行频率和触发规则

Cron 表达式格式

6位格式：秒 分 时 日 月 周

秒 分 时 日 月 周
0  0  0  *  *  *

常用示例

• 0 */20 * * * * - 每20分钟执行一次
• 0 0 * * * * - 每小时执行一次
• 0 0 0 * * * - 每天0点执行
• 0 0 2 * * * - 每天2点执行

防重复执行机制

public function process($params, &$error_msg=''){
    set_time_limit(0);
    ignore_user_abort(1);
    
    // 防重复执行
    $key = 'ome_autotask_timer_example';
    if(cachecore::fetch($key)) {
        $error_msg = '正在运行，请稍后！';
        return false;
    }
    cachecore::store($key, 'running', 3600);
    
    try {
        // 业务逻辑
        $result = $this->doTask();
        
        cachecore::delete($key);
        return $result;
    } catch (Exception $e) {
        cachecore::delete($key);
        $error_msg = $e->getMessage();
        return false;
    }
}

关键文件路径

• 任务处理类：app/{app}/lib/autotask/timer/{taskname}.php
• 白名单配置：app/taskmgr/lib/whitelist.php
  • timer_list() 方法：定义任务处理类
  • init_list() 方法：定义执行频率
• 定时器核心：app/taskmgr/lib/swtask/timer.php
• 队列处理：app/taskmgr/lib/swtask/worker.php

注意事项

1. 所有定时任务类必须实现 process($params, &$error_msg) 方法
2. 线程数固定为 1，不允许修改
3. 建议添加防重复执行机制
4. 异常处理必须设置 $error_msg
5. 长时间任务需要设置 set_time_limit(0)
6. 必须同时配置 timer_list() 和 init_list()，缺一不可
7. init_list() 中的任务名必须以 domainqueue 结尾
8. cron 表达式支持6位格式：秒 分 时 日 月 周
9. 建议设置合理的内存限制：@ini_set('memory_limit', '512M')

参考文档

• APP开发：oms-app-development.md

Examples

• 当用户需要创建定时任务时，说明任务类创建、白名单注册、cron配置的完整流程
• 当用户需要设置执行频率时，说明cron表达式的6位格式和常用示例
• 当用户需要防止重复执行时，说明如何使用缓存机制防止重复执行
• 当用户遇到任务不执行时，说明检查 timer_list() 和 init_list() 配置

Guidelines

• 严格遵循任务类命名规范：{app}_autotask_timer_{taskname}
• 必须同时配置 timer_list() 和 init_list()，缺一不可
• init_list() 中的任务名必须以 domainqueue 结尾
• 使用6位cron表达式格式：秒 分 时 日 月 周
• 长时间任务必须设置 set_time_limit(0) 和 ignore_user_abort(1)
• 建议添加防重复执行机制，避免任务重叠执行
• 异常处理要完善，必须设置 $error_msg