开源框架TLog核心原理架构解析

前言

最近在做TLog 1.2.5版本的迭代，许多小伙伴之前也表示说很想参与开源项目的贡献。为了让项目更好更快速的迭代新特性以及本着发扬开源精神互相学习交流，很有幸招募到了很多小伙伴与我一起前行。

为了方便大家理解TLog项目的核心原理和架构，便有了此篇内容。此篇内容偏向TLog技术设计和核心原理，同时也涵盖着做一个开源框架所需要考虑的问题和技术要点。

我一直相信，好的技术内容应提领关键点，引导大家该去如何读懂源码。而不是全篇的贴代码。所以此篇也不是源码解析，而是提炼关键点，让大家如何的更好去理解。

因为阅读者在某些点上可能会有知识盲区，为了讲了细致，在某些点上我尽可能附加了延伸阅读。知道相关知识点的同学，可以直接跳过。

还有，如果你是第一次阅读到此篇内容，不知道TLog是什么项目，则可以移步Gitee的托管仓库以及项目主页去查看项目特性：

gitee托管仓库：https://gitee.com/dromara/TLog

github托管仓库： https://github.com/dromara/TLog

项目主页： https://yomahub.com/tlog/

你也可以看之前发布的一篇介绍TLog文章

https://mp.weixin.qq.com/s/-lalQBIUqxU2RW4RWHHvNw

模块

了解一款开源框架，首先从模块开始了解，TLog定位是一款轻量级日志追踪框架，它由10个模块组成

首先TLog既然是一款日志框架，日志增强就是它的核心，得适配主流的日志框架(log4j / log4j2 /logback)，这些最主要的逻辑和最核心的功能实现都在tlog-core模块中（以后可能还会单独拆出3个日志框架的单独模块）。

其次，TLog能够进行日志追踪，自然要适配微服务架构，支持RPC框架/协议(dubbo / dubbox / spring cloud feign / http)。由于每种RPC框架有自己的扩展点，自然不可能抽象写出统一的处理逻辑。所以就有了以下模块:

tlog-dubbo为对接apache dubbo的适配模块

tlog-dubbox为对接早期的当当的dubbox开源版本，因为有的公司还在用

tlog-feign 为对接spring cloud feign的适配模块

tlog-webroot为对接最普通的http调用适配模块

考虑到用spring cloud的很多公司都会用spring全家桶的spring cloud gateway，所以就有了适配spring cloud gateway的适配模块tlog-gateway

在spring支持方面，tlog支持了传统spring的xml配置结构，也支持了springboot的自动装配。由于spring是springboot的子集，所以必定有2个模块，所以就有了tlog-all和tlog-all-springboot-starter。之所以要加上all字样，因为这2个包也是开发者引用的门面包，这2个提供单独的依赖地址，会把所需要其他的tlog包一起依赖带入。这样就不用一个个去声明依赖了。

TLog提供了基于javaagent的无依赖使用方式，所以就有了tlog-agent模块。在打包时，会单独打成一个jar包。

其他tlog模块所公共使用的一些VO，枚举，util类则抽出来形成一个单独的模块，所以就有了tlog-common。

模块之间的依赖关系图如下：

启动装载

TLog大约有80%的工作都是启动时完成的，所以第一步就要弄清楚TLog随着项目启动时干了些什么。

由于springboot有自动装配功能，所以只需要弄清楚tlog-all-springboot-starter自动装配了什么，就可以了解非springboot项目那些手动配置xml的意义了。

不清楚springboot自动装配功能的同学，可以先去了解下这块的知识，我觉得这篇文章讲的比较透彻，可以延伸阅读下：

https://zhuanlan.zhihu.com/p/95217578

TLog在springboot环境下所有自动装配的配置类，都在spring.factories中体现：

org.springframework.boot.autoconfigure.EnableAutoConfiguration=\
  com.yomahub.tlog.springboot.TLogPropertyConfiguration,\
  com.yomahub.tlog.springboot.TLogWebAutoConfiguration,\
  com.yomahub.tlog.springboot.TLogFeignAutoConfiguration,\
  com.yomahub.tlog.springboot.TLogAspectAutoConfiguration,\
  com.yomahub.tlog.springboot.TLogCommonAutoConfiguration,\
  com.yomahub.tlog.springboot.TLogGatewayAutoConfiguration

TLogPropertyConfiguration主要用来自动装配的是TLog配置初始化器，最终注入的是TLogPropertyInit，在传统spring环境下，也只需要单独配置TLogPropertyInit的xml就可以了，所以两种spring环境形成最终的统一。

TLogWebAutoConfiguration主要用来自动装配http协议的拦截器。

TLogFeignAutoConfiguration主要用来自动装配spring cloud feign环境下的拦截过滤器。

TLogAspectAutoConfiguration主要用来自动装配自定义标签的切面，spring会自动为切中的类生成动态代理注入上下文。

TLogCommonAutoConfiguration主要用来自动装配基于spring上下文的工具类。在很多不在spring容器管理中的bean想获取spring上下文中的bean时，都会用到这个工具类。

TLogGatewayAutoConfiguration主要用来自动装配spring cloud gateway环境下的拦截过滤器。

只要注册了以上的自动装配类，在springboot环境下，启动时都会帮你自动装配好。但是在传统spring下，你还是得在xml中一个个的配置。所以开源项目支持springboot是很有必要的。

这些自动装配的顺序，也并不是按照配置的顺序进行的，有先后依赖关系。具体可以仔细研究源码，源码注释有写。

如果有人不知道如何控制springboot自动装配的顺序的话 ，推荐看我之前写的一篇文章，专门针对这个知识点进行了解读

