Sparkdo.CrontabQ 1.0.1

Sparkdo.CrontabQ 使用文档

简介

Sparkdo.CrontabQ 是一个功能强大、高性能的 .NET Cron 表达式解析库，专为需要精确时间调度的 .NET 应用程序而设计。该库提供了完整的 Cron 表达式解析和计算功能，使开发者能够轻松实现复杂的定时任务调度需求。

作为 Sparkdo 生态系统的一部分，Sparkdo.CrontabQ 遵循现代 .NET 开发最佳实践，提供直观的 API 设计和卓越的性能表现。无论是简单的每分钟执行任务，还是复杂的多字段组合调度，该库都能准确高效地处理。

该库基于成熟的 Cron 解析算法，经过大量测试验证，确保在各种场景下都能提供准确的时间计算结果。通过简洁的 API 设计，开发者可以快速上手并集成到现有项目中。

核心特性

1. 全面的 Cron 表达式支持

• 支持标准 Unix Cron 语法的所有特性
• 完整实现 Cron 字段：秒、分、时、日、月、周、年
• 支持特殊字符：*, ?, -, ,, /, L, W, #, R
• 兼容常见的 Cron 扩展语法

2. 多种表达式格式

• 标准格式：分 时 日 月 周 (如: 0 0 * * *)
• 带秒格式：秒 分 时 日 月 周 (如: 0 0 0 * * *)
• 带年份格式：分 时 日 月 周 年 (如: 0 0 * * * 2023)
• 完整格式：秒 分 时 日 月 周 年 (如: 0 0 0 * * * 2023)

3. 丰富的调度功能

• 时间计算：精确计算下一个/上一个执行时间
• 时间序列：获取指定时间范围内的所有执行时间点
• 休眠计算：计算到下次执行的精确时间间隔
• 时间验证：验证时间点是否符合调度规则

4. 预定义调度模式

• 宏表达式：内置常用调度模式 (@hourly, @daily, @weekly 等)
• 快捷属性：提供 Hourly, Daily, Weekly 等静态属性
• 定制调度：支持 HourlyAt, DailyAt 等精确时间调度

5. 高级特性支持

• 随机执行：支持 R 字符实现随机时间调度
• 工作日处理：智能处理 W 字符和工作日计算
• 月末计算：准确处理 L 字符和月末日期计算
• 特殊星期：支持 # 字符实现"第几个星期几"调度

6. 开发者友好

• 简洁 API：直观易用的接口设计
• 完整文档：详细的使用说明和示例代码
• 强类型安全：充分利用 .NET 类型系统确保安全性
• 异常处理：提供清晰的错误信息和异常处理机制

7. 性能与质量

• 高性能：优化的算法确保快速的时间计算
• 低内存占用：高效的内存使用，无内存泄漏
• 零外部依赖：纯净的 .NET 实现，减少依赖冲突
• 全面测试：涵盖各种场景的单元测试确保质量
• 跨平台：支持 .NET 6+ 和多种操作系统

项目信息

• 包名称: Sparkdo.CrontabQ
• 描述: 一个功能全面、性能优异的 .NET Cron 表达式解析库
• 标签: cron, schedule, scheduling, cron-expression, sparkdo

特性

• 全面的 Cron 支持 - 支持标准 Cron 表达式的所有特性和语法
• 多种格式兼容 - 支持标准格式、带秒格式、带年份格式及组合格式
• 高性能计算 - 优化的算法确保快速的时间计算，即使在复杂表达式下也能保持优异性能
• 丰富的功能集 - 提供时间计算、序列生成、休眠时间计算等完整功能
• 宏表达式支持 - 内置常用调度模式，如每秒、每分钟、每小时等
• 随机执行支持 - 支持随机时间执行，满足特殊调度需求
• 零依赖设计 - 纯净的 .NET 实现，无第三方依赖，减少项目复杂性
• 跨平台兼容 - 支持多种 .NET 版本和操作系统平台
• 完善的错误处理 - 提供详细的异常信息和表达式验证机制
• 优秀的代码质量 - 经过全面的单元测试验证，确保稳定性和可靠性
• 易于集成 - 简洁的 API 设计，可轻松集成到任何 .NET 项目中

安装

Package Manager

Install-Package Sparkdo.CrontabQ

.NET CLI

dotnet add package Sparkdo.CrontabQ

快速入门

安装

Package Manager

Install-Package Sparkdo.CrontabQ

.NET CLI

dotnet add package Sparkdo.CrontabQ

PackageReference

<PackageReference Include="Sparkdo.CrontabQ" Version="1.0.0" />

基本使用

