PHP 8.5 NoDiscard 如何提示调用方接收返回值

PHP 8.5 的 #[\NoDiscard] 适合标记“返回结果不应被悄悄丢掉”的函数或方法。调用方直接写一行函数调用而不使用返回值时，PHP 会发出警告；需要忽略时可以用 (void) 明确表达这是有意为之。它解决的是调用约定容易被忘记的问题，不会替你判断业务结果，也不会把所有函数都变成必须接收返回值。

把 NoDiscard 放在真正需要检查结果的声明上，再让调用方选择消费、判断或显式忽略返回值。这样静态结构表达了意图，运行时也能尽早暴露遗漏。

先判断：哪些返回值值得被强制关注

验证结果、解析结果、写入状态和批量处理报告，通常不能只靠副作用判断成功。例如解析器可能返回对象或 null，保存函数可能返回布尔值，批处理函数还可能把每条失败原因放在数组里。调用方完全忽略它们，错误就会在更远的位置才出现。

相反，纯粹记录日志、刷新缓存这类主要依赖副作用的函数，不一定适合加上该属性。NoDiscard 更像 API 的契约：它告诉调用者“这个返回值代表了一项需要做决定的信息”，而不是一条通用编码规范。

在声明上添加 NoDiscard，并保留可读的提示

属性可以不带消息，也可以给出一条解释。消息应说明为什么不能丢掉结果，避免把它写成模糊的“请注意”。下面的返回值表示批量处理可能逐项失败，因此调用者需要接住结果：

如果直接写 processBatch($items);，PHP 8.5 会提示返回值应该被使用或被明确忽略。这个提醒的价值在于把“忘了处理”从代码审查时的猜测，提前变成调用现场的可见信号。

调用方有三种清晰选择：接收、判断或显式忽略

收到提示后，不要机械地把返回值塞进临时变量。先看业务是否需要它：要继续处理就赋值，要做门禁就直接放入条件表达式，要确实忽略才显式转换为 void。

(void) 不会把结果转换成另一个可继续使用的值，它只是清楚地标注“这里不需要结果”。项目还要支持 PHP 8.4 或更早版本时，属性本身可以保留但旧版本不会发出提示；而 (void) 语法不适用于旧版本，可使用一个约定好的临时变量承接返回值。

继承边界决定了提示是否真的出现

NoDiscard 绑定的是实际被调用的函数或方法声明。把属性写在接口方法或抽象方法上，并不能保证实现方法调用时出现警告；覆盖父类方法也要在子类声明上重新标记。trait 方法是一个容易忽略的例外：方法被复制到使用它的类中，会保留 trait 上的属性。

因此，迁移旧 API 时要把检查重点放在“运行时最终调用的声明”上。只给接口补属性、却不检查实现类，会让团队以为契约已经生效，实际却没有得到提示。

常见问题

NoDiscard 会让函数调用失败吗？

它的作用是发出警告，不是替调用方抛出业务异常。是否把警告升级、记录或拦截，仍由项目的错误处理策略决定。

能不能给所有有返回值的函数都加上？

不建议。只有丢失结果很可能代表缺陷时才加，否则调用现场会充满无意义的提示，真正重要的遗漏反而容易被忽略。

PHP 8.4 能识别这个属性吗？

属性语法可以被旧版本读取，但 PHP 8.4 及以下不会执行 NoDiscard 的提醒逻辑。需要兼容旧版本时，保留属性可用于平滑迁移，同时用临时变量表达有意忽略。

参考：PHP NoDiscard 手册；PHP 8.5 发布说明；PHP void 类型与显式丢弃返回值。