手把手教你從零設計一個java日志框架

Posted on 2021-02-17 by WalkonNet

輸出內容 – LoggingEvent

提到日志框架，最容易想到的核心功能，那就是輸出日志瞭。那麼對於一行日志內容來說，應該至少包含以下幾個信息：

日志時間戳
線程信息
日志名稱（一般是全類名）
日志級別
日志主體（需要輸出的內容，比如info（str））

為瞭方便的管理輸出內容，現在需要創建一個輸出內容的類來封裝這些信息：

public class LoggingEvent {
 public long timestamp;//日志時間戳
 private int level;//日志級別
 private Object message;//日志主題
 private String threadName;//線程名稱
 private long threadId;//線程id
 private String loggerName;//日志名稱
 
 //getter and setters...
 
 @Override
 public String toString() {
  return "LoggingEvent{" +
    "timestamp=" + timestamp +
    ", level=" + level +
    ", message=" + message +
    ", threadName='" + threadName + '\'' +
    ", threadId=" + threadId +
    ", loggerName='" + loggerName + '\'' +
    '}';
 }
}

對於每一次日志打印，應該屬於一次輸出的“事件-Event”，所以這裡命名為LoggingEvent

輸出組件 – Appender

有瞭輸出內容之後，現在需要考慮輸出方式。輸出的方式可以有很多：標準輸出/控制臺（Standard Output/Console）、文件（File）、郵件（Email）、甚至是消息隊列（MQ）和數據庫。

現在將輸出功能抽象成一個組件“輸出器” – Appender，這個Appender組件的核心功能就是輸出，下面是Appender的實現代碼：

public interface Appender {
 void append(LoggingEvent event);
}

不同的輸出方式，隻需要實現Appender接口做不同的實現即可，比如ConsoleAppender – 輸出至控制臺

public class ConsoleAppender implements Appender {
 private OutputStream out = System.out;
 private OutputStream out_err = System.err;

 @Override
 public void append(LoggingEvent event) {
  try {
   out.write(event.toString().getBytes(encoding));
  } catch (IOException e) {
   e.printStackTrace();
  }
 }
}

日志級別設計 – Level

日志框架還應該提供日志級別的功能，程序在使用時可以打印不同級別的日志，還可以根據日志級別來調整那些日志可以顯示，一般日志級別會定義為以下幾種，級別從左到右排序，隻有大於等於某級別的LoggingEvent才會進行輸出

ERROR > WARN > INFO > DEBUG > TRACE
現在來創建一個日志級別的枚舉，隻有兩個屬性，一個級別名稱，一個級別數值（方便做比較）

public enum Level {
 ERROR(40000, "ERROR"), WARN(30000, "WARN"), INFO(20000, "INFO"), DEBUG(10000, "DEBUG"), TRACE(5000, "TRACE");

 private int levelInt;
 private String levelStr;

 Level(int i, String s) {
  levelInt = i;
  levelStr = s;
 }

 public static Level parse(String level) {
  return valueOf(level.toUpperCase());
 }

 public int toInt() {
  return levelInt;
 }

 public String toString() {
  return levelStr;
 }

 public boolean isGreaterOrEqual(Level level) {
  return levelInt>=level.toInt();
 }

}

日志級別定義完成之後，再將LoggingEvent中的日志級別替換為這個Level枚舉

public class LoggingEvent {
 public long timestamp;//日志時間戳
 private Level level;//替換後的日志級別
 private Object message;//日志主題
 private String threadName;//線程名稱
 private long threadId;//線程id
 private String loggerName;//日志名稱
 
 //getter and setters...
}

現在基本的輸出方式和輸出內容都已經基本完成，下一步需要設計日志打印的入口，畢竟有入口才能打印嘛

日志打印入口 – Logger

現在來考慮日志打印入口如何設計，作為一個日志打印的入口，需要包含以下核心功能：

