PHP 8.4 #[\SensitiveParameter] 怎么保护日志里的敏感参数：异常追踪与调试边界

登录接口偶发 500 时，最先被翻出来的通常是异常回溯；如果回溯把 $password 或 $accessToken 一起带出来，排查问题就变成了新的泄露点。PHP 8.4 提供的 #[\\SensitiveParameter] 可以把这些参数标记为敏感值，让调试信息避开原始内容，但它只负责异常参数展示，不会替你加密数据库或清理所有业务日志。

把属性加在真正可能出现在回溯里的函数参数上，再用一次故障演练确认日志只剩占位信息；不要把它当成完整的凭据管理方案。

先复现一次：异常回溯为什么会碰到密码

假设一个简化的登录流程由 LoginController::login 调用 AuthService::verify，校验失败时服务抛出异常。开发环境为了方便，把异常对象写进调试日志；这时函数参数可能沿着回溯链被展示出来。

verify('alice', 'demo-password');

问题不在于 PHP 把密码主动写进业务日志，而在于开发者选择了带参数上下文的异常展示方式。先确认泄露点，再决定标记哪些参数，范围会比给每个方法都加属性更清楚。

把敏感标记放在参数边界

#[\\SensitiveParameter] 是参数属性，应该直接放在需要保护的形参前。用户名通常用于定位请求，可以保留；密码、刷新令牌或一次性验证码则应标记。下面的调用关系与上一段一致，变化只发生在参数声明。

verify('alice', 'demo-password');
} catch (Throwable $error) {
    error_log((string) $error);
}

发生异常时，回溯仍然指出 AuthService::verify 和调用位置，但敏感参数不会以原始字符串继续传播。上线前可以在隔离环境故意触发一次异常，检查日志中没有 demo-password 这类测试值。

它保护的是回溯展示，不是所有输出

这里最容易产生误会：如果代码先执行 error_log($password)，属性不会拦截这次主动输出；如果把请求体序列化后写入审计表，也不会因为函数参数被标记而自动脱敏。属性的有效边界是参数在错误回溯和相关调试展示中的表示方式。

日志策略要和参数属性配套

登录失败日志可以记录用户标识、失败原因和请求关联 ID，但不要把原始请求体、Authorization 头或完整异常上下文无条件写入长期日志。对结构化日志，敏感字段应在进入 logger 之前就被替换；对第三方异常采集器，也要检查它是否会自行读取请求上下文。

用三个检查点验收

1. 看函数声明：确认密码、令牌等值标在真实的参数边界，而不是只标记了调用方的局部变量。
2. 看异常回溯：在隔离环境触发 RuntimeException，保留方法名和行号，同时搜索日志中是否仍有原始敏感值。
3. 看旁路输出：检查 error_log、请求体记录、调试工具和异常采集器是否各自有脱敏规则。

这三个检查点分别覆盖参数声明、回溯展示和旁路日志。只通过前两项，并不能说明生产日志已经安全。

常见问题：什么时候不该依赖这个属性

数据库里的密码需要加这个属性吗？

不需要把数据库字段理解成属性的作用对象。密码应该使用适合验证的哈希方案保存，属性只解决运行时调试信息里的参数展示问题。

给整个类加属性可以吗？

这个属性的使用位置是参数声明。更稳妥的做法是逐个标记真正敏感的形参，并在异常演练中核对效果。

为什么日志里还是能看到令牌？

常见原因是令牌在另一个未标记的函数参数中出现，或代码、HTTP 中间件、日志处理器主动记录了请求头。沿着 LoginController::login、AuthService::verify 和日志处理器逐段检查，不要只看属性是否存在。

收束：保留排查线索，也切断敏感值

#[\\SensitiveParameter] 的价值在于缩小异常调试信息的暴露面：方法名、调用位置和错误原因仍可用于定位，密码与令牌则不应跟着回溯传播。真正上线前，把它和结构化日志字段白名单、异常采集脱敏、隔离环境故障演练放在同一份检查表里。