PHP SplPriorityQueue 相同优先级元素顺序怎么控制

不能直接控制。PHP 官方手册明确说明：SplPriorityQueue 中优先级相同的元素，其顺序是未定义的，可能与插入顺序不同。要让同级元素稳定地先入先出，不能依赖堆当前碰巧呈现的顺序，而要把“插入先后”变成第二排序键：使用“业务优先级 + 递增序号”的复合优先级，并重写 compare()。

官方手册地址：https://www.php.net/manual/en/class.splpriorityqueue.php

下面只解决一个问题：高优先级任务仍然先执行，而相同业务优先级的任务按 FIFO，也就是先插入的先出队。

问题原文：为什么同优先级任务没有按插入顺序出来

假设任务 A、B、C 都使用优先级 10，随后插入一个优先级 20 的紧急任务 D。我们通常希望结果是 D、A、B、C：先处理更高优先级，再保持同级 FIFO。

insert('A', 10);
$queue->insert('B', 10);
$queue->insert('C', 10);

// D 的优先级更高，应该最先出队
$queue->insert('D', 20);

while (!$queue->isEmpty()) {
    echo $queue->extract(), PHP_EOL;
}

D 在 A、B、C 之前是有保证的，但 A、B、C 的相对顺序没有保证。某次运行看起来像 FIFO，不代表换一个 PHP 版本、调整插入数据或改变堆结构后仍然如此。SplPriorityQueue 基于最大堆实现，堆只维护父节点不小于子节点的性质，不维护同级元素的插入历史。

先给结论：让每个入队元素拥有唯一的复合优先级

稳定排序需要一个全序关系。单独的业务优先级只能区分“10 大于 5”，却无法区分“第一个 10”和“第二个 10”。因此给每个元素增加递增序号：

• 第一排序键：业务优先级，数值越大越先出队；
• 第二排序键：插入序号，数值越小表示越早插入，越先出队。

例如 A、B、C 分别得到 [10, 0]、[10, 1]、[10, 2]。D 得到 [20, 3]。比较时先看第一项；第一项相同，再让较小的序号获得更高堆优先级。

常见误区：看到一次有序，不代表有顺序保证

误区一：同级元素自然会 FIFO

不会。PHP 手册对相同优先级使用的是“顺序未定义”，这意味着业务代码不应依赖任何具体顺序。测试数据少时偶然稳定，通常只是堆当前形态的副作用。

误区二：重写 compare()，相等时返回 0 就能保序

compare() 返回 0 只表示两个优先级相等，并没有告诉堆哪一个应该先出。要保序，必须让同级任务在比较器眼中不再完全相等，也就是提供第二键。

误区三：把任务名称作为第二键

任务名称只能得到字典序，不是插入顺序。A、B、C 可能碰巧符合预期，但换成订单号、UUID 或中文名称后，结果会变成另一种业务语义。第二键应明确表达你真正需要的规则。

正确做法：把同级规则编码进复合优先级

下面的子类不覆盖 insert()，而是提供 enqueue()。这样可以避免不同 PHP 版本中内部方法返回类型声明变化带来的兼容性干扰，也能提醒调用方必须经过稳定入队入口。

 $priority,
            'sequence' => $this->sequence++,
        ]);
    }

    public function compare(mixed $priority1, mixed $priority2): int
    {
        // 先比较业务优先级：数值越大，越靠近最大堆顶部
        $businessOrder = $priority1['priority']  $priority2['priority'];
        if ($businessOrder !== 0) {
            return $businessOrder;
        }

        // 同级时反向比较序号：较小序号代表更早插入，应获得更高顺位
        return $priority2['sequence']  $priority1['sequence'];
    }
}

$queue = new StablePriorityQueue();

// 只提取任务数据，避免把内部复合优先级暴露给业务层
$queue->setExtractFlags(SplPriorityQueue::EXTR_DATA);

$queue->enqueue('A', 10);
$queue->enqueue('B', 10);
$queue->enqueue('C', 10);
$queue->enqueue('D', 20);

while (!$queue->isEmpty()) {
    echo $queue->extract(), PHP_EOL;
}

结果关系稳定为：

D
A
B
C

compare() 的返回约定是：正数表示第一个优先级更大，0 表示相等，负数表示更小。代码中的第二次比较故意写成 $priority2['sequence'] $priority1['sequence']。如果顺序写反，较晚插入的序号更大，反而会变成同级 LIFO。

边界情况：稳定顺序之外还要注意什么

提取优先级时会看到内部数组

默认提取模式是 EXTR_DATA，业务层只拿到任务值。如果改成 EXTR_BOTH，返回的 priority 会是内部复合数组，而不再是单个数字。需要给外部展示原始业务优先级时，可以把它同时保存在任务数据中，或者在封装类中提供专门的 DTO。

所有业务优先级应使用一致类型

示例把业务优先级限制为 int|float，避免数字、字符串、数组混合比较。生产代码还应拒绝 NAN 等不能形成稳定全序的浮点值。优先级来自外部输入时，先校验范围再入队。

序号只在一个队列实例内有意义

这个方案保证单进程、单队列实例内的稳定顺序。如果多个进程分别创建队列，或任务经过消息队列分片，局部序号不能自动形成全局 FIFO。那时应使用数据库自增 ID、消息偏移量或由统一入口分配的全局序列。

长生命周期服务要考虑序号增长

普通请求或批处理很难触及整数上限，但常驻服务可能长期运行。可以在队列清空后把序号安全重置为 0；不要在队列尚有元素时重置，否则新旧任务可能得到相同复合优先级。

遍历和提取都会改变队列

优先队列适合消费，不适合当作可反复浏览的列表。需要调试或预览顺序时，应对队列副本操作；真正消费时使用 extract()，并把“出队即处理”写成明确流程。

什么时候不要继续改 SplPriorityQueue

如果优先级种类很少，例如只有高、中、低三级，并且每一级都严格 FIFO，那么“三个普通队列 + 从最高非空队列取值”可能比复合堆更直观。它把规则直接表达为三个桶，调试也更容易。

如果项目允许安装 PECL ds 扩展，Ds\PriorityQueue 的官方文档说明相同优先级会保留 FIFO。不过这会增加扩展依赖，而且迭代同样具有消费语义。已有 SPL 环境、希望零额外扩展时，复合优先级方案通常更合适。

延伸问题

如何让相同优先级后插入的先出？

把第二键比较方向改为 $priority1['sequence'] $priority2['sequence']，较大的新序号会拥有更高顺位，这就是同级 LIFO。

如何改成数字越小优先级越高？

反转第一键的比较方向即可，但第二键仍按目标规则独立处理。不要简单把整个比较结果乘以 -1，否则同级 FIFO 也会一起被反转。

能不能直接用时间戳当第二键？

不推荐把普通秒级时间戳当唯一第二键，因为同一秒可插入多个任务。高精度时间仍可能遇到碰撞或时钟回拨。单实例内的递增整数更简单，也更容易推理。

为什么 compare() 已经重写，仍然出现同级乱序？

检查所有入队调用是否都经过 enqueue()。只要有代码直接调用继承来的 insert() 并传入单个数字，比较器就会收到不同结构的优先级，稳定规则会被破坏。生产封装可以用组合而不是继承，彻底隐藏原始队列对象。