v0.8.4 — 通用 Request ID Header

主要变更

• 默认 request_id_header 从 x-b3-traceid 调整为通用关联 Header x-request-id。
• 避免包生成的 UUID v7 被误认为符合 B3 规范的 Trace ID，提升与 B3/OpenTelemetry 链路组件协作时的语义严谨性。
• 修正 LogMiddleware 注释，使其准确描述 Request ID 的长度、安全字符校验及无效值替换行为。
• README 示例、配置表和 API/SDK 传播测试已同步更新。
• 新增自定义 Header 回归测试，确认显式配置仍会被规范化并正常使用。

兼容性说明

• 这是默认配置行为变更：未显式设置 trace_log.request_id_header 的应用，升级后将使用 x-request-id。
• 如需保持旧 Header，可在宿主配置中显式设置 request_id_header；自定义 Header 支持保持不变。
• PHP 最低版本仍为 8.2，Hyperf 兼容范围仍为 3.2，无依赖升级要求。

验证

• PHPUnit：161 tests，1032 assertions，全部通过。
• PHPStan level 8：无错误。
• PHP CS Fixer dry-run：无格式差异。
• git diff --check：通过。

v0.8.3 — 安全性与稳健性增强

主要变更

• 加固入站 Request ID：限制为最多 128 字节、无空白的可打印 ASCII；非法或超长值改为 UUID v7，并同步回写请求与响应 Header。
• 增强 HTTP/SDK 内容保护：始终遮蔽 URL userinfo 密码，同时保留用户名、path 与 fragment；文档明确 payload.max_bytes=null 的内存与 OOM 风险。
• 增强 Guzzle 异常结果处理：fulfilled 但非 PSR-7 ResponseInterface 的值记录为 WARNING，仅记录返回类型，不序列化未知对象或内容。
• 修复 SQL 日志插值边界：支持 PostgreSQL dollar-quoted body，并避免将 ::cast 误识别为命名参数。
• 补充 Request ID、URL 脱敏、Guzzle 非标准返回值和 PostgreSQL SQL 的回归测试。

兼容性说明

• PHP 最低版本仍为 8.2，Hyperf 兼容范围仍为 3.2。
• RequestContext 新增公开常量 MAX_REQUEST_ID_BYTES，值为 128。
• 行为调整：带前后空白、控制字符、Unicode 或超长的外部 Request ID 不再 trim 后接受，而是替换为 UUID v7。
• 无配置迁移或依赖升级要求。

验证

• PHPUnit：160 tests，1031 assertions，全部通过。
• PHPStan level 8：无错误。
• PHP CS Fixer dry-run：无格式差异。
• git diff --check：通过。

v0.8.2

主要变更

• LogConfig 在构造时一次性读取、严格校验并缓存配置，符合 Hyperf 常驻 Worker 需要重启后配置才生效的运行模型。
• API、Database 和 Redis 采集准备阶段的异常现在会进入内部诊断，不再逃逸并影响原业务执行结果。
• 精简异步同步回退逻辑，并为源码公共及内部方法补齐职责注释和自动化注释覆盖测试。
• 重组 README：突出五分钟接入路径、完整配置表、日志级别、协程上下文、异步写入、内容保护及 Guzzle 边界。

依赖与兼容性

• 保持 PHP >=8.2、Hyperf ^3.2、官方 Swoole >=5.0 和 Guzzle ^7.0。
• 修复 WriteMode typed class constants 导致的 PHP 8.2 语法不兼容。
• 补充源码实际使用的直接依赖，移除非必需的 hyperf/guzzle 和 minimum-stability: dev。
• hyperf/guzzle 改为宿主可选依赖；通过 Hyperf\\Guzzle\\ClientFactory 创建的协程客户端仍可正常保留 CoroutineHandler 并记录 sdklog。
• CI 对 PHP 8.2、8.3、8.4 独立执行语法和完整质量检查。