https://mp.weixin.qq.com/s/-7kTj7lWrlmHqjH6Yx2Nfw

那不知道会不会有人问，那dubbo/dubbox，三大日志框架的增强就不需要注册自动装配器么？

这里一一解释：

dubbo/dubbox，在设计时就有基于spi的实现，能够自动识别出扩展的插件，所以无需注册任何bean到spring容器，所以不需要装配。

log4j&logback，字节码模式的话，在springboot/spring启动前就得加载了。下文会说到。所以不在springboot/spring启动阶段装配。至于日志适配模式，由于需要开发者提前替换好相关的encoder，所以日志框架在加载日志配置文件时就会做这件事。所以也不需要自动装配任何东西。

log4j2的设计完全采用插件式，他自己能扫描并识别到相关扩展插件，所以也不需要在springboot/spring装配时干任何事。

Log框架的支持解析

对于log框架的支持是TLog的重点，主要都在tlog-core这个模块中。TLog接入有三种方式，javaagent接入，字节码接入，适配模式接入。接入方式和对应的类，有下图：

其实可以发现，javaagent本质上也是利用字节码的方式进行，区别是，javaagent的jar包外置，不用项目依赖。而字节码方式，需要依赖，并且要在启动类里面手动添加AspectLogEnhance.enhance()代码进行触发。

还可以发现，javaagent模式和字节码模式目前是不支持异步日志的。只有适配模式才能支持。

可能会有人有疑问，上图为什么没提到log4j2呢。

答：因为之前也说了，log4j2是插件形式，从本质上来讲。log4j2的生效方式只有一种，log4j2自动会去检测插件，严格的说，log4j2日志增强的方式不属于上面任何一种。也不需要任何装配，任何触发条件，只需要定义相关插件就可以了。具体log4j2的插件定义在tlog-core的如下包里：

com.yomahub.tlog.core.enhance.log4j2

Log框架中的MDC

TLog对3大日志框架的MDC也有支持，具体三个支持类在以下路径

log4j: com.yomahub.tlog.core.enhance.log4j.AspectLog4jMDCPatternConverter
logback: com.yomahub.tlog.core.enhance.logback.AspectLogbackMDCConverter
log4j2: com.yomahub.tlog.core.enhance.log4j2.AspectLogLog4j2MDCConverter

要注意的是，这3个类，并不是直接对MDC作处理，这3个类的作用是：检测log配置是否用了MDC

如果检测到配置文件有用mdc，则在TLog线程上线文中设置一个标记

TLogContext.setHasTLogMDC(true);

而真正对MDC进行处理的是这个类TLogRPCHandler，这个类是所有rpc调用的一个抽象层，里面有以下代码进行了MDC的处理逻辑：

...
//如果有MDC，则往MDC中放入日志标签
if (TLogContext.hasTLogMDC()) {
   MDC.put(TLogConstants.MDC_KEY, tlogLabel);
}

如果这个标记为true，则用slf4j的MDC API进行设值

RPC支持

TLog对于RPC的支持，主要用到的是各个RPC框架自己的拦截器和过滤器来实现。

dubbo/dubbox

dubbo和dubbox是使用dubboFilter来实现，其原理2者一致。代码也都差不多。因为包路径和个别类命名有区别，所以分成了2个模块，这里放在一起讲

其主要的处理类为TLogDubboFilter和TLogDubboxFilter，之前有提到过，dubbo/dubbox有自己的SPI，能检测出插件。定义dubbo的插件方式如下：

@Activate(group = {CommonConstants.PROVIDER, CommonConstants.CONSUMER}, order = -10000)
public class TLogDubboFilter extends TLogRPCHandler implements Filter {
	...
}

dubbo/dubbox这里分provider端和consumer端去处理，A->B，A就是consumer，B就是provider。2端的处理逻辑不一样。

provider端：接受隐式传参里的参数-->处理参数-->放入tlog的线程上下文-->调用原有业务逻辑

consumer端：从tlog线程上下文中获得参数-->处理参数-->调用远端业务逻辑

feign/http

在spring cloud feign的场景，一般用feign作为consumer，普通的controller作为provider。所以这2个放到一起讲。

feign主要的处理类为TLogFeignFilter，作为consumer端，大致做了如下事情：

从tlog线程上下文中获得参数-->参数处理-->放入http header-->请求http

而Controller处理类主要为TLogWebInterceptor,作为provider端，大致做了如下事情：

从http header中接受到标签参数-->处理参数-->放入tlog线程上下文-->调用原有业务逻辑

自定义标签

自定义标签是TLog中一个特色功能模块，能让用户自己定义标签编入log日志中。

其主要的处理类就一个aop，为AspectLogAop，位置在tlog-core中。

其主要思想就是去切@TLogAspect标签，然后解析相关参数，最后把结果append到线程上下文的标签值中。

这里面涉及了标注的解析，点操作符的解析和值的获取等操作。想弄明白，直接看AspectLogAop这个类就可以了。

其他功能

TLog还有其他辅助功能。

对mq中间件的支持：代码在tlog-core的com.yomahub.tlog.core.mq这个包中

自动打印参数和调用时间：在RPC的filter下面，会有XxxInvokeTimeFilter类

异步线程支持/线程池的支持：代码在tlog-core的com.yomahub.tlog.core.thread中

自定义TraceId生成器：代码在tlog-common 的com.yomahub.tlog.id中

以上所有功能的代码理解，结合着使用文档去阅读理解，应该很容易弄懂，就不作解读了

关于我

我是一个开源作者，也是一名内容创作者。「元人部落」是一个坚持做原创的技术科技分享号，会一直分享原创的技术文章，陪你一起成长。