PHP 8.5 NoDiscard防止忽略返回值

如果一个 PHP 函数返回的是校验结果、错误集合或事务状态，调用方却把返回值直接丢掉，问题往往不会在代码审查时立刻暴露。PHP 8.5 提供的 #[\NoDiscard] 属性，正好可以把这类 API 意图写进声明：返回值没有被使用时，运行时会给出警告；确实要忽略时，则需要显式表达。

官方资料：https://www.php.net/manual/en/class.nodiscard.php

本文只聚焦一个边界：如何标记返回值重要的函数或方法，以及调用方怎样在“误忘记处理”和“有意忽略”之间做出清楚区分。

#[\NoDiscard] 到底约束什么

#[\NoDiscard] 标记的是函数或方法的返回值，而不是函数内部的某个局部变量。PHP 8.5 会关注调用表达式的结果有没有被消费：赋值、作为参数传递、参与判断或返回给上层，都属于使用；单独调用后什么也不做，则会触发警告。

因此它更像 API 契约，而不是新的返回值类型。函数仍然可以返回字符串、数组、对象或标量，属性只是在提醒调用方：这个结果通常有业务含义，不应该被悄悄扔掉。

给返回值重要的函数加上属性

最小写法是在函数或方法前加上全局命名空间下的属性。属性可以带一段说明文字，帮助调用者理解为什么这个结果不能随便忽略。

 0]);
if ($errors !== []) {
    // 中文注释说明这里处理了 NoDiscard 返回值。
    print_r($errors);
}
?>

这里的重点不是“有属性就必须赋值给变量”，而是调用结果要参与后续语义。比如把 validateOrder() 作为 if 条件、传给日志函数，或者交给另一个函数处理，也都属于消费返回值。

为什么单独调用会被提醒

下面这种写法没有使用校验结果，调用方看起来像是忘记了处理错误：

 0;
}

// PHP 8.5 会针对未消费的返回值发出警告。
syncInventory(1001);
?>

警告的价值在于把“可能遗漏的业务判断”暴露出来，但它不会替你决定失败后应该重试、记录日志还是回滚事务。属性解决的是提醒和契约表达，业务策略仍然要由调用方编写。

确定要忽略时，用 (void) 写清楚意图

有些函数同时承担副作用并返回状态。例如记录审计日志时，当前调用点可能只关心“发起记录”这个动作，不需要立即处理返回对象。PHP 8.5 可以用 (void) 明确告诉读者和运行时：这里是有意忽略。

(void) 只表达“结果在这里不需要”，不会吞掉函数内部已经发生的异常，也不会把失败自动变成成功。若这个调用涉及关键写入，仍应根据业务决定是否记录失败或向上抛出异常。

需要兼容 PHP 8.4 及更早版本怎么办

PHP 手册说明，属性语法可以放在支持 PHP 8.4 及更早版本的代码中；旧版本不会执行 NoDiscard 的检查。但旧版本不支持 PHP 8.5 新增的 (void) 丢弃写法，因此跨版本库可以用一个约定的临时变量表达意图。

如果项目只支持 PHP 8.5 及以上，优先使用 (void)，它的意图更直接。如果同一套库需要覆盖旧版本，保留属性并使用临时变量会更稳妥；同时在文档或编码规范中统一这个约定，避免有人误以为 $_ 是漏写的业务变量。

哪些返回值不适合标记 NoDiscard

不要把属性当成“所有函数都必须检查”的强制规则。以下情况需要谨慎：

• 返回值只是为了提供可选统计信息，而调用方经常只需要副作用；
• 函数名已经清楚表明它主要执行动作，返回值没有稳定的业务含义；
• 调用方数量很多且无法统一升级，贸然增加属性会让大量旧调用出现警告；
• 返回值的处理方式依赖上下文，库作者无法判断丢弃是否真的危险。

更合适的选择通常是：只给“忽略结果很可能代表 bug”的函数和方法加属性，例如校验、授权、持久化、同步、资源获取或返回错误集合的 API。

升级到 PHP 8.5 时的检查清单

常见问题

NoDiscard 会改变函数的返回值吗？

不会。它不改变返回类型和返回内容，只在调用方完全不消费结果时提醒。

把结果传给另一个函数算不算使用？

算。只要返回值进入赋值、参数、条件、表达式或上层返回等后续语义，就不是静默丢弃。

PHP 8.4 会因为 NoDiscard 属性直接报错吗？

按 PHP 手册的说明，属性可以保留在兼容旧版本的代码中，旧版本不会执行这项检查；但具体项目仍应按自己的最低版本和部署方式做兼容评估。

只想忽略警告，是否应该关闭所有警告？

不建议。优先在调用点用 (void) 或临时变量表达真实意图，这样不会把其他真正遗漏的返回值问题一起隐藏。