PHP JSON 日志脱敏怎么避免破坏结构：嵌套字段、异常值与审计保留

线上接口已经把密码字段替换成星号，值班同事却发现同一条日志的 JSON 结构偶尔变成了字符串，后面的检索和审计都失去了字段层级。PHP 日志脱敏真正难的地方，不是写一个 str_replace()，而是在写出日志前复制数据、按字段递归处理、明确无效 UTF-8 的策略，并保证脱敏后的结果仍然是可解析的 JSON。

稳定的做法是“结构化数据脱敏后再编码”：敏感字段按键名命中，嵌套数组递归处理，编码失败直接留下可定位的错误，不用截断字符串或拼接半截 JSON。

先把“脱敏成功”定义成可检查的结果

不少开发者写脱敏逻辑的时候，只会简单校验日志里有没有密码明文，这么做很容易漏过三类常见问题：嵌套对象里的敏感字段没处理、数组第二个及之后的元素漏处理、JSON编码失败后直接把错误详情拼进日志流。逻辑上线之前，至少要同时验证三个核心点：

• 所有敏感键的明文内容完全消失，对应的键名和其余非敏感字段的原有结构完全没有被破坏。
• 输出能够再次被 json_decode() 解析，数组和对象的边界没有被打平。
• 命中哪些规则、跳过哪些值、编码是否成功，都能在不泄露原文的前提下追踪。

用递归复制处理嵌套 JSON

脱敏函数入参直接接收 PHP 数组或标量类型，处理完返回一份全新的复制值。这么做完全不会改动业务后续还要复用的请求对象，不会引入意料之外的副作用。匹配规则的时候统一把键名转小写做对比，但最终输出的结果里保留原始键名，大家查日志的时候直接沿用接口文档里的字段名就能检索，不用额外做映射。

 $item) {
            $keyName = strtolower((string) $key);
            $nextPath = $path . '.' . $key;
            if (in_array($keyName, $secretKeys, true)) {
                $result[$key] = '[REDACTED]';
                continue;
            }
            $result[$key] = redactForLog($item, $secretKeys, $nextPath);
        }
        return $result;
    }

    return $value;
}

$secretKeys = ['password', 'access_token', 'refresh_token', 'id_card'];
$safePayload = redactForLog($payload, $secretKeys);

这里的 $path 暂时没有写入结果，但保留下来很有用：当审计需要记录命中位置时，可以单独收集 $.user.access_token 这样的路径，记录路径而不是记录秘密值。生产代码还应对递归深度和循环引用设上限，避免异常对象拖垮日志链路。

编码边界决定日志能不能继续检索

PHP 的 json_encode() 要求字符串使用 UTF-8。来自旧系统、文件名或外部回调的数据可能带有无效字节；如果沿用默认返回值，调用方很容易把 false 当成空日志。更明确的写法是让编码异常显式暴露，并在边界处给出不含原文的降级记录。

try {
    $json = json_encode(
        $safePayload,
        JSON_UNESCAPED_UNICODE | JSON_UNESCAPED_SLASHES | JSON_THROW_ON_ERROR
    );
} catch (JsonException $error) {
    $json = json_encode([
        'log_status' => 'serialization_failed',
        'error_type' => get_class($error),
    ], JSON_UNESCAPED_UNICODE | JSON_THROW_ON_ERROR);
}

如果业务明确允许替代无效字节，可以选择 JSON_INVALID_UTF8_SUBSTITUTE，但要把这个选择写进日志契约：替代字符意味着原字段已不再是原始文本，不能在审计中假装它可逆。不要把 JSON_PARTIAL_OUTPUT_ON_ERROR 当作默认修复方案，它可能留下不完整的结果。

异常值、空值和数组是最容易漏测的三块

脱敏规则不能只拿一份平整数组测试。真实请求通常同时包含对象、列表、空值和历史格式字段。下面这组输入能覆盖大多数首轮回归：

$payload = [
    'user' => [
        'email' => 'a@example.test',
        'access_token' => 'secret-a',
    ],
    'items' => [
        ['id' => 7, 'password' => 'secret-b'],
        ['id' => 8, 'password' => null],
    ],
    'note' => null,
];

断言重点不是整段字符串相等，而是重新解码后检查路径和值：

• user.access_token 与两个 items.*.password 都是占位符。
• user.email、items.*.id 和 note 的类型保持不变。
• 原始数组中的秘密值不因日志处理被修改，也不出现在异常消息中。

把审计信息留在“可验证但不可泄露”的范围

审计需要知道规则是否生效，但不需要知道密码是什么。建议保存事件时间、请求类型、脱敏规则版本、命中路径数量和序列化状态；敏感路径可做稳定哈希或只保留字段名，具体取决于是否需要跨请求聚合。不要把原始 payload 放到异常上下文、调试日志或重试消息里。

当规则升级时，给规则加版本号并保留一组固定样本。新版本必须证明旧字段仍被覆盖，同时明确新增字段的默认行为：未知字段不应因为“暂时没列入名单”就自动打印完整值。

上线前常见问题：用四个问题收口

脱敏函数要不要修改原数组？

非常不推荐这么做。返回全新的处理后结构，能最大程度避免日志处理逻辑意外影响业务主流程；如果遇到超大体积的待处理数据，也应该提前把拷贝的性能成本纳入压测范围，不要为了省点内存直接原地修改原始数据。

无效 UTF-8 应该忽略还是替换？

两种处理方式都没有绝对适用的场景。直接忽略当前字段会丢失字段结构，直接替换成默认值又会改动原始结构的形态。处理审计类敏感字段的时候，优先让流程标记失败并记录字段类型就好，只有面向用户展示的、允许做降级处理的字段，才考虑用掩码替换内容。

只按字段名匹配够不够？

只靠键名匹配肯定不够稳妥。同一个字段名在不同接口里可能代表完全不同的含义，规则还应结合数据路径、接口来源和字段类型多维度判断。对银行卡号、手机号等模式型数据，可增加专门的值匹配策略。

怎样证明日志里没有秘密？

测试的时候准备好包含嵌套对象、列表、空值、非法编码字节的全量样本，脱敏处理完之后先把结果重新解码成数组，再对路径上的敏感值做断言校验；同时要扫一遍序列化失败分支的所有输出，确认返回的异常信息里只有错误类型和规则上下文，不会泄露任何原始敏感内容。

小结：先守住结构，再谈日志可读性

PHP JSON 日志脱敏的正确执行顺序，核心就是先复制原始数据、再递归匹配敏感字段、明确捕获编码过程的所有错误、仅留存必要的审计信息，最后才做格式化输出。只要把“敏感明文不落地、全量结构可解析、所有失败可追踪”这三条定为测试的硬性门槛，后续新增字段脱敏规则时，完全不需要靠人工肉眼核对碰运气。