订单物流日志必须独立通道、结构化上下文、全链路一致：用 monolog 单独配置 logistics 通道，采用 rotatingfilehandler 保留7天日志，lineformatter 显式输出 %context%，info 级记录含 order_id、event、from_status、to_status、courier、tracking_no、operator、ip 等字段，cli 脚本复用同一实例，严禁拼接 message 或用 echo/print_r，确保事件完整性优先于性能。
订单物流变更日志必须独立记录、带上下文、可追溯，不能混在通用业务日志里——否则排查发货延迟、用户投诉或对账异常时，你得翻几十个日志文件再手动 grep。
用 Monolog 单独建一个物流日志通道
很多团队直接用 Log::info() 往默认通道写，结果物流日志被淹没在登录、支付、缓存刷新等杂日志中。正确做法是为物流事件单独配置一个通道，比如叫 logistics：
use Monolog\Logger;
use Monolog\Handler\RotatingFileHandler;
use Monolog\Formatter\LineFormatter;
$logistics = new Logger('logistics');
$handler = new RotatingFileHandler(__DIR__ . '/logs/logistics.log', 7, Logger::INFO);
$formatter = new LineFormatter("[%datetime%] %level_name%: %message% | context=%context%\n");
$handler->setFormatter($formatter);
$logistics->pushHandler($handler);
关键点：
-
RotatingFileHandler第二个参数7表示只保留最近 7 天日志，防止单个文件爆炸 - 格式器里显式输出
%context%，后续才能塞进订单 ID、运单号、状态变化前/后值 - 级别设为
INFO起步，DEBUG级别留给开发期查字段映射问题，上线后关掉
记录时必须带结构化上下文，不能只写“已发货”
一句 $logistics->info('订单 12345 已发货') 在生产环境毫无价值。下次用户问“什么时候发的？谁发的？发的哪家快递？单号多少？”，你只能去数据库翻表、再查操作日志、再对时间戳——三头跑。
立即学习“PHP免费学习笔记（深入）”；
正确写法是把所有关键事实作为 context 数组传入：
$logistics->info('物流状态更新', [
'order_id' => 12345,
'event' => 'shipped',
'from_status' => 'paid',
'to_status' => 'shipped',
'courier' => 'SF',
'tracking_no' => 'SF100000001',
'operator' => 'admin_user_789',
'ip' => $_SERVER['REMOTE_ADDR'] ?? 'cli',
]);
这样日志内容会自动变成 JSON 可解析格式（配合 JsonFormatter 更佳），也方便后续接入 ELK 或 Loki 做聚合分析。
- 漏掉
from_status就无法判断是否跳过中间状态（比如从created直接到shipped，说明可能有脚本误操作） -
operator和ip必须记，审计和追责时是唯一依据 - 不要在 message 字符串里拼接变量——会导致日志难以正则提取、影响结构化解析
CLI 脚本发物流也要走同一套日志逻辑
定时任务（如每天凌晨调用快递接口同步物流）常被忽略日志一致性。很多人直接用 file_put_contents 或 error_log 写到临时文件，结果：查问题时发现 Web 请求有日志，后台脚本没日志，或者格式完全不一致。
解决方案：CLI 脚本初始化时复用同一个 $logistics 实例（或工厂类），确保路径、格式、上下文字段完全统一：
// cli/sync-logistics.php
require __DIR__ . '/../vendor/autoload.php';
// ... 初始化 $logistics 同上
$logistics->info('开始批量同步物流状态', [
'batch_size' => 237,
'source' => 'kdniao_api',
]);
foreach ($orders as $order) {
try {
$result = callKdNiaoApi($order['tracking_no']);
$logistics->info('物流同步成功', [
'order_id' => $order['id'],
'api_response_code' => $result['Code'],
'latest_status' => $result['Traces'][0]['AcceptStation'] ?? 'unknown',
]);
} catch (Exception $e) {
$logistics->error('物流同步失败', [
'order_id' => $order['id'],
'exception' => $e->getMessage(),
'trace' => $e->getTraceAsString(),
]);
}
}
- 避免在 CLI 中用
echo或print_r当日志——它们不会落盘，且无时间戳、无级别 - 如果脚本由 systemd 或 crontab 启动，记得检查
umask和日志目录权限，RotatingFileHandler默认创建的文件权限是 0644，但某些容器环境需显式设为 0664
最易被忽略的一点：物流日志的「事件完整性」比「写得快」重要得多。宁可让发货接口慢 50ms 等日志刷盘，也不要为了性能异步丢弃上下文——一次丢日志，可能意味着你永远没法还原那个客户投诉的“明明显示已签收却说没收到”的现场。
