Coolify 中的 Laravel 集合最佳实践：高阶消息、游标迭代与批量操作的落地方法

本文基于 Coolify 仓库内置的 Laravel 最佳实践技能规则文档（.agents/skills/laravel-best-practices/rules/collections.md），系统讲解 Laravel Collection 的五个核心技巧：高阶消息（Higher-Order Messages）、cursor() 与 lazy() 的选型、lazyById() 的安全迭代、toQuery() 批量操作以及 #[CollectedBy] 自定义集合类，并结合 Coolify 源码中的真实用法逐条印证，帮助你在大型 Laravel 项目（如 PaaS 平台）中写出更简洁、内存更省、迭代更安全的集合代码。

背景：集合规则在 Coolify 技能体系中的位置

Coolify 仓库在 .agents/skills/laravel-best-practices/SKILL.md 中内置了一套面向 AI Agent 的 Laravel 最佳实践技能，其中第 17 节“Collections”明确引用 rules/collections.md，将其定位为“影响优先排序”（prioritized by impact）的实践之一。该技能同时强调一条元原则——Consistency First（一致性优先）：应用这些规则前，先检查代码库已有的模式，保持一致比追求理论最优更重要。以下规则正是这条原则下的默认选择：当代码库尚无既定模式时，按这些规则来写。

一、简单操作用高阶消息（Higher-Order Messages）

规则内容

当你对集合中每个元素执行的是一个简单方法调用时，无需写闭包，直接用 ->each->method() 形式的高阶消息：

错误写法：

$users->each(function (User $user) {
    $user->markAsVip();
});

正确写法：

$users->each->markAsVip();

高阶消息同样适用于 map、sum、filter、reject、contains 等方法，例如 $users->filter->isVip()、$items->sum->price()。

Coolify 源码印证

Coolify 源码中已经按此模式使用高阶消息。服务启动动作 中批量重置重启计数：

$service->applications()->get()->each->resetRestartLimit();
$service->databases()->get()->each->resetRestartLimit();

部署控制器 中对部署日志批量可见性处理：

$deployments['deployments']->each->makeVisible(['logs']);

两处都是典型的“对每个元素调用一个无参数方法”场景，高阶消息让意图一目了然，也避免了闭包的样板代码。

适用边界：高阶消息适合单个方法调用；一旦需要多个语句、访问索引或捕获上下文变量（use），仍应回到闭包写法。

二、cursor() 与 lazy() 的选型

规则内容

两者都是内存友好的大规模数据迭代手段，但机制不同：

• cursor() —— 每次只在内存中持有一个模型，基于 PDO 游标逐行拉取；但它不能预加载关联（eager loading 会被静默忽略）。
• lazy() —— 基于分块分页（chunked pagination）返回扁平的 LazyCollection，支持预加载关联。

关键陷阱：

// 错误：预加载被静默忽略，存在 N+1 风险
User::with('roles')->cursor()

// 正确：需要访问关联时用 lazy()
User::with('roles')->lazy()

// 正确：只读取模型自身属性时用 cursor()
User::cursor()

Coolify 源码印证

SSL 证书重发定时任务 是一个典型的 cursor() 用法场景：

$query = SslCertificate::query();
// ... 按 server_id、有效期过滤 ...
$query->where('is_ca_certificate', false);

$regenerated = collect();

$query->cursor()->each(function ($certificate) use ($regenerated) {
    // 通过 $certificate->server 懒加载关联后签发证书
    $caCert = $certificate->server->sslCertificates()
        ->where('is_ca_certificate', true)
        ->first();
    // ...
    SSLHelper::generateSslCertificate(/* ... */);
});

注意这里的选择逻辑：任务需要访问 $certificate->server 关联，但作者选择逐条懒加载（每个证书查一次 CA），而不是改用 lazy()->with(...) 预加载——从源码结构看，这是因为后续要调用 SSLHelper 执行远程 SSH 签发操作，瓶颈在外部 IO 而非查询次数，且 cursor() 的“同一时刻一个模型”特性进一步压缩了内存占用。这正是规则所强调的权衡：cursor() 用于只读、内存最敏感的场景，lazy() 用于需要批量关联预加载的场景。

此外，标签迁移 中对全表数据的逐行处理也使用了 cursor()，说明在一次性迁移场景中这是团队既定的低内存模式（Consistency First 原则的体现）。

