2.2 PhalApi 2.x 日志

日志

关于日志接口，PSR规范中给出了相当好的说明和定义，并且有多种细分的日记级别。

简化版的日记接口

虽然PSR规范中详尽定义了日志接口，然而在用使用开源框架或内部框架进行项目开发过程中，实际上日记的分类并没有使用得那么丰富，通常只是频繁集中在某几类。为了减少不必要的复杂性，PhalApi特地将此规范的日志接口精简为三种，只有：

error：系统异常类日记
info：业务纪录类日记
debug：开发调试类日记

error 系统异常类日记

系统异常类日志用于纪录在后端不应该发生却发生的事情，即通常所说的系统异常。例如：调用第三方、的接口失败了，此时需要纪录一下当时的场景，以便复查和定位出错的原因。又如：写入一条纪录到数据纪录却失败了，此时需要纪录一下，以便进一步排查。

纪录系统异常日志，用法很简单。可以使用PhalApi\Logger::error($msg, $data)接口，第一个参数$msg用于描述日志信息，第二个可选参数为上下文场景的信息。下面是一些使用示例。

// 只有描述
\PhalApi\DI()->logger->error('fail to insert DB');


// 描述 + 简单的信息
\PhalApi\DI()->logger->error('fail to insert DB', 'try to register user dogstar');


// 描述 + 当时的上下文数据
$data = array('name' => 'dogstar', 'password' => '123456');
\PhalApi\DI()->logger->error('fail to insert DB', $data);

上面三条纪录，会在日记文件中生成类似以下的日志内容。

$ tailf ./runtime/log/201502/20150207.log 
2015-02-07 20:37:55|ERROR|fail to insert DB
2015-02-07 20:37:55|ERROR|fail to insert DB|try to register user dogstar
2015-02-07 20:37:55|ERROR|fail to insert DB|{"name":"dogstar","password":"123456"}

info 业务纪录类日记

业务纪录日志，是指纪录业务上关键流程环节的操作，以便发生系统问题后进行回滚处理、问题排查以及数据统计。如在有缓存的情况下，可能数据没及时写入数据库而导致数据丢失或者回档，这里可以通过日记简单查看是否可以恢复。以及说明一下操作发生的背景或原由，如通常游戏中用户的经验值添加：

// 假设：10 + 2 = 12
\PhalApi\DI()->logger->info('add user exp', array('name' => 'dogstar', 'before' => 10, 'addExp' => 2, 'after' => 12, 'reason' => 'help one more phper'));

对应的日记为：

2015-02-07 20:48:51|INFO|add user exp|{"name":"dogstar","before":10,"addExp":2,"after":12,"reason":"help one more phper"}

debug 开发调试类日记

开发调试类日记，主要用于开发过程中的调试。用法如上，这里不再赘述。以下是一些简单的示例。

// 只有描述
\PhalApi\DI()->logger->debug('just for test');


// 描述 + 简单的信息
\PhalApi\DI()->logger->debug('just for test', '一些其他的描述 ...');


// 描述 + 当时的上下文数据
\PhalApi\DI()->logger->debug('just for test', array('name' => 'dogstar', 'password' => '******'));

更灵活的日志分类

若上面的error、info、debug都不能满足项目的需求时，可以使用PhalApi\Logger::log($type, $msg, $data)接口进行更灵活的日记纪录。

\PhalApi\DI()->logger->log('demo', 'add user exp', array('name' => 'dogstar', 'after' => 12));
\PhalApi\DI()->logger->log('test', 'add user exp', array('name' => 'dogstar', 'after' => 12));

对应的日记为：

2015-02-07 21:13:27|DEMO|add user exp|{"name":"dogstar","after":12}
2015-02-07 21:15:39|TEST|add user exp|{"name":"dogstar","after":12}

注意到，第一个参数为日记分类的名称，在写入日记时会自动转换为大写。其接口函数签名为：

    /**
     * 日记纪录
     *
     * 可根据不同需要，将日记写入不同的媒介
     *
     * @param string $type 日记类型，如：info/debug/error, etc
     * @param string $msg 日记关键描述
     * @param string/array $data 场景上下文信息
     * @return NULL
     */
    abstract public function log($type, $msg, $data);

指定日志级别

在使用日志纪录前，在注册日志\PhalApi\DI()->logger服务时须指定开启的日志级别，以便允许指定级别的日志得以纪录，从而达到选择性保存所需要的日志的目的。

通过PhalApi\Logger的构造函数的参数，可以指定日志级别。多个日记级别使用或运算进行组合。

// 日记纪录
$di->logger = new FileLogger(API_ROOT . '/runtime', Logger::LOG_LEVEL_DEBUG | Logger::LOG_LEVEL_INFO | Logger::LOG_LEVEL_ERROR);

上面的三类日记分别对应的标识如下。

日志类型	日志级别标识
error 系统异常类	PhalApi\Logger::LOG_LEVEL_ERROR
info 业务纪录类	PhalApi\Logger::LOG_LEVEL_INFO
debug 开发调试类	PhalApi\Logger::LOG_LEVEL_DEBUG

扩展：定制你的日志

普遍情况下，我们认为将日记存放在文件是比较合理的，因为便于查看、管理和统计。当然，如果你的项目需要将日记纪录保存在其他存储媒介中，也可以快速扩展实现的。例如实现数据库的存储思路。

<?php
namespace App\Common\Logger;


use PhalApi\Logger;


class DBLogger extends Logger {

    
    public function log($type, $msg, $data) {
        // TODO 数据库的日记写入 ...
    } 
}

随后，重新注册\PhalApiDI()->logger服务即可。

$di->logger = new App\Common\Logger\DBLogger(API_ROOT . '/runtime', Logger::LOG_LEVEL_DEBUG | Logger::LOG_LEVEL_INFO | Logger::LOG_LEVEL_ERROR);