using Sparkdo.CrontabQ;

// 解析标准格式的 Cron 表达式（分 时 天 月 周）
var crontab = CrontabQ.Parse("0 9 * * *"); // 每天上午9点执行
var nextOccurrence = crontab.GetNextOccurrence(DateTime.Now);           // 下一个发生时间
var previousOccurrence = crontab.GetPreviousOccurrence(DateTime.Now);   // 上一个发生时间

Console.WriteLine($"下次执行时间: {nextOccurrence}");
Console.WriteLine($"上次执行时间: {previousOccurrence}");

支持的格式类型

Sparkdo.CrontabQ 支持四种不同的 Cron 表达式格式，以适应不同的调度需求：

1. 默认格式 (Default): 分 时 天 月 周

   var crontab = CrontabQ.Parse("0 0 * * *", CrontabFormat.Default); // 每天午夜执行
   

2. 带年份格式 (WithYears): 分 时 天 月 周 年

   var crontab = CrontabQ.Parse("0 0 * * * 2023", CrontabFormat.WithYears); // 2023年每天午夜执行
   

3. 带秒格式 (WithSeconds): 秒 分 时 天 月 周

   var crontab = CrontabQ.Parse("0 0 0 * * *", CrontabFormat.WithSeconds); // 每天0点0分0秒执行
   

4. 带秒和年格式 (WithSecondsAndYears): 秒 分 时 天 月 周 年

   var crontab = CrontabQ.Parse("0 0 0 * * * 2023", CrontabFormat.WithSecondsAndYears); // 2023年每天0点0分0秒执行
   

错误处理和验证

// 验证表达式是否有效
if (CrontabQ.IsValid("0 0 * * *"))
{
    Console.WriteLine("表达式有效");
}

// 安全解析表达式
if (CrontabQ.TryParse("0 0 * * *", out var crontab))
{
    var next = crontab.GetNextOccurrence(DateTime.Now);
    Console.WriteLine($"下次执行: {next}");
}
else
{
    Console.WriteLine("无效的 Cron 表达式");
}

// 异常处理
try
{
    var crontab = CrontabQ.Parse("invalid expression");
}
catch (CrontabException ex)
{
    Console.WriteLine($"解析错误: {ex.Message}");
}

核心功能

获取下一个执行时间

var crontab = CrontabQ.Parse("0 0 * * *", CrontabFormat.Default); // 每天午夜执行
var next = crontab.GetNextOccurrence(DateTime.Now);

获取上一个执行时间

var crontab = CrontabQ.Parse("0 0 * * *", CrontabFormat.Default); // 每天午夜执行
var previous = crontab.GetPreviousOccurrence(DateTime.Now);

获取时间序列

// 获取指定时间范围内的所有执行时间
var startTime = DateTime.Now;
var endTime = startTime.AddDays(1);
var occurrences = crontab.GetNextOccurrences(startTime, endTime);

// 获取指定时间范围内的所有上一个执行时间
var previousOccurrences = crontab.GetPreviousOccurrences(startTime, endTime);

休眠时间计算

// 获取距离下一个执行时间的毫秒数
var sleepMs = crontab.GetSleepMilliseconds(DateTime.Now);

// 获取距离下一个执行时间的时间间隔
var sleepTimeSpan = crontab.GetSleepTimeSpan(DateTime.Now);

宏表达式支持

预定义宏表达式

// 使用预定义的宏表达式
var secondly = CrontabQ.Secondly;    // 每秒 (* * * * * *)
var minutely = CrontabQ.Minutely;    // 每分钟 (* * * * *)
var hourly = CrontabQ.Hourly;        // 每小时 (0 * * * *)
var daily = CrontabQ.Daily;          // 每天 00:00:00 (0 0 * * *)
var monthly = CrontabQ.Monthly;      // 每月 1 号 00:00:00 (0 0 1 * *)
var weekly = CrontabQ.Weekly;        // 每周日 00:00:00 (0 0 * * 0)
var yearly = CrontabQ.Yearly;        // 每年 1 月 1 号 00:00:00 (0 0 1 1 *)
var workday = CrontabQ.Workday;      // 每周一至周五 00:00:00 (0 0 * * 1-5)

字符串宏表达式

// 使用字符串宏表达式
var secondly = CrontabQ.Parse("@secondly");    // 每秒
var minutely = CrontabQ.Parse("@minutely");    // 每分钟
var hourly = CrontabQ.Parse("@hourly");        // 每小时
var daily = CrontabQ.Parse("@daily");          // 每天 00:00:00
var monthly = CrontabQ.Parse("@monthly");      // 每月 1 号 00:00:00
var weekly = CrontabQ.Parse("@weekly");        // 每周日 00:00:00
var yearly = CrontabQ.Parse("@yearly");        // 每年 1 月 1 号 00:00:00
var workday = CrontabQ.Parse("@workday");      // 每周一至周五 00:00:00