三、迭代中更新记录时使用 lazyById()

规则内容

lazy() 使用偏移量分页（LIMIT/OFFSET 式推进）。如果你在迭代过程中更新、删除正在遍历的记录，偏移量会错位，导致记录被跳过或重复处理。

lazyById() 改用 id > last_id 作为游标条件推进，天然免疫迭代中的数据变更，是“边迭代边写”场景的安全选择。

Coolify 源码印证

Coolify 中最能体现这条规则的是卡住资源清理命令：

$teams = Team::query()
    ->whereDoesntHave('members')
    ->whereDoesntHave('servers')
    ->lazyById();
foreach ($teams as $team) {
    $team->delete();   // 迭代中删除记录
}

$servers = Server::onlyTrashed()->lazyById();
foreach ($servers as $server) {
    $server->forceDelete();   // 迭代中硬删除
}

该命令遍历大量资源并在循环体内直接 delete() / forceDelete()。若换成 lazy()，删除操作会改变后续行的偏移量，部分记录可能被漏删或重复删除——lazyById() 的 id > last_id 推进方式保证了每条记录恰好被处理一次。

同一命令中还有一处带关联预加载的 lazyById() 用法（第 48 行）：Server::query()->with('team.subscription')->lazyById()->filter(...)，说明 lazyById() 同样支持 with() 预加载（分块 + id 游标的组合），这弥补了 cursor() 的短板。

Coolify 云端命令也沿用了显式指定分块大小的写法，如用户导出命令 的 ->lazyById(500) 和清理未验证用户命令 的 ->lazyById(100)——通过第一个参数控制每块行数，可按内存预算精细调节。

四、toQuery() 用于集合的批量操作

规则内容

当你已经持有一个集合（而不是从模型查询开始），又需要对其执行批量更新时，避免手动 whereIn('id', $collection->pluck('id')) 构造，直接：

错误写法：

User::whereIn('id', $users->pluck('id'))->update([...]);

正确写法：

$users->toQuery()->update([...]);

toQuery() 会从集合底层的查询约束（对 Eloquent 集合而言即主键集合）重建一个 Query Builder，语义等价但省去手动 pluck 与 whereIn，且不需要重复指定模型类。

适用说明

从源码结构看，Coolify 当前 app/ 目录下尚未出现 toQuery() 的既有用法，因此这条规则对该仓库而言属于“待采用的默认模式”：当你在 Coolify 中拿到一个 Collection/EloquentCollection 需要批量 update 或 delete 时，优先按此规则书写，与技能文档保持一致。

五、#[CollectedBy] 声明式自定义集合类

规则内容

为模型指定自定义集合类（Custom Collection Class）时，属性更声明式、也更符合框架演进方向：

#[CollectedBy(UserCollection::class)]
class User extends Model {}

相比旧式做法——在模型中覆写 newCollection() 方法——注解写法是单行声明，意图清晰。

适用说明

从源码结构看，Coolify 的 User 模型 等模型目前均未覆写 newCollection()，也未使用 #[CollectedBy]，即仓库现状以框架默认集合为主。这意味着：如果你确实需要为某个模型定制集合行为（如默认的 map 返回类型、序列化钩子），按本规则使用 #[CollectedBy] 注解即可，无需先例可循；但若无此需求，遵循 Consistency First 原则，不要引入自定义集合。

小结：选型速查

场景	推荐手段	Coolify 参照
对每个元素调用单个方法	高阶消息 each->、map->、sum-> 等	StartService.php
全量只读遍历、内存最敏感、不碰关联	cursor()	RegenerateSslCertJob.php
需要预加载关联的大数据遍历	lazy()->with(...) / lazyById()->with(...)	CleanupStuckedResources.php
迭代中更新/删除记录	lazyById()（可带分块大小）	CleanupStuckedResources.php、ExportUsers.php
已有集合需批量 update/delete	toQuery()	规则默认模式
为模型绑定自定义集合类	#[CollectedBy]	规则默认模式

五条规则的共同指向是：用 Laravel 集合 API 的语义化入口（高阶消息、游标、查询重建、声明式注解）替代手动样板代码，在保持可读性的同时控制内存与并发安全。落地时请遵循技能文档的 Consistency First 元原则——先看仓库既有模式，规则用于填补空白，而非推翻现状。