作者：泥瓦匠
“路漫漫其修远兮，吾将上下而求索”
今天给大家分享下我对 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，工具的作用是放一些特定的变量值到日志中。
具体操作如下：
- 新建日志拦截器
- logback 配置
通过 HandlerInterceptor 或者 Filter 一样的道理，实现日志拦截。伪代码如下：LOG_UUID 就是每次会话的日志的 UUID
logback 里面配置：
这么简单你可得到如图所示的效果：
红圈的就是调用链路了...
快去试试吧。
由于能力有限，若有错误或者不当之处，还请大家批评指正，一起学习交流！
-The End-
