泥瓦匠 Java 工作技巧 0520

作者：泥瓦匠

今天给大家分享下我对 API 接口文档小结 & 应用日志链路追踪（基于 SLF4J MDC ）

第一点：API 接口文档小结

API 文档的目的：

• API 是软件系统的重要一部分，子系统之间交互协议就是 API 。那么 API 好，系统复杂度极大降低
• 众多的 API 叠加，就是成功的系统
• 一般性的 API ：Dubbo 接口、HTTP 接口，目的是为了让业务方或者调用方更快更方便更直接的接入即可

API 文档的设计规则：

• 提供清晰的模型 model
  • 调用地址
  • 入参
  • 出参等等
• 简单
  • 比如入参对象，对象里面是常见整形、字符串等字段
  • 入参不要很嵌套，不要让人家用的时候不知道入参传什么
  • 让人家清晰地看到一个调用案例，就能马上写出如何调用这个接口
• 扩展性，解耦
  • 比如一个接口搞定还是两个接口搞定
  • 如果一个接口搞定，极大的加重了这个接口的耦合性，那不要这么做

资料：

• 《深度 | API 设计最佳实践的思考》https://mp.weixin.qq.com/s/qWrSyzJ54YEw8sLCxAEKlA
• API Design patterns for Google Cloud https://cloud.google.com/apis/design/design_patterns

第二点：应用日志链路追踪（基于 SLF4J MDC）

这其实个小技巧。不管单应用还是分布式，当一个请求到一个应用。这个请求在这个应用的调用链路，日志链路怎么更方便的找到？即每一个会话的日志的列表

有人说：每个 log 都透传这个请求的 requesId。没错这样可以，但这样就麻烦了。

基于 SLF4J MDC，利用拦截器的方式去做，就相对来说会比较优雅。

SLF4J 工具类 MDC ，支持 logback 和 log4j，工具的作用是放一些特定的变量值到日志中。

具体操作如下：

1. 新建日志拦截器
2. logback 配置

通过 HandlerInterceptor 或者 Filter 一样的道理，实现日志拦截。伪代码如下：LOG_UUID 就是每次会话的日志的 UUID

public class LogInterceptor implements HandlerInterceptor {
 


 
 private final static String LOG_UUID = "logUUID";
 


 
 @Override
 
 public boolean preHandle(HttpServletRequest request, HttpServletResponse response, Object handler) throws Exception {
 
 String logUUID = java.util.UUID.randomUUID().toString().replaceAll("-", "").toUpperCase();
 
        MDC. put(LOG_UUID, logUUID);
 


 
 return true;
 
 }
 


 
 @Override
 
 public void afterCompletion(HttpServletRequest request, HttpServletResponse response, Object handler, Exception ex)
 
 throws Exception {
 
 // MDC删除
 
        MDC. remove(LOG_UUID);
 
 }
 
}
 

logback 里面配置：

<encoder class="ch.qos.logback.classic.encoder.PatternLayoutEncoder">
 
 <pattern>
 
 %d|%thread|%X{LOG_UUID}|%-5level|%logger{65}|%msg%n
 
 </pattern>
 
 </encoder>
 

这么简单你可得到如图所示的效果：

红圈的就是调用链路了...

快去试试吧。