验证

• PHPUnit：147 tests，993 assertions
• PHPStan：无错误
• PHP CS Fixer：无格式问题
• PHP 8.2 目标语法解析通过
• Composer 严格校验和 git diff --check 通过

v0.8.1

本次发布完善了 Hyperf 日志采集管线：统一 CollectorLoggerInterface 为 Monolog Level + Collector 的单一 log 方法；将 HttpStatusClass 作为 Enum 公开，并统一 API/SDK 的 HTTP 判级（4xx 为 WARNING、5xx 或异常为 ERROR）。LogConfig 现在在构造阶段严格校验布尔开关、Header、写入模式、异步队列预算及内容保护配置，默认值集中维护。异步 dispatcher 增加有界队列、同步回退、串行 Handler 写入、确定性 drain 与递归保护；SDK Promise 使用请求期 LogOrigin 快照，跨协程完成时仍保留 request_id。采集链路内部诊断现在包含受限的异常类型、单行消息、文件名、行号和 request_id，不输出 stack trace；benchmark 增加重复日志检测，测试覆盖异步生命周期与诊断边界。README 已同步为 v0.8.1 当前使用说明。验证结果：142 tests、433 assertions，PHPStan、PHP CS Fixer 和 Composer validate 全部通过。

v0.8.0

主要变更

• 默认日志写入模式由 async 调整为可靠基线 sync；异步模式改为每 Worker 一个惰性、有界的消费队列，支持容量预算、同步回退和退出 drain。
• API/SDK 始终保留 response.status_code，即使关闭响应详情也能正确按 4xx → WARNING、5xx/异常 → ERROR 判级；Header 和 Body 仍由 response_enabled 控制。
• 合并采集器身份与提交时元数据，并增加 LogOrigin，保证 SDK Promise 跨协程完成时继续使用请求发起时的 request ID 和协程 ID。
• 新增 WriteMode::SYNC、WriteMode::ASYNC，统一同步/异步配置标识。
• 严格校验采集器布尔开关和 request_id_header，防止字符串 "false" 意外开启敏感日志或非法 Header 破坏请求。
• API/SDK 共用 HTTP 日志级别策略；数据库日志继续仅依赖 Hyperf QueryExecuted 事件，不增加数据库 AOP。

兼容性调整

• CollectorLoggerInterface 现在包含 PSR-3 八个级别方法，并增加可选第三参数 ?LogOrigin $origin = null；自定义实现需要补齐完整签名。
• trace_log.write_mode 省略时现在默认为 sync。需要异步写入时应显式设置 WriteMode::ASYNC，并可通过 async.max_buffer_bytes 配置每 Worker 队列预算。
• collectors.*.enabled 与 response_enabled 现在严格要求布尔值。

验证

• PHPUnit：110 tests，354 assertions
• PHPStan：No errors
• PHP CS Fixer dry-run：通过
• git diff --check：通过

v0.7.1 · Swoole 日志写入加固

本次更新

• 新增 trace_log.write_mode：默认 async 保持原有行为，可设为 sync 在当前执行单元完成采集日志的写入尝试；无效配置明确报错。
• 异步创建子协程抛错或返回失败值时记录诊断并同步回退；内容处理及 Handler 异常仍与业务隔离，request ID 在采集子协程中继承。
• 新增真实 Swoole 协程和 CLI/API/Guzzle/DB/Redis → 结构化 JSON 链路测试，补齐 SQL 插值及边界/失败路径。新增可复现的性能脚本和本机基线。
• Composer 明确要求官方 ext-swoole >=5.0；CI 为 PHP 8.2、8.3、8.4 安装 Swoole。GitHub 源码保留开发测试与 benchmark，Composer dist 排除这些开发资料。

兼容性与注意事项

