17370845950

订单物流日志必须独立通道、结构化上下文、全链路一致：用 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 已发货') 在生产环境毫无价值。下次用户问“什么时候发的？谁发的？发的哪家快递？单号多少？”，你只能去数据库翻表、再查操作日志、再对时间戳——三头跑。

正确写法是把所有关键事实作为 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 等日志刷盘，也不要为了性能异步丢弃上下文——一次丢日志，可能意味着你永远没法还原那个客户投诉的“明明显示已签收却说没收到”的现场。