PHP enum 怎样用 match 覆盖未知分支

同一个文档状态枚举被列表文案、详情展示和导出模式共同引用时，新增一个 case 就会增加多处映射的维护负担。本文把问题限定在“枚举已经扩展，但某个 match 还没覆盖新增项”：展示层可以明确降级，业务层则应明确拒绝或补齐分支。default 不是自动兼容所有新业务含义的开关。

环境：PHP 8.1 或更新版本。官方 match 说明地址：https://www.php.net/manual/en/control-structures.match.php；枚举基础说明：https://www.php.net/manual/en/language.enumerations.basics.php。

共享枚举扩展后，真正增加的是映射维护面

设想文档服务原来只有 DocumentPhase::Draft 和 DocumentPhase::Ready，后来加入 DocumentPhase::Archived。枚举定义已经包含 Archived，列表仍只翻译前两项，导出模块也仍只认识前两种模式。此处的“未知”指消费者没有适配的合法 case，而不是 enum 可以凭空容纳一个任意字符串。

当消费者从一个扩展到多个时，分散的 match 容易各自添加不同兜底：有的把 Archived 当草稿，有的当可导出，还有的直接报错。这里不需要声称存在海量请求或性能瓶颈；维护瓶颈就是同一状态的含义散落在多个映射里，新增项无法被统一讨论。

先分清严格比较与未覆盖分支

match 采用严格比较。对枚举对象进行匹配时，分支应写 DocumentPhase::Draft 这样的枚举项；不要用 'Draft' 字符串冒充同一个对象。case 的 name 是名称，不等于这个 case 本身。即使是 backed enum，case 对象也不等于它的 value 标量。

没有 default 的 match 并不会仅因遗漏某个 enum case 就在声明时拒绝代码。只有它实际求值、且找不到匹配分支时，才会抛出 UnhandledMatchError。这意味着“旧函数还能加载”不能证明“所有新状态都能处理”。default 表示其他分支未匹配时采用的表达式，同一个 match 只能有一个 default。

边界上的外部非法值是另一个问题：带枚举参数类型的函数不接受任意字符串作为枚举对象。backed enum 的 tryFrom 对不存在的合法标量值返回 null；输入转换应单独处理，不要期待函数内部的 match default 接住类型不成立的调用。转换方法参考：https://www.php.net/manual/en/language.enumerations.backed.php。

把展示降级与业务拒绝分成两个集中映射

可以先把多个页面重复的文案判断收敛到 displayLabel，让它对未适配项返回“待适配状态”。这是中性展示，不把未知状态标成“已完成”或“可导出”。展示文案不承诺业务能力，调用方也不能通过比较文案来推断导出许可。

导出模式则统一放在 exportMode：明确支持 Draft 的 preview 和 Ready 的 final，其他项抛出带 case 名称的 LogicException。这个函数只决定模式，没有执行导出。调用方必须把拒绝作为失败处理，而不是 catch 后继续按 final 导出。相比不写 default，自定义拒绝能表达当前业务尚未适配这一层含义；相比宽松默认值，它不会悄悄给新状态分配旧行为。

这也不是无限堆积 default 的理由。若 Archived 的产品含义已确定，就为它新增显式分支。若所有 case 本来都必须支持，保留无 default 的完整显式映射并在维护时逐项检查也很合理。PHP 的运行时异常与团队的完整性检查是两件事，不应把 default 宣称为编译期穷尽保障。

完整示例：同一个新增项体现三种策略

下面代码可保存为独立 PHP 文件。它使用纯枚举，避免把输入反序列化问题混入 match 分支讨论。代码展示集中映射和旧映射的不同语义，不代表本文已在本地执行或取得线上验证结果。

 '草稿',
        DocumentPhase::Ready => '可查看',
        default => '待适配状态',
    };
}

// 严格业务映射拒绝未明确支持的枚举项。
function exportMode(DocumentPhase $phase): string
{
    return match ($phase) {
        DocumentPhase::Draft => 'preview',
        DocumentPhase::Ready => 'final',
        default => throw new LogicException('未适配枚举项：' . $phase->name),
    };
}

// 旧映射没有 default；遗漏分支只在实际求值时暴露。
function oldLabel(DocumentPhase $phase): string
{
    return match ($phase) {
        DocumentPhase::Draft => '草稿',
        DocumentPhase::Ready => '可查看',
    };
}

// 本例只是逐项展示策略，不会执行文档导出。
foreach (DocumentPhase::cases() as $phase) {
    echo $phase->name . ' / ' . displayLabel($phase) . PHP_EOL;
    try {
        echo '导出模式：' . exportMode($phase) . PHP_EOL;
    } catch (LogicException $error) {
        echo '业务拒绝：' . $error->getMessage() . PHP_EOL;
    }
    try {
        echo '旧文案：' . oldLabel($phase) . PHP_EOL;
    } catch (UnhandledMatchError $error) {
        echo '旧映射遗漏：' . $phase->name . PHP_EOL;
    }
}

按代码语义，Draft 与 Ready 都有明确文案和导出模式；Archived 在 displayLabel 中得到待适配文案，在 exportMode 中触发业务拒绝，在 oldLabel 中触发 UnhandledMatchError。示例的 catch 用于展示差异，不是要求业务代码吞掉所有异常。尤其不要用 catch(Throwable) 后返回成功来隐藏遗漏。

若新增项也应支持导出，应明确修改 exportMode 的 match，并为它确定真正的模式；若它只允许查看，则保留业务拒绝并给展示函数补上明确文案。两个函数可共用枚举，但无需拥有相同的允许集合。

上线关注契约信号，不把兜底当成适配完成

这里给出的是上线后的观察清单，而不是已完成的上线结果：页面出现“待适配状态”时记录对应 case 名称和映射位置；出现“未适配枚举项”时确认调用方停止该操作并返回可理解的失败；出现 UnhandledMatchError 时定位仍未集中或没有覆盖的旧映射。记录必要的状态名即可，不要附带完整用户文档内容。

后续每次修改枚举，都把涉及的 displayLabel、exportMode 和剩余旧映射列入同一次变更讨论。DocumentPhase::cases() 可以提供合法项清单，供维护者检查覆盖情况，但遍历清单本身不证明每个业务行为正确。若未来消费者越来越多，再按展示、导出等契约边界集中映射；不要为了一个三项枚举先引入庞大的注册框架。

结论是两层取舍：展示兜底解决“如何呈现未适配项”，严格业务映射解决“是否已经支持该行为”。新增合法 case 应当被显式纳入讨论，外部非法值则留在输入边界处理。default 可兜住未覆盖分支，但不会替团队决定新枚举项的业务含义。