PHP 8.5 NoDiscard 属性减少返回值误用的配置方法

PHP 8.5 的 #[\NoDiscard] 属性适合解决一种很隐蔽的返回值误用：函数已经返回了失败信息、校验结果或处理结果，但调用方像调用无返回值命令一样直接丢掉它。把属性写在函数或具体方法声明上后，PHP 会在返回值没有被使用时发出 warning；调用方如果确实想忽略结果，可以用 (void) 明确表达这个决定。

官方地址：https://www.php.net/manual/en/class.nodiscard.php

我更愿意把它看成一条 API 契约，而不是一个“打开检查”的全局配置。本文只讨论 PHP 8.5 中 NoDiscard 的声明位置、调用方式和边界，不把它扩展成完整的静态分析或框架规范。

模式命名：把“返回值必须被消费”写进 API 契约

很多业务函数的返回值不是装饰：保存操作可能返回失败原因，校验函数可能返回错误集合，批处理函数可能返回逐项结果。问题在于，PHP 传统调用允许下面这种写法自然通过：

这段代码不一定错，甚至可能是有意忽略。但如果 process_orders() 的返回值承载了失败信息，遗漏消费就会让问题延迟到更远的地方。PHP 8.5 的 #[\NoDiscard] 通过声明把这种风险前置到调用点：函数或方法的作者先说明“结果重要”，调用方再决定使用、保存，或者显式忽略。

适用压力：哪些返回值值得被强制关注

这个模式有价值的前提，是“忘记处理返回值”确实比“多看到一条 warning”更危险。下面几类结果通常值得优先考虑：

• 返回失败原因、校验错误或需要重试的状态，而函数本身没有抛出异常。
• 返回经过过滤、规范化或授权判断后的新对象，忽略它会继续使用旧对象。
• 返回批处理的逐项结果，调用方必须决定哪些项目成功、哪些项目失败。
• 返回资源句柄、事务结果或需要后续清理的对象，丢弃结果会隐藏生命周期责任。

反过来，纯粹为了链式调用、日志输出或兼容旧接口而返回的值，不一定适合强制消费。NoDiscard 不是“所有非 void 函数都应标注”的规则；它应当对应一个具体后果。

典型实现：在函数或具体方法声明上添加属性

NoDiscard 不是 php.ini 中的开关，而是 PHP 代码里的预定义属性。它的目标位置是函数和方法声明，并且可以传入一段说明文字，让 warning 直接告诉调用方为什么不能随手丢弃结果。

 $order) {
        // 这里用布尔字段模拟业务处理结果，真实项目可替换为领域结果对象。
        $results[$orderId] = ['ok' => (bool) $order['ready']];
    }

    return $results;
}

// 直接丢弃返回值时，PHP 8.5 会提示应使用结果或明确忽略。
process_orders([
    'A-100' => ['ready' => true],
]);

// 读取结果就满足“返回值被使用”的契约。
$result = process_orders([
    'B-200' => ['ready' => false],
]);
if (!$result['B-200']['ok']) {
    echo "需要人工处理", PHP_EOL;
}

关键点是属性写在声明上，而不是调用点。对于方法，写法相同：

 0, 'accepted' => 12];
    }
}

$report = new ImportReport();
$summary = $report->build();
echo $summary['accepted'], PHP_EOL;

NoDiscard 的价值在于把作者的意图留在 API 边界上。调用方不需要记住一份额外的团队约定，只要看到属性，就知道这个结果至少应该被检查、保存或有意忽略。

反例：把 warning 当成“必须使用”的绝对命令

最常见的反例是清理型或通知型方法：调用方知道结果不影响当前流程，但函数仍然返回一个状态对象。若给它加上 NoDiscard，所有合法的“只执行动作”调用都会产生噪声，真正重要的 warning 反而容易被淹没。

另一个反例是把多个独立动作包装成一个返回数组，再用 NoDiscard 强迫所有调用方读取整份数组。这样的 API 可能是在掩盖职责过多；与其给调用方增加警告，不如先拆分命令和查询，或让失败通过异常、结果对象等更清晰的方式表达。

因此，标注前可以先问一句：如果调用方完全不知道这个返回值，最坏后果是什么？如果答案只是“少了一条统计信息”，NoDiscard 的收益有限；如果答案是“错误被当成成功继续提交”，这个模式就很合适。

明确忽略：用 (void) 表达调用方的决定

PHP 8.5 提供了与 NoDiscard 配套的 (void) 转换。它不是为了消除警告而隐藏问题，而是把“我看到了这个契约，但在这里有意不消费结果”写成可读代码。

如果项目还要运行在 PHP 8.4 或更早版本，属性本身可以被添加而不产生同样的检查，但旧版本不支持用 (void) 来表达这个意图。官方手册给出的兼容思路是使用临时变量，例如 $_ = refresh_index();。这是一种兼容写法，不代表旧版本会发出 NoDiscard warning。

后果边界：接口、抽象方法和 Trait 不能混为一谈

NoDiscard 的 warning 归属于实际被调用的声明。只把属性写在接口方法或抽象方法上，并不会自动让实现方法的调用产生 warning；实现类需要在真正被调用的具体方法上再次声明。覆写父类的同名方法也一样，子类方法没有单独标注时，不会因为父类曾经标注就自动继承这个检查。

Trait 是一个容易漏掉的例外：Trait 中的方法被导入类后，会像写在使用类中一样保留属性。因此，团队在抽取 Trait 方法时，应把它当作具体方法声明的一部分来评估，不要只看类的接口关系。

 1, 'accepted' => 11];
    }
}

final class CleanupTools
{
    // Trait 导入后，方法上的属性会随方法进入使用类。
    use HasImportantResult;
}

trait HasImportantResult
{
    #[\NoDiscard]
    public function result(): string
    {
        // 这个返回值只是演示 Trait 方法的声明边界。
        return 'ready';
    }
}

这类边界说明了一个重要后果：NoDiscard 不替代接口设计，也不替代静态分析。它只在 PHP 运行时把一条局部契约变成 warning，最终仍需要由团队决定哪些 warning 进入日志、测试或发布门禁。

判断清单：什么时候值得在项目里采用

可以按下面的顺序评估一组函数或方法：

1. 返回值是否携带失败、授权、校验、资源或逐项处理结果？如果没有，先不要标注。
2. 忽略返回值时，是否会让调用方继续执行错误流程？如果会，NoDiscard 的收益更明确。
3. 调用方是否存在合理的“有意忽略”场景？如果存在，要约定 (void) 或兼容旧版本的临时变量写法。
4. 属性是否写在实际调用到的函数或具体方法声明上？接口、抽象方法、覆写方法和 Trait 要分别判断。
5. warning 的文字是否能解释为什么必须关注结果？短消息比抽象的“请使用返回值”更有帮助。

小结

PHP 8.5 的 #[\NoDiscard] 适合把“这个返回值不能被无意丢掉”写进函数或具体方法声明。它的模式边界很清楚：重要结果使用属性约束，确实不需要时用 (void) 明确表达；接口、抽象方法和覆写关系不能替代具体实现上的声明，而 Trait 导入的方法会保留属性。把它放在有明确后果的 API 上，才能减少误用而不制造新的 warning 噪声。

相关问题：

• PHP 8.5 NoDiscard 为什么要写在具体实现方法上？
• PHP 8.4 项目能不能提前写 #[\NoDiscard] 属性？
• PHP 8.5 中怎样明确表示有意忽略函数返回值？