提供error/warn/info/debug/trace幾個打印的方法
擁有一個name屬性，用於區分不同的logger
調用appender輸出日志
擁有自己的專屬級別（比如自身級別為INFO，那麼隻有INFO/WARN/ERROR才可以輸出）

先來簡單創建一個Logger接口，方便擴展

public interface Logger{
 void trace(String msg);
 void info(String msg);
 void debug(String msg);
 void warn(String msg);
 void error(String msg);
 String getName();
}

再創建一個默認的Logger實現類：

public class LogcLogger implements Logger{
 private String name;
 private Appender appender;
 private Level level = Level.TRACE;//當前Logger的級別，默認最低
 private int effectiveLevelInt;//冗餘級別字段，方便使用
 
 @Override
 public void trace(String msg) {
  filterAndLog(Level.TRACE,msg);
 }

 @Override
 public void info(String msg) {
  filterAndLog(Level.INFO,msg);
 }

 @Override
 public void debug(String msg) {
  filterAndLog(Level.DEBUG,msg);
 }

 @Override
 public void warn(String msg) {
  filterAndLog(Level.WARN,msg);
 }

 @Override
 public void error(String msg) {
  filterAndLog(Level.ERROR,msg);
 }
 
 /**
  * 過濾並輸出，所有的輸出方法都會調用此方法
  * @param level 日志級別
  * @param msg 輸出內容
  */
 private void filterAndLog(Level level,String msg){
  LoggingEvent e = new LoggingEvent(level, msg,getName());
  //目標的日志級別大於當前級別才可以輸出
  if(level.toInt() >= effectiveLevelInt){
   appender.append(e);
  }
 }
 
 @Override
 public String getName() {
  return name;
 }
 
 //getters and setters...
}

好瞭，到現在為止，現在已經完成瞭一個最最最基本的日志模型，可以創建Logger，輸出不同級別的日志。不過顯然還不太夠，還是缺少一些核心功能

日志層級 – Hierarchy

一般在使用日志框架時，有一個很基本的需求：不同包名的日志使用不同的輸出方式，或者不同包名下類的日志使用不同的日志級別，比如我想讓框架相關的DEBUG日志輸出，便於調試，其他默認用INFO級別。

而且在使用時並不希望每次創建Logger都引用一個Appender，這樣也太不友好瞭；最好是直接使用一個全局的Logger配置，同時還支持特殊配置的Logger，且這個配置需要讓程序中創建Logger時無感（比如LoggerFactory.getLogger(XXX.class)）

可上面現有的設計可無法滿足這個需求，需要稍加改造

現在設計一個層級結構，每一個Logger擁有一個Parent Logger，在filterAndLog時優先使用自己的Appender，如果自己沒有Appender，那麼就向上調用父類的appnder，有點反向“雙親委派（parents delegate）”的意思

上圖中的Root Logger，就是全局默認的Logger，默認情況下它是所有Logger（新創建的）的Parent Logger。所以在filterAndLog時，默認都會使用Root Logger的appender和level來進行輸出

現在將filterAndLog方法調整一下，增加向上調用的邏輯：

private LogcLogger parent;//先給增加一個parent屬性

private void filterAndLog(Level level,String msg){
 LoggingEvent e = new LoggingEvent(level, msg,getName());
 //循環向上查找可用的logger進行輸出
 for (LogcLogger l = this;l != null;l = l.parent){
  if(l.appender == null){
   continue;
  }
  if(level.toInt()>effectiveLevelInt){
   l.appender.append(e);
  }
  break;
 }
}

好瞭，現在這個日志層級的設計已經完成瞭，不過上面提到不同包名使用不同的logger配置，還沒有做到，包名和logger如何實現對應呢？

其實很簡單，隻需要為每個包名的配置單獨定義一個全局Logger，在解析包名配置時直接為不同的包名

日志上下文 – LoggerContext

考慮到有一些全局的Logger，和Root Logger需要被各種Logger引用，所以得設計一個Logger容器，用來存儲這些Logger

/**
 * 一個全局的上下文對象
 */
public class LoggerContext {

