在许多业务系统如电商订单处理、SaaS 订阅管理或工单流转系统中，我们经常会遇到一种特殊的时间范围查询需求：截止时间并不是直接存储在数据库表中的一个固定字段，而是需要通过表中的某个初始时间字段加上另一个字段代表的有效天数动态计算得出。例如，订单表中存储了订单创建时间和该订单的有效支付天数，我们需要查询出所有已经超过支付期限的未支付订单。面对这种需求，如果将数据全部取出再在应用层用 PHP 进行过滤，当数据量达到百万级别时，不仅会导致严重的内存溢出问题，还会造成极大的网络和计算开销。正确的做法是将时间计算逻辑下沉到数据库层面，让数据库引擎在扫描数据时就完成过滤。
一、理解需求：为什么需要动态计算时间范围
要理解动态计算时间范围的重要性，我们首先需要明确静态时间范围查询与动态时间范围查询的本质区别。在常规的查询场景中，比如查询最近七天内创建的订单，我们通常会在应用层使用 PHP 的 Carbon 库计算出七天前的具体日期，然后将这个具体的日期字符串作为参数传递给 Laravel 的查询构造器。这种情况下，查询条件是静态的，对于每一行数据而言都是一样的。数据库引擎可以利用时间字段上的索引快速定位数据，执行效率极高。
然而，在动态计算场景下，每一行数据的过期时间都不一样。以一个包含 created_at（创建时间）和 valid_hours（有效小时数）字段的订单表为例，某条记录的过期时间等于 created_at 加上 valid_hours 小时。如果我们要查询当前时间已经超过该过期时间的记录，由于每条记录的 valid_hours 可能不同，我们无法在应用层给出一个统一的时间边界。如果强行在应用层处理，意味着必须将整个表中可能过期的数据全部拉取到 PHP 进程中，再通过循环逐条比对时间。这种做法在数据量稍大时就会引发严重的性能瓶颈，不仅数据库 I/O 负载剧增，PHP 进程也会因为处理大量对象而耗尽内存。因此，我们必须寻找一种让数据库在执行查询时动态计算每行过期时间的方法。
二、使用 whereRaw 与 DATE_ADD 实现日期偏移
在 Laravel 框架中，当我们需要使用数据库原生函数来处理复杂的查询逻辑时，whereRaw 方法是最直接的途径。以 MySQL 数据库为例，我们可以利用其内置的 DATE_ADD 函数或者 DATE_ADD 的语法糖 INTERVAL 来实现日期的动态偏移。通过这种方式，我们可以直接在 SQL 语句中表达出“创建时间加上有效天数小于当前时间”的逻辑，让数据库引擎在遍历数据时对每一行进行计算和比对。
下面是一个具体的代码示例，展示了如何在 Laravel 查询构造器中使用 whereRaw 来实现动态时间范围过滤。假设我们需要查询所有已经过期的未支付订单，过期时间由 created_at 字段加上 valid_days 字段的值决定：
// 查询已过期的未支付订单
$expiredOrders = Order::where('status', 'unpaid')
->whereRaw('DATE_ADD(created_at, INTERVAL valid_days DAY) < NOW()')
->get();
// 也可以使用另一种 MySQL 语法糖
$expiredOrders = Order::where('status', 'unpaid')
->whereRaw('created_at + INTERVAL valid_days DAY < NOW()')
->get();
这种方式的优点非常明显：代码简洁，执行效率高。数据库引擎会直接在底层进行计算，只有满足条件的数据才会被发送到应用层，极大地减少了数据传输量和内存占用。但是，这种做法也存在一定的局限性。首先，whereRaw 里面写死了特定数据库的 SQL 方言函数，如果项目未来需要切换到 PostgreSQL 或 SQLite 等其他数据库，这段代码将会直接报错，可移植性较差。其次，在 whereRaw 中使用字段名时，必须确保字段名是安全的，不能由用户输入直接拼接，否则会引发 SQL 注入风险。在上述例子中，valid_days 是固定的表字段名，不存在注入风险，但如果字段名是动态变量，则必须通过白名单校验。
三、利用查询作用域封装动态时间查询
为了提高代码的可复用性和可维护性，避免在多个控制器或服务类中重复编写冗长的原生 SQL 语句，我们可以利用 Laravel Eloquent 提供的查询作用域功能。查询作用域允许我们将常用的查询约束封装成方法，从而在全局范围内复用。通过封装，我们不仅可以使业务代码更加清晰易读，还能集中管理动态时间计算的逻辑，降低维护成本。
我们可以在 Order 模型中定义一个名为 expired 的本地作用域。在这个作用域内部，我们依然使用 whereRaw 来执行数据库层面的时间计算，但对外暴露的则是一个优雅的 PHP 方法。这样一来，业务层的调用者不需要关心底层 SQL 是如何拼接的，只需要知道调用这个方法就能获取过期订单即可。
class Order extends Model
{
// 定义本地查询作用域
public function scopeExpired($query)
{
// 使用 MySQL 的 DATE_ADD 函数动态计算过期时间
return $query->whereRaw('DATE_ADD(created_at, INTERVAL valid_days DAY) < NOW()');
}
// 如果需要更灵活地控制时间基准，可以传入参数
public function scopeExpiredBefore($query, $dateTime = null)
{
$dateTime = $dateTime ?: now();
// 注意：如果传入外部时间，应该使用绑定参数的方式防止注入
return $query->whereRaw('DATE_ADD(created_at, INTERVAL valid_days DAY) < ?', [$dateTime]);
}
}
封装好作用域之后，我们在控制器或服务层中的调用代码就会变得极其清爽。例如，我们要查询所有过期的未支付订单，只需链式调用 expired 方法即可。如果业务逻辑发生变化，比如过期时间的计算规则从天数变成了小时数，或者增加了节假日排除逻辑，我们只需要修改模型中的 scopeExpired 方法即可，所有调用了该作用域的地方都会自动生效，极大地提高了代码的可维护性。同时，通过参数绑定的方式，我们也能有效防范 SQL 注入攻击，保障系统安全。
四、跨数据库兼容性与性能优化建议
虽然使用 whereRaw 配合 DATE_ADD 能够解决动态时间计算的问题，但在实际企业级项目中，我们往往需要考虑更多的架构因素，尤其是跨数据库兼容性和查询性能优化。从兼容性角度来看，不同数据库对日期加减函数的支持各不相同。PostgreSQL 使用 created_at + (valid_days || ' days')::interval 的语法，而 SQLite 则使用 datetime(created_at, '+' || valid_days || ' days')。如果项目有切换数据库的需求，直接写死原生 SQL 显然是不合理的。针对这种情况，一种折中方案是编写自定义的数据库语法扩展，或者尽量在业务设计阶段规避这种动态计算需求，通过增加一个冗余的 expire_at 字段来存储计算后的过期时间。
从性能优化的角度来看，在 WHERE 条件中对字段使用函数或表达式计算，会导致数据库无法直接使用该字段上的普通索引，从而可能引发全表扫描。当表数据量非常大时，查询性能依然会成为一个痛点。为了解决这个问题，最推荐的做法是采用“空间换时间”的策略。在插入或更新订单数据时，通过模型的模型事件（如 creating 或 saving 事件），在应用层提前计算好过期时间，并将其持久化存储到 expire_at 字段中。
class Order extends Model
{
protected static function booted()
{
static::creating(function ($order) {
// 在创建订单时，提前计算并设置过期时间字段
if ($order->created_at && $order->valid_days) {
$order->expire_at = Carbon::parse($order->created_at)->addDays($order->valid_days);
}
});
}
}
通过上述模型事件的处理，每条记录在写入数据库时就已经拥有了一个明确的 expire_at 字段。这样，当我们需要查询过期订单时，查询条件就变成了简单的 where('expire_at', '<', now())。这种查询可以直接利用 expire_at 字段上的索引，查询速度能够得到质的飞跃。虽然这增加了一个字段的存储开销，但在现代关系型数据库中，这点空间开销相比于带来的性能提升而言是完全值得的。综上所述，在 Laravel 中处理动态时间范围查询时，应根据实际数据量和性能要求，在原生 SQL 计算和冗余字段预计算之间做出合理选择。