06.5.5.12 异常处理与日志
所属:全栈开发面试题库 / 06 后端框架与工程实践 / 06.5 PHP 后端 / 06.5.5 Hyperf
06.5.5.12-001 Hyperf 异常处理机制整体是怎样的?
一句话结论
请求协程内未捕获的异常由框架异常处理器栈接管:按注册顺序匹配 isValid(),匹配成功的处理器 handle() 生成响应并记录日志;处理器未匹配时走默认错误响应,异常处理在中间件链之后兜底。
概念解释
异常处理器按 Server 分组注册,不同协议(HTTP、RPC)可使用不同处理器集合。业务代码抛出的异常不需要在每个控制器重复 try/catch,统一交给处理器转换为标准错误报文;处理器本身仍需避免再次抛出未捕获异常。
原理流程
- 控制器、中间件或服务抛出 Throwable。
- 框架在请求兜底层收集异常,进入异常处理器列表。
- 逐个调用
isValid()匹配异常类型,首个匹配者执行handle()。 - 处理器构造响应、记录日志,未匹配异常走默认响应。
代码或图示
请求链路抛出异常
→ 异常处理器列表按顺序匹配
→ isValid 通过 → handle 生成响应 + 记录日志
→ 全部未匹配 → 默认错误响应
常见误区
- 以为控制器 try/catch 后框架就不再记录异常:异常被吞掉时日志需要业务自己补记。
- 异常处理器里再抛异常:兜底链路再次异常,可能产生默认 500 且堆栈丢失。
追问
- 处理器列表在哪里配置?答:
config/autoload/exceptions.php按 Server 名登记处理器类;结构以组件默认配置为准(待确认)。 - 处理器执行顺序?答:按注册顺序匹配,先注册先判断;精确类型处理器应排在通用兜底处理器之前。
06.5.5.12-002 异常处理器接口的两个方法分别负责什么?
一句话结论
isValid(Throwable $throwable): bool 判断处理器是否处理该异常类型;handle(Throwable $throwable, ResponseInterface $response): ResponseInterface 负责记录日志、构造标准错误响应;接口签名以当前版本源码为准。
概念解释
匹配与处理分离:判断方法保持轻量,不做 IO;处理方法完成响应转换。同一异常可被多个处理器判断,只有首个 isValid 通过的处理器执行。返回的响应对象沿协议写回客户端。
原理流程
- 处理器类实现异常处理器接口。
isValid按异常类名、错误码或属性判断归属。handle提取错误码与消息,写日志堆栈。- 组装响应对象返回,状态码与报文按业务约定设置。
代码或图示
// 接口方法签名以 vendor/hyperf/exception-handler 源码为准(待确认)
interface ExceptionHandlerInterface
{
public function isValid(Throwable $throwable): bool;
public function handle(Throwable $throwable, ResponseInterface $response): ResponseInterface;
}
常见误区
- 在
isValid里查数据库或调用下游:匹配阶段被反复调用,拖慢异常处理链路。 handle只返回响应不记日志:线上排障缺少堆栈现场。
追问
- 处理器能拿到请求对象吗?答:可通过协程上下文获取当前请求;不要把请求对象作为参数依赖,签名以接口定义为准。
- 如何区分业务异常与系统异常?答:定义分层异常基类,处理器按类型映射不同状态码与日志级别。
06.5.5.12-003 exceptions.php 配置结构是怎样的?
一句话结论
配置按 Server 名分组,每组登记有序的处理器类列表;HTTP Server 与其他 Server 可分别配置,处理器类由容器解析,未登记的类型回退默认处理器。
概念解释
注册顺序决定匹配优先级:业务自定义异常处理器靠前,通用兜底处理器靠后。新增处理器后必须登记才生效,类路径拼写错误在启动期可能不暴露,请求触发时才解析失败。
原理流程
- 打开
config/autoload/exceptions.php。 - 按 Server 名填写处理器类全限定名数组。
- 启动期框架读取列表并实例化处理器。
- 请求异常时按对应 Server 的列表依次匹配。
代码或图示
// 结构为示意;Server 键名与默认处理器类名以官方配置为准(待确认)
return [
'http' => [
\App\Exception\Handler\BusinessExceptionHandler::class,
\App\Exception\Handler\DefaultExceptionHandler::class,
],
];
常见误区
- 处理器类写好但忘记登记:异常走默认响应,业务错误码丢失。
- 通用兜底处理器排在前面:所有异常都被它接住,精确类型分支失效。
追问
- 不配置会有默认行为吗?答:组件提供默认异常处理;默认响应格式与是否记录日志以源码为准(待确认)。
- RPC Server 的异常格式在哪里改?答:对应 Server 分组处理器内按协议构造错误响应,报文结构遵循 RPC 组件约定。
06.5.5.12-004 HTTP 异常响应的格式如何统一?
一句话结论
由处理器统一组装响应体:状态码、业务错误码、提示消息与追踪标识固定结构,响应 Content-Type 与序列化方式按项目约定;控制器返回正常数据,错误报文只在处理器出口生成。
概念解释
统一格式避免各控制器手写错误结构造成字段不一致。业务异常携带错误码与面向用户的消息,系统异常对客户端只返回通用提示,详细堆栈进日志,不向前端暴露内部路径与 SQL。
原理流程
- 定义业务异常基类,包含错误码与消息。
- 处理器按异常类型映射 HTTP 状态码。
- 组装统一响应体:code、message、trace_id、数据段。
- 堆栈与上下文写入日志,响应体只暴露安全字段。
代码或图示
// 响应结构为项目约定示意
[
'code' => 10001,
'message' => '库存不足',
'trace_id' => $traceId,
'data' => null,
]
常见误区
- 把异常堆栈直接返回给客户端:泄露框架路径、SQL 与内部结构,也增加响应体积。
- 各控制器自行
json(['error' => ...]):错误码与字段风格不统一。
追问
- HTTP 状态码与业务错误码怎么对应?答:4xx 类客户端错误用对应状态码,业务规则错误可统一 200/400 加业务码;约定在项目内保持一致。
- 响应里带 trace_id 有什么用?答:客户端反馈问题时凭 trace_id 回溯服务端日志,排查链路。
06.5.5.12-005 框架内置异常类型与默认响应如何区分?
一句话结论
常见可识别类型包括路由不存在、方法不允许、参数校验失败、业务异常与未捕获系统异常;不同类型映射不同状态码与报文,未捕获的系统异常对外保持通用提示,详细信息进日志。
概念解释
框架在路由、参数绑定等阶段抛出约定异常,处理器可据此区分“请求问题”与“服务问题”。业务自定义异常继承约定基类,便于统一识别;不要把所有异常都包成通用 Exception,丢失类型信息。
原理流程
- 路由匹配失败 → 路由类异常 → 404 报文。
- 参数校验失败 → 校验类异常 → 422/400 报文。
- 业务规则失败 → 业务异常 → 业务错误码。
- 未捕获 Throwable → 系统异常 → 通用 500 提示与错误日志。
代码或图示
// 业务异常基类示意;基类位置以项目与框架约定为准
class BusinessException extends \RuntimeException
{
public function __construct(public readonly int $bizCode, string $message)
{
parent::__construct($message);
}
}
常见误区
- 用通用异常携带所有错误:处理器无法区分类型,状态码与日志级别无法分级。
- 系统异常对外返回详细消息:暴露内部实现,也不利于屏蔽敏感信息。
追问
- 参数校验异常由谁抛出?答:参数绑定/验证组件在校验失败时抛出;异常类名以组件源码为准(待确认)。
- 如何扩展新异常类型?答:继承对应基类,在处理器列表中增加匹配分支,登记注册后生效。
06.5.5.12-006 协程内异常如何被捕获?try/catch 的边界是什么?
一句话结论
同步调用栈内 try/catch 按 PHP 常规边界生效;协程内抛出的异常沿该协程调用栈向上传播,未被捕获则由框架兜底处理器接管。新建协程内的异常不会被外层 try/catch 自动捕获。
概念解释
每个协程有独立调用栈:外层协程 catch 不到内层独立协程抛出的异常。异步投递、监听器内新开协程、回调任务都要在协程入口自行捕获,否则异常成为未捕获错误,日志与响应可能缺失。
原理流程
- 业务代码在当前协程调用栈内 try/catch。
- 同步调用抛出的异常在最近 catch 处捕获。
- 独立协程入口未捕获的异常沿其自身栈上传。
- 框架兜底处理未捕获异常,记录日志。
代码或图示
// 外层 catch 不到新协程内抛出的异常
go(function () {
try {
$this->handle();
} catch (\Throwable $e) {
logger()->error('async failed', ['exception' => $e]);
}
});
常见误区
- 在主流程 catch 后以为异步任务也被保护:异步协程异常独立传播。
- 回调任务入口不写兜底:异常导致协程退出,错误只在底层日志出现。
追问
- 协程未捕获异常默认如何处理?答:由扩展/框架记录错误并终止该协程;是否中断整个进程以实现为准(待确认)。
- 并发工具收集异常怎么做?答:使用框架并发工具时按其结果/异常获取约定处理,不依赖外层全局 catch。
06.5.5.12-007 监听器、消费者、定时任务中的异常如何不被吞掉?
一句话结论
这些异步或托管入口必须在自身回调内捕获异常并分级处理:可预期失败记录后降级,不可预期异常记录堆栈并按组件约定返回失败状态;禁止空 catch 静默丢弃。
概念解释
没有请求响应对象兜底,托管入口的异常若不记录,问题只表现为“消息没处理/任务没跑”。监听器、消费者、Process、定时任务各自有独立兜底边界,入口处的 try/catch 是最后一道防线。
原理流程
- 在回调入口包裹 try/catch。
- 分类异常:业务坏数据记录后丢弃/转死信;暂时性失败返回重试。
- 不可预期异常记录完整堆栈与上下文标识。
- 按组件约定返回确认结果或退出码,避免静默成功。
代码或图示
public function consume($data, $deliveryMessage): mixed
{
try {
$this->service->handle($data);
return \Hyperf\Amqp\Result::ACK;
} catch (\Throwable $e) {
logger()->error('consumer failed', ['data' => $data, 'exception' => $e]);
return \Hyperf\Amqp\Result::REQUEUE;
}
}
常见误区
catch (\Throwable $e) { }空块:失败无日志、无重试,数据缺口不可见。- 所有异常都返回 ACK:消息被确认后不再重投,业务数据丢失。
追问
- 监听器异常如何回到主流程?答:同步监听器异常可向上传播;异步监听器需自行落失败记录,不能依赖主流程响应。
- 任务类异常告警怎么触发?答:失败计数达到阈值接入告警;日志级别与告警规则按项目可观测体系配置。
06.5.5.12-008 异常日志应该记录哪些信息?
一句话结论
至少包含异常类型、堆栈、错误消息、业务标识、请求/消息上下文与 trace_id;分级记录,业务异常记警告,系统异常记错误,避免把大段请求体与敏感信息写进日志。
概念解释
日志目的是可复盘:堆栈定位代码位置,业务标识定位数据,trace_id 串联链路。上下文要精简,记录主键与入参摘要即可;密码、令牌、身份证等敏感字段必须脱敏。重复高频异常还要配合计数,避免日志洪泛。
原理流程
- 处理器/回调捕获异常后提取类型与消息。
- 附带 trace_id、业务主键、来源入口。
- 记录完整堆栈到错误日志通道。
- 脱敏处理参数,控制单条日志体积。
代码或图示
logger()->error('order handle failed', [
'trace_id' => $traceId,
'order_id' => $orderId,
'exception' => $e->getMessage(),
'stack' => $e->getTraceAsString(),
]);
常见误区
- 只记消息不记堆栈:无法定位出错代码行。
- 记录完整请求体:敏感信息泄露且日志体积失控。
追问
- 堆栈里包含反射路径怎么办?答:以框架实际输出为准,必要时在日志格式中裁剪无关前缀;不要掩盖真实业务栈帧。
- 异常日志重复记录怎么办?答:明确边界:处理器记一次,业务回调只补充上下文,避免同一异常多处重复打 error。
06.5.5.12-009 日志组件的结构是怎样的?
一句话结论
日志基于日志库(Monolog 一类)封装:Logger 工厂按通道名获取记录器,记录器绑定处理器(文件、控制台等)与格式化器;项目通过配置定义默认通道与多通道,业务按通道名取用。
概念解释
组件把工厂、通道、处理器分层:业务代码只依赖工厂接口获取通道记录器,不直接写文件路径。不同通道可分文件、分级别;日志组件的类名与配置键以安装版本源码为准。
原理流程
- 配置文件定义通道:处理器、级别、格式、文件路径。
- 工厂按通道名构建或复用 Logger 实例。
- 业务调用
info/error/warning等方法写入记录。 - 处理器按格式写入目标(文件、标准输出等)。
代码或图示
// 工厂获取通道为示意;类名与方法以 vendor/hyperf/logger 为准(待确认)
$logger = $factory->get('order');
$logger->info('order created', ['order_id' => $id]);
常见误区
- 业务代码直接
fopen写日志文件:绕过通道配置、切割与格式化约定。 - 每个请求新建 Logger 实例:应复用工厂提供的实例,避免重复初始化处理器。
追问
- Logger 是协程安全的吗?答:写入操作按处理器实现;文件句柄共享时需确认组件封装的协程安全性(待核对源码)。
- 日志上下文如何附加?答:通过处理器中的上下文处理器或日志记录器补充公共字段,具体机制以日志库能力为准。
06.5.5.12-010 logger.php 如何配置多通道与默认通道?
一句话结论
配置中声明默认通道与命名通道,每个通道绑定处理器、级别与文件;业务可按场景取专用通道(如 order、queue、cron),默认通道承载未指定场景的日志。
概念解释
多通道便于按业务域分文件、按级别分流:错误日志与访问日志分离,消费者与定时任务独立通道。通道配置包含处理器类型、文件路径、日期格式化与最低级别;键名以组件默认配置为准。
原理流程
- 在日志配置中定义默认通道与处理器。
- 为独立业务域新增命名通道与对应文件。
- 业务代码按通道名获取记录器。
- 日志按通道写入对应文件,便于采集与排障。
代码或图示
// 配置结构为示意;处理器类名与键名以官方默认配置为准(待确认)
return [
'default' => [
'handler' => \Monolog\Handler\RotatingFileHandler::class,
'path' => BASE_PATH . '/runtime/logs/hyperf.log',
'level' => 'info',
],
'order' => ['path' => BASE_PATH . '/runtime/logs/order.log'],
];
常见误区
- 所有日志挤在默认通道:排障时从单一大文件检索困难。
- 日志路径写死本机绝对路径:应基于项目基础路径拼接,保证仓库可迁移。
追问
- 路径常量怎么引用?答:入口定义的基础路径常量在配置中拼接相对目录;不要写盘符绝对路径。
- 新增通道后不生效?答:核对配置键名、处理器类是否可用,以及业务取用通道名是否一致。
06.5.5.12-011 日志按天切割与按大小切割如何配置?
一句话结论
按天切割使用日期轮转处理器,按日期生成文件;按大小切割使用文件大小轮转处理器,超过阈值滚动编号;生产常用按天切割并配合日志采集归档,切割参数以日志库处理器为准。
概念解释
不切割的单文件会持续增长,占用磁盘且检索变慢。按天切割文件名带日期,保留天数由配置控制;大小切割防止单日日志洪泛撑爆单文件。两类处理器的构造参数(保留天数、单文件大小)需要对照日志库文档确认。
原理流程
- 通道选择日期轮转或大小轮转处理器。
- 配置基础文件名、保留周期/大小阈值。
- 写入时处理器按规则生成或切换文件。
- 过期文件由采集或清理策略归档删除。
代码或图示
// 处理器参数为示意;构造参数以 Monolog 版本为准(待确认)
// RotatingFileHandler:按天轮转,保留 14 天
// 大小轮转处理器:按单文件字节数与保留份数滚动
常见误区
- 只配置日志输出不设保留周期:旧日志长期堆积占满磁盘。
- 切割时间按服务器本地时区:跨时区部署需统一进程时区与文件名日期约定。
追问
- 日志文件谁负责清理?答:应用处理器可保留份数,容器环境常由采集代理或日志轮转系统接管;两侧策略要协调避免重复删除。
- 切割瞬间日志会丢吗?答:处理器切换文件期间写入仍走当前句柄;极端进程退出场景的缓冲丢失见日志异步条目。
06.5.5.12-012 日志级别如何选择?生产环境开什么级别?
一句话结论
级别由低到高通常为 debug、info、warning、error、critical;生产环境默认 info 或 warning,错误与关键流程记 error/warning,调试细节只在排障临时开启,避免 debug 洪泛影响性能与磁盘。
概念解释
级别决定哪些记录被处理器写入:低于通道级别的日志直接跳过。业务正常流程记 info,可预期异常与降级记 warning,系统错误记 error。生产长期开 debug 会产生大量上下文日志,掩盖真正错误。
原理流程
- 定义各级别使用场景:调试、正常流程、异常预警、系统故障。
- 通道配置最低级别,生产取 info/warning。
- 排障时临时上调级别或开启调试通道,事后恢复。
- 关键错误同时接入告警,不只依赖文件日志。
代码或图示
debug → 开发调试细节,生产默认关闭
info → 正常业务流程关键节点
warning → 可预期异常、降级、重试
error → 业务失败、未捕获异常、下游错误
critical → 影响整体可用性的严重故障
常见误区
- 生产全量 debug:磁盘与 IO 压力上升,错误被海量调试日志淹没。
- 所有异常都记 error:告警阈值被稀释,真正严重问题得不到关注。
追问
- 如何临时开调试日志?答:通过配置中心或环境变量调整通道级别后滚动生效;不重启进程的前提下可刷新的级别项需核对组件能力(待确认)。
- 日志级别能按通道区分吗?答:可以,不同通道配置不同最低级别,独立控制调试与生产通道。
06.5.5.12-013 上下文日志如何注入 trace_id 等公共字段?
一句话结论
把 trace_id、用户标识、请求入口等公共字段在请求开始时写入协程上下文,通过日志上下文处理器自动附加到每条日志;监听器与异步任务需显式把标识带入消息或任务数据。
概念解释
公共字段不希望每条日志手动传参:上下文处理器从当前协程上下文读取并补充到记录数组。trace_id 在请求入口生成或从上游头信息继承,贯穿 DB、Redis、下游调用日志。异步边界(MQ、新协程)上下文不自动传递,需要显式携带。
原理流程
- 请求入口生成/继承 trace_id,写入协程上下文。
- 日志处理器从上下文读取公共字段并附加。
- 业务日志只写业务字段,公共字段自动出现。
- 投递异步任务时把 trace_id 放入消息头/任务参数,消费侧恢复上下文。
代码或图示
// 入口处写入上下文(示意)
Context::set('trace_id', $traceId);
// 日志记录自动携带公共字段;处理器读取上下文的机制以日志组件为准(待确认)
logger()->info('order created', ['order_id' => $id]);
常见误区
- 异步任务日志不带 trace_id:后台日志无法关联原请求链路。
- 把公共字段存进静态变量:跨协程污染,其他请求读到错误标识。
追问
- 上下文处理器在哪里配置?答:日志通道配置中注册上下文处理器;类名与读取约定以组件默认配置为准(待确认)。
- trace_id 从哪里继承?答:从上游请求头(如网关透传字段)读取,缺失时新生成;字段名在项目内统一约定。
06.5.5.12-014 协程环境下日志如何避免上下文串号?
一句话结论
日志公共字段必须从当前协程上下文读取,不能存放在单例 Logger 属性或静态变量中;异步新协程开始时先恢复必要标识,再写日志,避免不同请求的 trace_id 互相覆盖。
概念解释
Logger 实例可复用,但其附加的上下文数据应来自协程隔离的 Context,而非实例可变属性。协程切换时实例属性被并发读写会产生串号;日志处理器设计为每次记录时现场读取上下文,才能保证隔离。
原理流程
- 复用 Logger 单例,不保存请求态字段。
- 每条记录由处理器从当前协程 Context 取公共标识。
- 新协程/消费者入口先恢复上下文标识。
- 退出协程时上下文随协程回收,不残留到下一请求。
代码或图示
// 禁止:单例属性持有请求标识,会被并发协程覆盖
class RequestLogger
{
private string $traceId = ''; // 请求态,禁止存放
}
常见误区
- 复用请求对象时缓存到 Logger:协程结束后引用残留,下条日志读到旧请求。
- 上下文写入全局数组:多协程并发读写产生竞态与串号。
追问
- 如何验证串号?答:压测并发下检查日志行 trace_id 与请求实际标识是否一致;异常关联即可暴露串号。
- Context 丢失时日志怎么标识?答:留空或记
unknown,不要复用其他请求的标识填充。
06.5.5.12-015 日志异步化与缓冲有哪些风险?
一句话结论
日志异步缓冲可降低同步写盘开销,但缓冲未刷出时进程退出会丢失最后一批记录;缓冲区大小、刷写时机与落盘可靠性需要权衡,关键错误日志应能及时写出。
概念解释
同步写文件在高并发下增加 IO 耗时,异步通道先入缓冲再由后台写入。风险点:缓冲队列积压、进程被强杀时内存缓冲丢失、下游采集阻塞反压。是否使用异步处理器由项目日志配置决定,框架默认行为需核对源码。
原理流程
- 业务日志写入缓冲队列。
- 后台协程/进程按批次刷写到文件或采集端。
- 进程正常停止时执行缓冲冲刷。
- 异常退出时未冲刷记录可能丢失,关键错误需同步兜底。
代码或图示
同步日志:记录 → 直接写处理器(可靠,IO 略高)
异步日志:记录 → 缓冲队列 → 后台刷写(低延迟,退出时可能丢缓冲)
常见误区
- 假设异步日志永不丢失:强杀、OOM 退出时内存缓冲未落盘。
- 缓冲无上限:日志洪泛时内存持续增长,加剧 OOM 风险。
追问
- 关键错误要不要走异步?答:error/critical 级别建议保证及时落盘或同步通道;是否分级配置以组件能力为准(待确认)。
- 异步缓冲积压怎么观测?答:监控队列长度与丢弃计数,积压时告警并降级非关键日志。
06.5.5.12-016 哪些情况会导致丢日志?如何降低风险?
一句话结论
常见丢日志场景:进程强杀时缓冲未落盘、异常处理器内记日志再次失败、日志路径/磁盘故障、异步通道丢弃溢出记录;降低风险的手段包括关键日志同步写、缓冲可观测、磁盘与路径健康检查、异常内兜底记录。
概念解释
日志本身也是依赖:写文件失败、磁盘满、权限问题都会让记录消失。异常处理器在构造错误响应时若记日志失败,不能让二次异常掩盖主问题。发布与运维侧要保证日志目录可写、磁盘有空间、采集代理正常。
原理流程
- 梳理日志写出链路:处理器、缓冲、文件/采集端。
- 关键级别记录优先可靠写出,限制缓冲容量。
- 日志写入失败在代码内兜底捕获,避免二次异常。
- 监控磁盘空间、日志增长与采集延迟。
代码或图示
try {
$logger->error($message, $context);
} catch (\Throwable $logFailure) {
// 兜底:写入备用通道或标准输出,不再次抛出
fwrite(STDERR, $message . PHP_EOL);
}
常见误区
- 只相信“日志一定落盘”:不检查目录权限与磁盘水位。
- 在异常处理器中直接调用可能失败的日志接口而不兜底:堆栈现场丢失。
追问
- 磁盘满了应用会怎样?答:日志写入失败,业务可能连带异常;需容量监控与日志轮转保留策略。
- 如何确认日志采集完整?答:对比应用计数与采集端记录数,缺口时段定位缓冲或采集链路。
06.5.5.12-017 日志中的敏感信息如何脱敏?
一句话结论
密码、令牌、密钥、身份证、手机号、银行卡等字段在写入日志前脱敏;通过统一的参数过滤处理器或业务侧掩码处理,禁止把完整凭证与个人敏感信息写入任何日志文件。
概念解释
日志会被采集、留存与多人访问,敏感信息泄露面大于业务数据库。脱敏应在出口统一处理:请求参数、消息体、第三方回调中的敏感字段按规则掩码;配置中的密钥值不出现在日志输出里。
原理流程
- 定义敏感字段清单与掩码规则。
- 在日志格式化/上下文处理器中统一过滤。
- 业务打印参数前对敏感字段掩码。
- 定期审查日志样例,确认无明文凭证。
代码或图示
// 脱敏示意:保留前缀与尾号,中间掩码
function maskPhone(string $phone): string
{
return substr($phone, 0, 3) . '****' . substr($phone, -2);
}
常见误区
- 只对登录接口脱敏:消息队列、第三方回调、异常参数中的敏感字段同样要过滤。
- 把完整 Authorization 头写入调试日志:令牌泄露风险高。
追问
- 脱敏在业务层还是日志层做?答:关键敏感字段建议日志出口统一过滤,业务层配合不主动打印;双层保险。
- 排障需要完整信息怎么办?答:受控环境下临时开启,最小化留存范围,不把敏感样例带入长期日志。
06.5.5.12-018 消费者、定时任务、进程的日志如何归属与分离?
一句话结论
托管入口使用独立日志通道或带入口标识的字段,与 HTTP 请求日志分离;每条记录标注任务/消费者名、消息标识或进程编号,便于按后台任务检索与告警归类。
概念解释
后台任务没有请求 URL,检索日志靠任务名与业务主键。独立通道避免请求日志洪泛淹没后台异常;任务标识写入上下文或日志字段,失败记录能定位到具体任务与消息。
原理流程
- 为消费者、定时任务、守护进程定义专用通道。
- 入口把任务名、消息标识、进程编号写入日志上下文。
- 失败日志按任务通道归档与告警。
- 定期检索后台任务日志的错误计数。
代码或图示
// 任务入口补充上下文字段
logger('cron')->info('settlement start', [
'task' => 'order.settlement',
'cursor' => $cursor,
]);
常见误区
- 后台任务全写默认请求日志:排障时分不清来源,告警难归类。
- 任务日志不带批次/消息标识:失败后无法定位具体数据。
追问
- 独立通道文件怎么切割?答:复用日志轮转配置,按天或大小保留,与请求日志策略一致。
- 多进程写同一文件安全吗?答:取决于处理器与文件句柄实现;不确定时按进程/通道分文件,避免写入交错(待确认:核对日志组件多进程写入行为)。
06.5.5.12-019 结构化日志(JSON)如何对接采集系统?
一句话结论
生产可使用 JSON 格式化器输出固定字段(时间、级别、通道、消息、trace_id、上下文),便于采集代理解析检索;字段结构在项目内约定,新增字段不破坏既有采集规则。
概念解释
纯文本日志依赖正则解析,字段变化易失配;结构化日志每行一个 JSON 对象,公共字段与业务字段分层。采集系统按字段建索引,告警与链路追踪基于 trace_id 关联。格式变更要考虑旧采集规则兼容。
原理流程
- 约定日志 JSON 字段:时间、级别、通道、消息、上下文。
- 通道配置 JSON 格式化器。
- 业务上下文以嵌套对象附加,不与公共字段冲突。
- 采集代理按行解析并写入检索存储。
代码或图示
{
"timestamp": "2026-11-19T10:00:00+08:00",
"level": "error",
"channel": "order",
"message": "order handle failed",
"trace_id": "abc123",
"context": {"order_id": 1001}
}
常见误区
- 上下文对象随意嵌套敏感结构:采集后仍需遵守脱敏规则。
- 一行日志输出多行 JSON 或换行消息:采集按行解析会断裂,消息内换行应转义。
追问
- 格式化器在哪里配置?答:日志通道配置中绑定格式化器;JSON 格式化类以日志库版本为准(待确认)。
- 文本与 JSON 能否并存?答:开发环境文本可读,生产 JSON 结构化;通过环境配置切换通道格式。
06.5.5.12-020 线上异常与日志问题的排查清单是什么?
一句话结论
按“能否复现 → 异常类型与处理器 → 堆栈与上下文 → 日志通道与写出 → 下游依赖”顺序排查:先确认异常是否被处理器接管,再凭 trace_id 串联日志,核对通道配置与磁盘状态,最后定位下游根因。
概念解释
线上问题先判断属于业务异常、系统异常还是日志本身缺失。没有日志记录时,要先排查日志通道、级别、路径与缓冲,再排查业务代码。组件默认行为不确定时,对照 vendor 源码与官方文档核实,不凭记忆下结论。
原理流程
- 凭 trace_id/业务主键检索请求与关联日志。
- 确认异常类型、处理器匹配分支与响应报文。
- 查看完整堆栈与上下文标识,定位代码位置。
- 检查日志通道级别、文件路径、磁盘与缓冲状态。
- 结合下游 DB/Redis/接口指标定位根因。
代码或图示
1. trace_id / 业务主键检索
2. 异常类型 → 处理器分支 → 响应报文
3. 堆栈定位代码位置
4. 日志通道、级别、路径、缓冲、磁盘
5. 下游依赖指标与错误记录
常见误区
- 找不到日志就认定“没有报错”:先排除日志未写出、级别过滤或通道错位。
- 只看错误消息不看堆栈:同类消息多个抛出点,无法定位真实位置。
追问
- 处理器未接管的异常长什么样?答:走默认响应,业务错误码缺失,日志可能只有框架兜底记录;检查 exceptions.php 登记与类型匹配。
- 组件行为与预期不符怎么办?答:标注「待确认」,核对
vendor/hyperf/exception-handler、vendor/hyperf/logger源码与当前版本文档,验证后再调整配置。