 /**
  * 根logger
  */
 private Logger root;

 /**
  * logger緩存，存放解析配置文件後生成的logger對象，以及通過程序手動創建的logger對象
  */
 private Map<String,Logger> loggerCache = new HashMap<>();

 public void addLogger(String name,Logger logger){
  loggerCache.put(name,logger);
 }

 public void addLogger(Logger logger){
  loggerCache.put(logger.getName(),logger);
 }
 //getters and setters...
}

有瞭存放Logger對象們的容器，下一步可以考慮創建Logger瞭

日志創建 – LoggerFactory

為瞭方便的構建Logger的層級結構，每次new可不太友好，現在創建一個LoggerFactory接口

public interface ILoggerFactory {
 //通過class獲取/創建logger
 Logger getLogger(Class<?> clazz);
 //通過name獲取/創建logger
 Logger getLogger(String name);
 //通過name創建logger
 Logger newLogger(String name);
}

再來一個默認的實現類

public class StaticLoggerFactory implements ILoggerFactory {

 private LoggerContext loggerContext;//引用LoggerContext

 @Override
 public Logger getLogger(Class<?> clazz) {
  return getLogger(clazz.getName());
 }

 @Override
 public Logger getLogger(String name) {
  Logger logger = loggerContext.getLoggerCache().get(name);
  if(logger == null){
   logger = newLogger(name);
  }
  return logger;
 }
 
 /**
  * 創建Logger對象
  * 匹配logger name，拆分類名後和已創建（包括配置的）的Logger進行匹配
  * 比如當前name為com.aaa.bbb.ccc.XXService，那麼name為com/com.aaa/com.aaa.bbb/com.aaa.bbb.ccc
  * 的logger都可以作為parent logger，不過這裡需要順序拆分，優先匹配“最近的”
  * 在這個例子裡就會優先匹配com.aaa.bbb.ccc這個logger，作為自己的parent
  *
  * 如果沒有任何一個logger匹配，那麼就使用root logger作為自己的parent
  *
  * @param name Logger name
  */
 @Override
 public Logger newLogger(String name) {
  LogcLogger logger = new LogcLogger();
  logger.setName(name);
  Logger parent = null;
  //拆分包名，向上查找parent logger
  for (int i = name.lastIndexOf("."); i >= 0; i = name.lastIndexOf(".",i-1)) {
   String parentName = name.substring(0,i);
   parent = loggerContext.getLoggerCache().get(parentName);
   if(parent != null){
    break;
   }
  }
  if(parent == null){
   parent = loggerContext.getRoot();
  }
  logger.setParent(parent);
  logger.setLoggerContext(loggerContext);
  return logger;
 }
}

再來一個靜態工廠類，方便使用：

public class LoggerFactory {

 private static ILoggerFactory loggerFactory = new StaticLoggerFactory();

 public static ILoggerFactory getLoggerFactory(){
  return loggerFactory;
 }

 public static Logger getLogger(Class<?> clazz){
  return getLoggerFactory().getLogger(clazz);
 }

 public static Logger getLogger(String name){
  return getLoggerFactory().getLogger(name);
 }
}

至此，所有基本組件已經完成，剩下的就是裝配瞭

配置文件設計

配置文件需至少需要有以下幾個配置功能：

配置Appender
配置Logger
配置Root Logger

下面是一份最小配置的示例

<configuration>

 <appender name="std_plain" class="cc.leevi.common.logc.appender.ConsoleAppender">
 </appender>

 <logger name="cc.leevi.common.logc">
  <appender-ref ref="std_plain"/>
 </logger>

 <root level="trace">
  <appender-ref ref="std_pattern"/>
 </root>
</configuration>

除瞭XML配置，還可以考慮增加YAML/Properties等形式的配置文件，所以這裡需要將解析配置文件的功能抽象一下，設計一個Configurator接口，用於解析配置文件：

public interface Configurator {
 void doConfigure();
}

再創建一個默認的XML形式的配置解析器：