Macro At 标识符

// 每第 3 秒
var crontab = CrontabQ.SecondlyAt(3);
// 每第 3，5，6 秒
var crontab = CrontabQ.SecondlyAt(3, 5, 6);

// 每分钟第 3 秒
var crontab = CrontabQ.MinutelyAt(3);
// 每分钟第 3，5，6 秒
var crontab = CrontabQ.MinutelyAt(3, 5, 6);

// 每小时第 3 分钟
var crontab = CrontabQ.HourlyAt(3);
// 每小时第 3，5，6 分钟
var crontab = CrontabQ.HourlyAt(3, 5, 6);

// 每天第 3 小时正（点）
var crontab = CrontabQ.DailyAt(3);
// 每天第 3，5，6 小时正（点）
var crontab = CrontabQ.DailyAt(3, 5, 6);

// 每月第 3 天零点正
var crontab = CrontabQ.MonthlyAt(3);
// 每月第 3，5，6 天零点正
var crontab = CrontabQ.MonthlyAt(3, 5, 6);

// 每周星期 3 零点正
var crontab = CrontabQ.WeeklyAt(3);
var crontab = CrontabQ.WeeklyAt("WED");  // SUN（星期天），MON，TUE，WED，THU，FRI，SAT
// 每周星期 3，5，6 零点正
var crontab = CrontabQ.WeeklyAt(3, 5, 6);
var crontab = CrontabQ.WeeklyAt("WED", "FRI", "SAT");
// 还支持混合
var crontab = CrontabQ.WeeklyAt(3, "FRI", 6);

// 每年第 3 月 1 日零点正
var crontab = CrontabQ.YearlyAt(3);
var crontab = CrontabQ.YearlyAt("MAR");  // JAN（一月），FEB，MAR，APR，MAY，JUN，JUL，AUG，SEP，OCT，NOV，DEC
// 每年第 3，5，6 月 1 日零点正
var crontab = CrontabQ.YearlyAt(3, 5, 6);
var crontab = CrontabQ.YearlyAt("MAR", "MAY", "JUN");
// 还支持混合
var crontab = CrontabQ.YearlyAt(3, "MAY", 6);

随机时刻支持

R 是一个特殊的 Cron 表达式字符，允许您指定随机生成的时刻。

// 每天 00:00 的随机秒数 (0-59) 时刻执行
var crontab = CrontabQ.Parse("R 0 0 * * ? *", CrontabFormat.WithSecondsAndYears);
var nextOccurrence = crontab.GetNextOccurrence(DateTime.Now);
// nextOccurrence.Second 将是 0-59 之间的随机值

实际应用示例

简单定时任务

// 阻塞方式
var crontab = CrontabQ.Parse("0 * * * * *", CrontabFormat.WithSeconds);
while(true)
{
    Thread.Sleep(crontab.GetSleepTimeSpan(DateTime.Now));
    Console.WriteLine($"任务执行: {DateTime.Now:G}");
}

// 无阻塞方式
var crontab = CrontabQ.Parse("0 * * * * *", CrontabFormat.WithSeconds);
Task.Factory.StartNew(async () =>
{
    while (true)
    {
        await Task.Delay(crontab.GetSleepTimeSpan(DateTime.Now));
        Console.WriteLine($"任务执行: {DateTime.Now:G}");
    }
}, TaskCreationOptions.LongRunning);

BackgroundService 实现定时任务

using Sparkdo.CrontabQ;

public class CronBackgroundService : BackgroundService
{
    private readonly ILogger<CronBackgroundService> _logger;
    private readonly ICrontabQ _crontab;

    public CronBackgroundService(ILogger<CronBackgroundService> logger)
    {
        _logger = logger;
        _crontab = CrontabQ.Parse("0 0 9 * * *", CrontabFormat.WithSeconds); // 每天上午9点执行
    }

    protected override async Task ExecuteAsync(CancellationToken stoppingToken)
    {
        while (!stoppingToken.IsCancellationRequested)
        {
            try
            {
                // 执行业务逻辑
                await DoWorkAsync();
                
                // 等待到下次执行时间
                var delay = _crontab.GetSleepTimeSpan(DateTime.Now);
                await Task.Delay(delay, stoppingToken);
            }
            catch (OperationCanceledException)
            {
                // 服务停止时的正常异常
                break;
            }
            catch (Exception ex)
            {
                _logger.LogError(ex, "执行定时任务时发生错误");
                await Task.Delay(TimeSpan.FromMinutes(1), stoppingToken); // 出错后等待1分钟再重试
            }
        }
    }