• 保留 Schema 1、现有公开接口、采集器默认开关及默认异步行为；从 v0.7.0 升级无需迁移现有采集配置。Swoole 现在是安装硬依赖，无 Swoole/OpenSwoole 环境不在支持范围。
• 同步模式只保证当前调用完成写入尝试，不保证物理落盘或零丢失；异步在 Worker 终止时可能丢失尾部日志，调度失败同步回退时可能短暂增加业务延迟。
• SQL 插值 bindings 与 Redis 非 AUTH 命令参数沿用原始记录方式，可能包含敏感信息；请按数据分级谨慎开启相关采集器。

验证

• PHPUnit：82 tests / 264 assertions；PHPStan Level 8、PHP-CS-Fixer dry-run、Composer 校验通过。
• GitHub Actions：PHP 8.2、8.3、8.4 + Swoole 三个 job 全绿（run 35344767631）。
• 独立目录从零安装包开发依赖并通过 PHPUnit、PHPStan Level 8 与代码风格检查；性能脚本完成 sync/async × 等待/立即终止测量。

v0.7.0 - 结构化日志管线重构

主要变更

• 重构 RequestContext：统一 request ID 与开始时间的生成和查询，使用固定协程 Context key，并提供 id()、startTime() 等无副作用查询方法。
• 重构四类日志采集器：API、Guzzle、数据库和 Redis 共用 CollectorLogger、统一日志结构及异常隔离。
• 新增 schema_version 1 的 StructuredJsonFormatter，时间戳固定为北京时间微秒格式，并避免普通同名消息被误判为采集器日志。
• 新增递归字段脱敏、容量限制及 payload_protection 元数据；显式无效 JSON 采用 fail-closed 策略。
• 安全快照 PSR-7 Stream：恢复可回绕流位置，支持 Hyperf SwooleStream，并跳过真正不可回绕的流。
• Guzzle 仅负责 request ID 透传和 SDK 日志，不再设置 timeout、connect_timeout 或 swoole 参数。
• trace_log.logger_channel 统一选择已有的 Hyperf Logger channel；不再要求在 logger.php 重复配置 apilog、sdklog、dblog、redislog alias。
• 增加 PHPStan level 8、PHP-CS-Fixer 和 GitHub Actions CI。

兼容性与迁移

这是破坏性版本，要求 PHP >= 8.2、Hyperf ^3.2、Guzzle ^7.0。

• RequestContext 移至 Sllhsmile\HyperfLog\Context 命名空间。
• TraceContextData 更名为 TraceContext。
• CustomizeJsonFormatter 更名为 StructuredJsonFormatter。
• 采集器开关与 response_enabled 移至 trace_log.collectors。
• 使用 trace_log.logger_channel 选择现有 Logger channel；null 表示跟随 logger.default。
• 移除可配置 Context key、Guzzle 开始时间 Header 和公共超时配置。
• PayloadProcessorInterface::process() 首个参数改为 Collector 枚举。

修复

• 修复 Hyperf 默认 SwooleStream 请求体和响应体无法记录的问题。
• 修复普通业务 message 为 http.server、http.client 等值时被错误分类并丢失 message 的问题。
• Redis AUTH 始终遮蔽，日志处理或 Handler 异常不再影响业务结果。

验证

• PHPUnit：44 tests，136 assertions
• PHPStan level 8：通过
• PHP-CS-Fixer：通过
• Composer validate：通过
• 宿主 Hyperf LoggerFactory 集成验证：通过

v0.6.1

主要变更

• 支持安全快照 Hyperf 默认 SwooleStream，恢复常规 HTTP 请求与响应正文日志。
• 畸形 JSON 采用失败关闭策略，正文记为 null 并输出 payload_omission 原因，避免绕过敏感字段脱敏。
• 修复业务 JSON 中 headers 节点的嵌套敏感字段脱敏。
• 统一 trace 生命周期：requestId 与 startedAt 由只读 TraceContextData 原子保存，Context key 固定使用 RequestContext::class。
• HTTP 异常响应提前写入 request ID，保证正常与异常路径保持一致。

