PHP 8.5 的 #[NoDiscard] 如何落地：返回值误用、(void) 豁免与升级检查

线上导入任务已经返回失败，日志却显示“校验通过”。追了一圈，问题不在校验函数，而在调用方把它当成普通副作用函数调用了：返回值没有接住，也没有任何提示。PHP 8.5 的 #[\NoDiscard] 正好针对这类遗漏——当一个被标记的函数返回值没有被使用时，运行时会发出警告；如果调用方确实有意忽略结果，可以用 (void) 把这个决定写出来。

一个被吞掉的校验结果，为什么会拖到上线后才暴露

假设订单导入前要检查 CSV 行里的商品编码。旧代码把检查写成了一个很普通的函数：

function checkSku(string $sku): bool
{
    return preg_match('/^[A-Z]{3}-[0-9]{6}$/', $sku) === 1;
}

checkSku($row['sku']);

最后一行没有语法错误，测试里也可能没有明显异常。它真正的问题是：调用者没有表达“这个布尔结果不重要”，也没有表达“结果必须参与后续判断”。如果校验函数后来改成记录失败原因、返回更丰富的状态，遗漏就更难被代码审查发现。

PHP 8.5 的发布说明把 #[\NoDiscard] 定义为一种 API 安全提示。它不会替你修正业务逻辑，也不会强制每个函数都接收返回值，但能把“看起来像忘了处理”的调用点暴露出来。

先给关键函数加属性，再观察哪些调用点真的有风险

属性放在函数声明前即可：

#[\NoDiscard]
function checkSku(string $sku): bool
{
    return preg_match('/^[A-Z]{3}-[0-9]{6}$/', $sku) === 1;
}

$valid = checkSku($row['sku']);
if (!$valid) {
    throw new InvalidArgumentException('商品编码格式不正确');
}

这段改动的价值不在于代码变短，而在于函数契约更清楚：调用者要么保存结果，要么明确写出为什么不保存。对已有项目，建议先从边界明显的函数开始，例如 validateImportRow()、canPublish()、parseAccessToken()。日志函数、缓存写入函数和纯副作用通知函数通常不适合直接加上这个属性。

返回值该怎么接：保存、参与判断，或者明确豁免

实际迁移时，调用点大致会落到三类。

第三类不要为了消除警告而写一个无意义变量。(void) 是一个小但重要的信号：它把“我已经看过这个返回值，但这里就是不使用”的决定留在代码里。以后函数返回类型变化或调用场景变化时，审查者能很快定位这些有意豁免点。

#[\NoDiscard]
function refreshSearchIndex(int $productId): bool
{
    // 更新索引，并返回是否成功
    return true;
}

// 业务上必须知道是否成功
if (!refreshSearchIndex($productId)) {
    throw new RuntimeException('搜索索引刷新失败');
}

#[\NoDiscard]
function writeAuditLog(string $event): bool
{
    return true;
}

// 这里确认只关心写入动作
(void) writeAuditLog('product-imported');

升级到 PHP 8.5 时，别把警告当成全量改写任务

PHP 官方迁移指南明确提醒，8.5 虽然是小版本，也包含需要在生产切换前测试的不兼容变化。#[\NoDiscard] 本身不要求你给所有旧函数加属性，真正需要控制的是改动范围：先挑高风险返回值，再在调用链上补验证。

可以在一个临时分支里准备最小实验：

error_reporting(E_ALL);

#[\NoDiscard]
function buildImportPlan(array $rows): array
{
    return array_values(array_filter($rows));
}

buildImportPlan($rows); // 观察 PHP 8.5 的未使用返回值警告
(void) buildImportPlan($rows); // 明确豁免，确认告警消失

检查时记录三件事：警告是否能在测试日志里看到、静默调用点是否真的只关心副作用、补上返回值后是否改变了异常路径。这里别急着把每一个提示都压掉；如果函数名里有 check、parse、build、can，却没有任何结果接收代码，通常值得回到业务路径重新看一遍。

三个容易误判的边界

只要是 bool 返回值，都应该加吗？

不是。属性描述的是“调用者通常不应忘记处理返回值”，而不是返回类型。一个返回布尔值的埋点函数可能只代表写入是否成功，业务也许已经接受丢失埋点；反过来，一个返回对象的解析函数同样可能必须被消费。看调用契约，不看类型表面。

用变量接住再不使用，算不算解决？

这只是把提示从调用点挪到局部变量，不能证明业务已经处理了结果。更好的写法是让变量进入判断、日志或返回值；真的不需要时使用 (void)，让意图可见。

PHP 8.4 能先写这个属性吗？

不要把 8.5 的新属性直接当作跨版本代码的默认写法。需要同时支持旧运行时的项目，应先在兼容分支中确认属性解析、构建镜像和静态检查工具的行为，再决定是否用版本分支、条件声明或延后迁移。最终以项目支持矩阵和 PHP 官方迁移指南为准。

一份适合提交前执行的升级检查

1. 列出所有“返回结果代表业务判断”的函数，优先覆盖校验、解析、权限和状态构建。
2. 为每个高风险调用点补上变量、条件、异常或日志，不要只改函数声明。
3. 对确实只触发副作用的调用使用 (void)，并在代码评审里说明原因。
4. 在 PHP 8.5 测试环境运行导入、发布、权限变更等关键流程，检查新增警告和异常路径。
5. 确认生产镜像版本、依赖锁文件和回滚镜像都能被明确识别，再安排灰度。

#[\NoDiscard] 的价值，是把一个经常靠经验提醒的问题变成可观察的调用契约。它适合从少数关键 API 开始使用，配合真实的测试结果推进，而不是为了“零警告”给每个返回值都套上一层规则。

相关问题

属性会自动阻止程序继续运行吗？

它的定位是提示和警告，不是替代业务异常。是否中断、记录还是继续，仍由项目的错误处理配置和调用逻辑决定。

(void) 应该写在所有被忽略的返回值前吗？

只对明确有意忽略且已经确认副作用可接受的调用使用。对于校验、解析、权限判断等结果型函数，优先补上判断。

升级前最值得先测哪一类代码？

先测批量导入、发布审批、权限校验和支付回调这类“返回值决定下一步”的路径，再处理低风险的日志和通知调用。