    private async Task DoWorkAsync()
    {
        _logger.LogInformation("执行定时任务: {Time}", DateTime.Now);
        // 在这里添加你的业务逻辑
        await Task.CompletedTask;
    }
}

任务调度器实现

using Sparkdo.CrontabQ;

public class TaskScheduler
{
    private readonly List<ScheduledTask> _tasks = new();

    public void AddTask(string name, string cronExpression, Func<Task> action)
    {
        var task = new ScheduledTask(name, cronExpression, action);
        _tasks.Add(task);
    }

    public async Task StartAsync(CancellationToken cancellationToken)
    {
        var tasks = _tasks.Select(task => Task.Run(() => RunTaskAsync(task, cancellationToken), cancellationToken));
        await Task.WhenAll(tasks);
    }

    private async Task RunTaskAsync(ScheduledTask task, CancellationToken cancellationToken)
    {
        while (!cancellationToken.IsCancellationRequested)
        {
            try
            {
                var delay = task.Cron.GetSleepTimeSpan(DateTime.Now);
                await Task.Delay(delay, cancellationToken);
                await task.Action();
            }
            catch (OperationCanceledException)
            {
                break;
            }
            catch (Exception ex)
            {
                Console.WriteLine($"任务 {task.Name} 执行出错: {ex.Message}");
            }
        }
    }
}

public class ScheduledTask
{
    public string Name { get; }
    public ICrontabQ Cron { get; }
    public Func<Task> Action { get; }

    public ScheduledTask(string name, string cronExpression, Func<Task> action)
    {
        Name = name;
        Cron = CrontabQ.Parse(cronExpression);
        Action = action;
    }
}

// 使用示例
var scheduler = new TaskScheduler();
scheduler.AddTask("数据备份", "0 0 2 * * *", async () => {
    Console.WriteLine("执行数据备份任务");
    await Task.Delay(1000); // 模拟备份操作
});

scheduler.AddTask("发送报告", "0 0 9 * * 1", async () => {
    Console.WriteLine("发送周报");
    await Task.Delay(1000); // 模拟发送操作
});

// 启动调度器
await scheduler.StartAsync(CancellationToken.None);

表达式语法

基本符号

字段说明

常用表达式示例

// 每分钟执行
"* * * * *"

// 每小时执行
"0 * * * *"

// 每天午夜执行
"0 0 * * *"

// 每周日午夜执行
"0 0 * * 0"

// 每月1号午夜执行
"0 0 1 * *"

// 每年1月1号午夜执行
"0 0 1 1 *"

// 每周一到周五午夜执行
"0 0 * * 1-5"

// 每5分钟执行
"*/5 * * * *"

// 每月第一个工作日执行
"0 0 1W * *"

// 每月最后一个工作日执行
"0 0 LW * *"

API 参考

Crontab 类

Crontab 类是 Sparkdo.CrontabQ 的核心入口点，提供了所有解析和创建 Cron 表达式的方法。

静态方法

• Parse(string expression, CrontabFormat format = CrontabFormat.Default): 解析 Cron 表达式并返回 ICrontabQ 实例。如果表达式无效，将抛出 CrontabException。

• TryParse(string expression, out ICrontabQ crontab, CrontabFormat format = CrontabFormat.Default): 尝试解析 Cron 表达式。如果解析成功返回 true 并输出 ICrontabQ 实例，否则返回 false。

• IsValid(string expression, CrontabFormat format = CrontabFormat.Default): 验证 Cron 表达式是否有效，不抛出异常。

预定义属性

• Secondly: 每秒执行的 Cron 表达式 (* * * * * *)
• Minutely: 每分钟执行的 Cron 表达式 (* * * * *)
• Hourly: 每小时执行的 Cron 表达式 (0 * * * *)
• Daily: 每天执行的 Cron 表达式 (0 0 * * *)
• Monthly: 每月执行的 Cron 表达式 (0 0 1 * *)
• Weekly: 每周执行的 Cron 表达式 (0 0 * * 0)
• Yearly: 每年执行的 Cron 表达式 (0 0 1 1 *)
• Workday: 每工作日执行的 Cron 表达式 (0 0 * * 1-5)

静态方法 (Macro At)

• SecondlyAt(params object[] fields): 创建指定特定秒开始的 Cron 表达式。例如：SecondlyAt(30) 表示每分钟第30秒执行。

