PHP match 表达式怎样覆盖枚举分支并保持穷尽

PHP 枚举配合 match 保持穷尽，最直接的写法是：用枚举 case 本身作为 subject，显式列出所有 case，不写静默 default，并用 Enum::cases() 遍历测试覆盖每个分支。以后新增 case 却忘记更新映射时，代码会抛出 UnhandledMatchError，而不是悄悄落入一个看似合理的兜底值。

官方文档：https://www.php.net/manual/en/control-structures.match.php

先明确：match 的“穷尽”是什么意思

match 与 switch 有三个关键差异：它用严格身份比较 ===，每个分支返回一个值，而且不会发生 case 穿透。更重要的是，match 必须有结果；当 subject 没有命中任何分支且不存在 default 时，PHP 会抛出 UnhandledMatchError。

对枚举来说，这个特性非常合适。枚举 case 是该枚举类型的单例对象，match($state) 可以直接和 OrderState::Paid 等 case 做身份匹配，不必先取 ->value 再比较字符串。类型边界越靠前，后面的业务分支越不容易混入拼写错误或未知值。

候选方案怎么选

如果标题问的是“怎样保持穷尽”，默认答案应是无 default 的 match。default 并不是错误语法，但它表达的是“其余值可以统一处理”，这和“每个枚举 case 都必须做明确决策”是两种不同需求。

推荐方案：枚举方法内使用无 default 的 match

把与枚举自身强相关的显示标签、终态判断或动作分类放进 enum 方法，可以减少多个调用方各自维护一份 match。分支返回类型由方法签名约束，新增 case 时也只需要在枚举文件附近修改。

 '待支付',
            self::Paid => '已支付',
            self::Shipped => '已发货',
            self::Cancelled => '已取消',
        };
    }

    public function isTerminal(): bool
    {
        // 语义相同的 case 可以放在同一个 match arm 中。
        return match ($this) {
            self::Shipped, self::Cancelled => true,
            self::Pending, self::Paid => false,
        };
    }
}

这里匹配的是 $this，也就是具体 case 对象。若以后加入 case Refunded = 'refunded';，却没有更新 label()，调用 OrderState::Refunded->label() 时会抛出 UnhandledMatchError。这个失败是有价值的：它说明领域模型发生了变化，而映射决策尚未完成。

外部函数与 enum 方法如何取舍

不是所有 match 都应该塞进 enum。与枚举天然相关、几乎所有调用方都认可的行为，例如稳定标签、终态判断、领域权限，可以放在 enum 方法里。与某个展示层、地区或渠道相关的映射，放在独立函数或映射器中更合适。

 'badge-warning',
        OrderState::Paid => 'badge-info',
        OrderState::Shipped => 'badge-success',
        OrderState::Cancelled => 'badge-muted',
    };
}

外部函数同样可以保持穷尽，只要参数类型是 enum，且 match 不写 default。选择关键不是“代码放在哪里更短”，而是这个映射由谁拥有：领域规则归 enum 或领域服务，页面颜色归展示层。

为什么不推荐 default 返回“未知”

枚举是封闭集合。正常情况下，类型为 OrderState 的变量只能是已声明 case，不存在任意未知对象。因此在领域内部写 default => '未知'，往往不是在处理脏数据，而是在掩盖未来新增 case 的遗漏。

 '待支付',
        OrderState::Paid => '已支付',
        default => '未知',
    };
}

如果业务确实要求未知输入返回统一结果，应把容错放到“标量转 enum”的边界，而不是放在已经类型安全的 enum 映射里。这样领域代码仍保持封闭和完整，外部数据错误也有清晰出口。

Backed Enum：先 tryFrom，再做穷尽匹配

字符串来自 HTTP、消息队列或数据库时，先用 Backed Enum 的 tryFrom() 转换。它在找不到 case 时返回 null；from() 则会抛出 ValueError。不可信输入通常适合 tryFrom，并由边界层生成明确的校验错误。

get('state'));

// 进入领域内部后只处理合法 case，label() 可以保持无 default。
$response = [
    'state' => $state->value,
    'label' => $state->label(),
];

不要直接对 $raw 使用一个带 default 的字符串 match 来替代 enum 转换。那会把输入校验、类型转换和领域映射混成一层，后续很难区分“客户端传了非法值”和“开发者漏写了新 case”。

用 cases() 在测试阶段暴露遗漏

PHP 运行时可以通过 UnhandledMatchError 发现遗漏，但更理想的是让测试先覆盖每一个 case。所有枚举都实现 UnitEnum，其 cases() 会按声明顺序返回全部 case。测试遍历这份列表并调用目标方法，新 case 会自动进入测试。

label(), $case->name);
        }
    }

    public function testTerminalStatesStayExplicit(): void
    {
        $expected = [
            OrderState::Shipped,
            OrderState::Cancelled,
        ];

        foreach (OrderState::cases() as $case) {
            // 除了覆盖分支，还断言业务不变量，避免返回值写反。
            self::assertSame(
                in_array($case, $expected, true),
                $case->isTerminal(),
                $case->name
            );
        }
    }
}

第一组测试检查“每个 case 都能返回标签”，第二组测试检查“返回结果是否符合业务定义”。仅仅不抛异常还不够，错误的分支值同样需要断言。项目若使用静态分析工具，可以再启用 enum match 相关规则，把反馈提前到开发阶段。

数组映射什么时候更合适

映射由配置生成、需要合并翻译文件，或业务人员可以调整时，数组可能比 match 更方便。但数组不会天然证明键集合等于 enum case 集合。此时应从 cases() 生成期望键集合，与实际配置键排序后比较；缺键和多余键都应报错。

纯代码常量、分支数量不多且必须完整时，match 更清楚；映射属于数据、需要动态加载时，数组更自然。不要为了“少写几行”把一个封闭领域判断变成弱类型字符串表。

决策表

相关问题

match 加 default 还算穷尽吗？

语法上有结果，但领域上不一定完整。default 覆盖“所有剩余值”，无法证明开发者对每个 enum case 做了显式决定。

PHP 会在编译时提示少写了枚举 case 吗？

PHP 语言本身主要在运行时通过 UnhandledMatchError 暴露未命中。需要在提交前发现时，应加 cases() 测试或静态分析。

应该 match 枚举对象还是 value 字符串？

领域内部优先 match 枚举对象，保留类型与严格身份语义。只有序列化、存储或协议边界才需要使用 value。

多个 case 返回同一个值会破坏穷尽吗？

不会。PHP 允许同一 arm 左侧写多个表达式；只要所有 case 都出现在某个 arm 中，仍然是显式覆盖。

参考资料

• PHP match：https://www.php.net/manual/en/control-structures.match.php
• PHP 枚举方法：https://www.php.net/manual/en/language.enumerations.methods.php
• PHP 枚举 cases()：https://www.php.net/manual/en/language.enumerations.listing.php
• PHP Backed Enum：https://www.php.net/manual/en/language.enumerations.backed.php