public class XMLConfigurator implements Configurator{
 
 private final LoggerContext loggerContext;
 
 public XMLConfigurator(URL url, LoggerContext loggerContext) {
  this.url = url;//文件url
  this.loggerContext = loggerContext;
 }
 
 @Override
 public void doConfigure() {
  try{
   DocumentBuilderFactory factory = DocumentBuilderFactory.newInstance();
   DocumentBuilder documentBuilder = factory.newDocumentBuilder();
   Document document = documentBuilder.parse(url.openStream());
   parse(document.getDocumentElement());
   ...
  }catch (Exception e){
   ...
  }
 }
 private void parse(Element document) throws IllegalAccessException, ClassNotFoundException, InstantiationException {
  //do parse...
 }
}

解析時，裝配LoggerContext，將配置中的Logger/Root Logger/Appender等信息構建完成，填充至傳入的LoggerContext

現在還需要一個初始化的入口，用於加載/解析配置文件，提供加載/解析後的全局LoggerContext

public class ContextInitializer {
 final public static String AUTOCONFIG_FILE = "logc.xml";//默認使用xml配置文件
 final public static String YAML_FILE = "logc.yml";

 private static final LoggerContext DEFAULT_LOGGER_CONTEXT = new LoggerContext();
 
 /**
 * 初始化上下文
 */
 public static void autoconfig() {
  URL url = getConfigURL();
  if(url == null){
   System.err.println("config[logc.xml or logc.yml] file not found!");
   return ;
  }
  String urlString = url.toString();
  Configurator configurator = null;

  if(urlString.endsWith("xml")){
   configurator = new XMLConfigurator(url,DEFAULT_LOGGER_CONTEXT);
  }
  if(urlString.endsWith("yml")){
   configurator = new YAMLConfigurator(url,DEFAULT_LOGGER_CONTEXT);
  }
  configurator.doConfigure();
 }

 private static URL getConfigURL(){
  URL url = null;
  ClassLoader classLoader = ContextInitializer.class.getClassLoader();
  url = classLoader.getResource(AUTOCONFIG_FILE);
  if(url != null){
   return url;
  }
  url = classLoader.getResource(YAML_FILE);
  if(url != null){
   return url;
  }
  return null;
 }
 
 /**
 * 獲取全局默認的LoggerContext
 */
 public static LoggerContext getDefautLoggerContext(){
  return DEFAULT_LOGGER_CONTEXT;
 }
}

現在還差一步，將加載配置文件的方法嵌入LoggerFactory，讓LoggerFactory.getLogger的時候自動初始化，來改造一下StaticLoggerFactory：

public class StaticLoggerFactory implements ILoggerFactory {

 private LoggerContext loggerContext;

 public StaticLoggerFactory() {
  //構造StaticLoggerFactory時，直接調用配置解析的方法，並獲取loggerContext
  ContextInitializer.autoconfig();
  loggerContext = ContextInitializer.getDefautLoggerContext();
 }
}

現在，一個日志框架就已經基本完成瞭。雖然還有很多細節沒有完善，但主體功能都已經包含，麻雀雖小五臟俱全

完整代碼

本文中為瞭便於閱讀，有些代碼並沒有貼上來，詳細完整的代碼可以參考：

https://github.com/kongwu-/logc

手把手教你從零設計一個java日志框架

輸出內容 – LoggingEvent

輸出組件 – Appender

日志級別設計 – Level

日志打印入口 – Logger

日志層級 – Hierarchy

日志上下文 – LoggerContext

日志創建 – LoggerFactory

配置文件設計

完整代碼

推薦閱讀：

發佈留言取消回覆

近期文章

輸出內容 – LoggingEvent

輸出組件 – Appender

日志級別設計 – Level

日志打印入口 – Logger

日志層級 – Hierarchy

日志上下文 – LoggerContext

日志創建 – LoggerFactory

配置文件設計

完整代碼

推薦閱讀：

發佈留言 取消回覆

近期文章

標籤

發佈留言取消回覆