兼容性调整

• RequestContext 使用 start() 作为唯一生成入口，使用 current()、id() 和 startTime() 进行无副作用查询。
• 移除旧的 initialize()、initializeRequestId()、initializeTrace() 接口。
• 移除 request_id_context_key 和 request_start_context_key 配置；request_id_header 与 Guzzle 的 request_start_header 保持可配置。
• 未初始化 trace 时，Formatter 与 Guzzle 不再隐式创建 request ID；RPC 和后台任务应在每个处理单元入口调用 start()。
• PHP 8.2、Hyperf 3.2 和 Guzzle 7 的版本要求保持不变。

缺陷修复

• 修复不可 seek 的 Hyperf SwooleStream 被直接跳过，导致默认环境无法记录 API 正文的问题。
• 修复畸形 JSON 可能以原始字符串进入日志的问题。
• 修复异常响应可能缺失 request ID 的问题。
• 修复长驻协程重复处理时 trace ID 与开始时间可能不同步的问题。

验证

• PHPUnit：62 tests，227 assertions。
• PHPStan level 8：无错误。
• Composer validate 与 git diff --check 均通过。

v0.6.0

主要变更

• 统一 apilog、sdklog、redislog 和 dblog 的请求、响应与 duration_ms 日志结构。
• JSON 请求和响应保留对象或数组结构，普通文本保留字符串，避免 JSON Body 二次编码。
• 新增安全的 PSR-7 Stream 快照：可回绕流读取后恢复位置，不可回绕或超限流不读取。
• 入站 multipart 使用已解析字段完成脱敏，上传文件仅记录安全元数据。
• Redis 日志改为完整命令并新增 response_enabled；AUTH 凭据始终遮蔽。
• Guzzle 支持 callable handler 安全跳过、共享 HandlerStack 去重及同步异常日志。
• 请求体、响应体、Redis 命令和数据库结果统一应用容量限制与截断元数据。

兼容性与边界

• 继续要求 PHP 8.2、Hyperf 3.2 和 Guzzle 7。
• 保留原有 Listener、Aspect 和 LogWriter 构造方式。
• 日志子协程以及可配置的 request-id/B3 Trace ID 行为保持不变。
• Redis 完整命令除 AUTH 外不做字段级解析；dblog 不执行脱敏。

验证

• PHPUnit：55 tests，198 assertions。
• PHPStan level 8：无错误。
• composer validate、PHP 语法检查和 git diff --check 均通过。

v0.5.0 - 日志内容保护

新增

• 为 apilog、sdklog 和 redislog 增加可配置的敏感字段脱敏与负载容量限制。
• 新增 PayloadProcessorInterface，宿主应用可通过 Hyperf 容器替换内容处理策略。
• 超限负载增加 payload_truncation 元数据，保留截断前的字节数。

改进与修复

• Guzzle 出站请求统一使用当前 RequestContext 的 request ID，避免同一链路出现多个 ID。
• 收紧日志失败 fallback，只保留安全的定位信息，不复制 Header、Body 或查询参数。
• 将脱敏、截断和日志写入集中到 LogWriter，并保持 CLI 同步写入兼容。
• 完善发布配置、容器工厂、中文代码注释和面向使用者的 README。

兼容性与边界

• 要求 PHP >=8.2、Hyperf ^3.2、Guzzle ^7.0。
• dblog 保持原有 SQL 与结果结构，不参与本次脱敏和截断。
• multipart/form-data 原始请求体和 Redis 格式化 request.command 暂不做结构化脱敏，README 已明确说明。

验证

• composer validate --no-check-publish 通过。
• 全部 PHP 文件及 README 完整 PHP 示例语法检查通过。
• PHPUnit：32 tests，107 assertions，全部通过。
• Tag 源码树已确认不包含 DESIGN.md。