【一课专栏】解构ODL引子 - ODL入坑之路·上篇
做为一名无证驾驶ODL这辆SDN战车3年多的老司机，在基于ODL进行商用SDN控制器的研发过程中，总结了一些经验和教训，也有一些心得体会，借这个机会与大家一起交流分享。以下虽非真理和圣经，但确确实实来源于项目实践和个人的点滴思考。在今后的一段时间里，我将会带着我的故事和大家一起学习ODL，帮助大家更好的理解和掌握ODL。
作为成立于2013年的开源项目，OpenDaylight也可以说是网络开源界的一个老兵，如果从定位来讲，官方的解释是“Open Source SDN Platform”，他的落点是“平台”，所以我们如果从平台的维度去理解ODL会看到很多设计之美。然而对于大多数使用者而言，经常会把OpenDaylight等同于SDN控制器，我们后面的章节会对ODL的控制器属性进行讲解，但更多的篇幅会从软件架构设计的角度对ODL平台进行讨论，力图大家能把握ODL的本质。我们这一讲将介绍如何去高效的学习ODL。引子部分将告诉大家一些方法论的东西，也可以说是一些经验之谈供大家借鉴，总共分为文档阅读、源码分析、学习方法、参与贡献四个方面，通过上下两篇文章进行阐述。上篇我们讲一讲怎么阅读ODL文档及分析ODL源码的套路。
一、知己知彼-ODL文档的正确阅读姿势
了解学习一个开源项目就是从阅读这个开源项目的文档开始的。人们说，没有文档的开源项目就是耍流氓，那ODL开源社区是不是也耍流氓呢？ODL开源项目的文档在哪里？都有哪些文档呢？文档质量怎么样？我们应该怎么阅读这些文档呢？下面我一一给大家进行解答。
首先就是ODL的文档在哪里？
官方文档是在ODL官方网站，
另外ODL社区的 官方wiki 上有大量的各个项目，各个模块的各种各样的文档，其中的文档涵盖ODL方方面面。特别的，wiki上还有各种会议上社区核心管理及开发人员做的报告(Presentions)及视频的访问链接。
还有ODL各子项目里docs目录里包含的文档，这里面一般是很有价值的设计文档。
除了ODL官方提供的文档，还有很多其他网站也能搜到大量ODL相关的文档，包括在 sdnlab.com 上还有大量中文的文档。
这么看来，ODL项目还是有很多文档的，但是，从我看来，有文档也不等于就是不耍流氓，为什么呢？因为ODL的大多数文档都有一个很大的问题:陈旧过时，误导新手。因此，从文档这方面来说，ODL社区不是一个大流氓，也至少是一个小流氓。而看到这篇短文的各位都是流氓的受害者，虽然是受害者，谁又让我们就像《色戒》里的王佳芝对易先生因性生情一样，爱上了一个汉奸加流氓呢。
爱上了一个流氓，我们当然也不能只是逆来顺受，我们能采取的措施有两个，一个就是把它变成一个好人，从此我们就能同心同德，比翼双飞了；另一个呢，就是以针对的招式应对之。今天就把本人摸爬滚打，呕心沥血整理出来的阅读ODL文档的四个行之有效的姿势:静思式，走马观花式，颠倒式，推敲式分享给各位，这些不传之ODL心经希望各位珍惜之，践行之。
姿势1-静思式
这种姿势是指我们传统的阅读教科书的方式，即认认真真的从头至尾把文档阅读一遍，该画重点就画重点，我们要深刻理解其中的概念，总结文档的层次结构和中心思想。这种姿势适合阅读的文档包括ODL官方的Getting Started Guide，Installation Guide，Developer Guide里的controller子项目的部分。对于这些文档，阅读前，我们要焚香沐浴(国外不焚香那就点根蜡烛)，集中精神，然后，认真的从头至尾的阅读一遍，掌握理解ODL基本概念，总体架构和核心设计思想，对ODL项目有一个系统了解。但切记一点，最新版本里这些文档也没有及时更新，与最新版本的实际情况会有部分出入，我们只要理解概念的本质与系统总体架构，可不必拘泥于细节。
姿势2-走马观花式
这个姿势是指就随便看看，暂时不需要采取实际行动。这种方式适合阅读的文档包括各子项目的User Guide和Developer Guide，已发布版本的Release Note，将发布版本的Release Plan，wiki上的各项目的Introducton。看这些文档停留随意，深浅自如，感兴趣就多看会，不感兴趣就打个酱油，用到了再深入研究，没用到就走马观花。当然，我们还可以通过搜索关键词功能找出一些我们感兴趣的内容重点看看。
姿势3-颠倒式
这个姿势有点难度，需要我们颠倒过来看文档，反过来思考问题。比如ODL早期版本里的adsal和config subsystem相关的文档，看这些文档时，我们要时时刻刻问自己，这些功能为什么在最新版本里最终完全废弃了，其设计到底有什么问题和不足，而不能仅仅从当时的介绍文档字面上去理解。当然，对于此类文档的阅读，大家感觉方法掌握有困难的话，那就可以干脆不要读了。
姿势4-推敲式
如果各位想在ODL社区的核心项目里有所贡献的话，核心项目里的docs目录下的文档就是必读文档了。这些目录下一般是该项目内的核心设计文档。阅读这些文档，需要大家结合源码，反复对照，梳理总结，消化吸收。此类文档包括yangtools项目里的开发介绍文档，controller项目里的distributeddatastore的设计文档等。
当然，这些姿势技巧只能是临时的妥协，最终我们还是想社区能提供高质量的文档，这就需要我们大家一起努力，改造它(更新ODL过时文档)，感化它(输出对他人有价值的新文档)，让ODL社区的文档变成我们心中想的模样。
二、抽丝剥茧-分析ODL源码的若干建议
要想深入研究学习ODL，阅读分析一些ODL的项目源码是不可避免的，特别是我们在使用或者基于ODL开发碰到bug的情况下，为了定位问题，跟踪分析源码就是我们开发人员不得不做的事情了。但分析ODL这种规模的项目的源代码，对于任何人来说，肯定都不是一件轻而易举的事情。那在分析ODL源码时，有没有一些套路可循呢？我个人基于这几年对ODL项目的跟踪研究和对ODL若干项目源码的阅读分析，总结出了几条建议，供大家参考。
第一步:大处着眼，把握项目的目录结构
分析源码的第一步建议不要直接从具体代码开始，而是先看一下项目的大体目录结构，根据目录能基本猜测出项目主要包含哪些功能模块，如果有项目说明文档，可以对照一下文档。如果能据此列出各功能模块与目录的对应关系，那就最好了。这样，我们能做到对项目的功能模块有个总体上的把握。
第二步:分析测试代码，理清模块间的接口定义
ODL的所有项目的所有模块，基本都有对应的测试代码，包括集成测试代码和单元测试代码。集成测试代码会测试模块间的调用接口，单元测试代码包含对模块内核心类，核心处理逻辑和方法的测试。分析测试代码可以先从执行测试用例，分析用例执行日志入手。然后再修改部分测试用例代码，比如修改测试参数，继续执行并分析用例执行输出日志。通过这个过程，我们能对项目内主要的调用关系和调用方式做到心中有数。
第三步:善用工具，跟踪代码，梳理流程
这一步我们应该能够先根据前两步的分析找到项目执行入口，这个地方要注意，因为ODL是基于OSGi框架的，每个模块的初始化是OSGi框架调用的，所以，每个模块都有独立的初始化入口。然后，需要我们利用开发工具(比如Intellj）从执行入口(或模块的初始化入口)跟踪代码执行。最终我们应该能够画出大致的代码执行流程图。
第四步:阅读代码注释，了解作者设计初衷
第四步也即最后一步，阅读代码中的注释，特别是接口定义与抽象类里的注释，了解作者为什么要定义这些接口和抽象类。然后我们要对照源码，找到对应的实现，如果我们能自己画出类继承关系，那就是基本分析明白了(有可能继承的层次很深，Intellj企业版有个功能可以帮我们显示类继承关系图，很好)。
对于没有使用第三方框架的ODL部分代码来说，上述套路还算是行之有效的。但ODL的源码之所以复杂，另一个原因就是ODL使用了大量的第三方框架和库，比如Guava，netty，akka等等，特别的，akka还是用Scala语言实现的。这给我们学习分析ODL代码造成了一定的困难。既然这样，我们还能咋办呢？如果确实怀疑问题与第三方库有关，那只能把第三方库的源码也下载下来，一二三四，按照上面的套路再来一遍，分析下这些第三方库的源码喽。
总而言之，是你投入在ODL及其依赖的第三方类库的时间和精力，决定了你对ODL源码理解的深度和广度。正如卖油翁给我们的启示:无他，唯手熟尔！
原文发布时间为：2018-09-6
本文来自云栖社区合作伙伴“SDNLAB”，了解相关信息可以关注“SDNLAB”。