• MinutelyAt(params object[] fields): 创建每分钟特定秒开始的 Cron 表达式。例如：MinutelyAt(30) 表示每分钟第30秒执行。

• HourlyAt(params object[] fields): 创建每小时特定分钟开始的 Cron 表达式。例如：HourlyAt(30) 表示每小时第30分钟执行。

• DailyAt(params object[] fields): 创建每天特定小时开始的 Cron 表达式。例如：DailyAt(9, 17) 表示每天上午9点和下午5点执行。

• MonthlyAt(params object[] fields): 创建每月特定天开始的 Cron 表达式。例如：MonthlyAt(1, 15) 表示每月1号和15号执行。

• WeeklyAt(params object[] fields): 创建每周特定星期几开始的 Cron 表达式。例如：WeeklyAt("MON", "FRI") 表示每周一和周五执行。

• YearlyAt(params object[] fields): 创建每年特定月1号开始的 Cron 表达式。例如：YearlyAt("JAN", "JUL") 表示每年1月和7月1号执行。

ICrontabQ 接口

ICrontabQ 接口定义了所有 Cron 表达式的核心功能。

时间计算方法

• GetNextOccurrence(DateTime baseTime): 获取起始时间下一个发生时间。从 baseTime 开始计算下一个匹配的时间点。

• GetNextOccurrence(DateTime baseTime, DateTime endTime): 获取特定时间范围下一个发生时间。计算在 endTime 之前下一个匹配的时间点。

• GetPreviousOccurrence(DateTime baseTime): 获取起始时间上一个发生时间。从 baseTime 开始计算上一个匹配的时间点。

• GetPreviousOccurrence(DateTime baseTime, DateTime endTime): 获取特定时间范围上一个发生时间。计算在 endTime 之后上一个匹配的时间点。

时间序列方法

• GetNextOccurrences(DateTime baseTime, DateTime endTime): 获取指定时间范围内的所有下一个发生时间。返回 baseTime 到 endTime 之间所有匹配的时间点。

• GetPreviousOccurrences(DateTime baseTime, DateTime endTime): 获取指定时间范围内的所有上一个发生时间。返回 endTime 到 baseTime 之间所有匹配的时间点。

休眠时间计算方法

• GetSleepMilliseconds(DateTime baseTime): 计算距离下一个发生时间相差的毫秒数。用于实现精确的延迟执行。

• GetSleepTimeSpan(DateTime baseTime): 计算距离下一个发生时间的时间间隔。返回 TimeSpan 对象，便于使用 Task.Delay 等方法。

其他方法

• ToString(): 将 Cron 表达式转换为字符串表示形式。可用于序列化或日志记录。

枚举类型

CrontabFormat

定义了支持的 Cron 表达式格式：

• Default: 默认格式（分 时 日 月 周）
• WithYears: 带年份格式（分 时 日 月 周 年）
• WithSeconds: 带秒格式（秒 分 时 日 月 周）
• WithSecondsAndYears: 带秒和年格式（秒 分 时 日 月 周 年）

CrontabFieldKind

定义了 Cron 表达式的字段类型：

• Second: 秒字段
• Minute: 分钟字段
• Hour: 小时字段
• Day: 日期字段
• Month: 月份字段
• DayOfWeek: 星期字段
• Year: 年份字段

错误处理

项目定义了 CrontabException 类来处理解析和计算过程中可能出现的异常情况：

try
{
    var crontab = CrontabQ.Parse("invalid expression");
}
catch (CrontabException ex)
{
    Console.WriteLine($"解析 Cron 表达式时出错: {ex.Message}");
}

测试

项目包含全面的单元测试，覆盖了各种表达式类型和边界情况，确保库的稳定性和正确性。

[Fact]
public void TestGetNextOccurrences()
{
    var beginTime = new DateTime(2022, 1, 1, 0, 0, 0);
    var endTime = new DateTime(2022, 1, 1, 1, 0, 0);
    var cron = CrontabQ.Parse("*/15 * * * *", CrontabFormat.Default); // Every 15 minutes
    var occurrences = cron.GetNextOccurrences(beginTime, endTime).ToList();

    Assert.Equal(3, occurrences.Count); // 00:15, 00:30, 00:45
    Assert.Equal("2022-01-01 00:15:00", occurrences[0].ToString("yyyy-MM-dd HH:mm:ss"));
    Assert.Equal("2022-01-01 00:30:00", occurrences[1].ToString("yyyy-MM-dd HH:mm:ss"));
    Assert.Equal("2022-01-01 00:45:00", occurrences[2].ToString("yyyy-MM-dd HH:mm:ss"));
}