如何写出一份“有理有据使人信服”的Android项目设计文档

末蓝、 2022-10-17 11:20 193阅读 0赞

在大厂，写得一手好文档是一个非常吃香的技能。这可不只是一个锦上添花的东西，而是很多工程师晋升，打造自己话语权的武器。 我这两年在组内的深刻体会就是，大部分厉害的高级工程师（不包括那些纯混日子靠资历晋升的人），写文档的能力一点也不含糊，很能抓住上级和项目的G点。

![efe878f8e758bb27621e9a793de4de9c.png][]

可能有人会觉得，我技术牛逼就行了，为啥还要提高写文档的能力，有这功夫我还不如多看看源码分析？这是一些初级或者刚入门的工程师的普遍的困惑。这是因为大部分刚刚入行的朋友有一个很深的误区，就是他们以为做软件工程是一个和计算机打交道的工作，其实不然。软件工程不只是和代码打交道，更重要的是和人打交道，是一份社会性质很强的工作。在大部分公司里面，尤其是大厂，牵涉到的人，组，都是非常非常多的。在小厂，人与人之间交流意见和设计可以口口相传，心领神会，但是一旦人开始多了，就只能靠文档了。除非你可以厉害到一个人把所有代码撸完，不然还是最好老老实实的夯实自己写文档的能力。

如果你有写技术博客的习惯，那么恭喜你，相信你已经对如何抓住文档受众的技巧有所了解了。这对你在大厂生存有很大的帮助。如果没有也不要伤心，这篇文章就是为你精心设计的。

在这篇文章里，我会大致的把一份安卓的项目设计文档的骨架，和一些我工作中实际遇到的正反例都列出来，方便大家以后在工作中实践。

### 设计文档的结构 ###

一个好的项目设计文档，其实有一定的模板可以参考的，不过不管模板怎么变，大致都需要有以下几个大框架

> 1.  **项目背景**
> 2.  **项目术语**
> 3.  **技术挑战**
> 4.  **完成要求**

> 4.1. **App性能要求** (可选)

> 4.2. **App Size 要求** (可选)

> 1.  **现有架构**(可选)
> 2.  **建议架构**

> 6.1. **引入的第三方框架/SDK的简介** (可选)

> 1.  **开发时间线**
> 2.  **其他可选架构**(可选)
> 3.  **参考文献**

咱先从项目背景开始聊

### 项目背景 ###

如果大家面试次数够多，应该会有听过一个叫STAR原则的东西，就是介绍自己项目的时候要遵循Situation(背景)->Target(目标)->Action(行动/做法)->Result(结果)这样的顺序，尽量做到简洁。

同样的，项目背景的介绍就是对应了这个STAR原则的S，也可以说是项目的动机，为什么要做这个项目。

这个背景和动机可以是一个产品产生的动机。比如说`抖鹰`的产品经理发现竞品`快脚`发提供了一个新的视频滤镜，而且这个滤镜在竞品`快脚` 中迅速攀升到用户热度的第一位了，基于我们在产品的数据分析中blalala。。。于是我们也要做这个滤镜。这就是一个简洁明了的项目背景。当然这个背景也可以是一个纯技术方面的问题，比如架构的升级等等，当然如果是架构的升级，那需要在背景里面简单的介绍现有架构的大概的一些局限性(我们下文会提到)。

本人阅读过的一些经典反例就是，背景介绍的第一句话上来就开始直接飙产品/公司内部的一些黑话，比如某个sqlite 的 database的某一个col有问题啊，或者是公司内部的一个SDK的限制等等。这些都是技术细节，不是项目大背景。提前把这些细节说出来是没法在第一段就抓住读者的眼球的，这会让读者失去仔细观看全文的热情，导致最后你的设计文档可能收不到任何有意义的反馈。

### 项目术语 ###

这一部分就更重要了。项目术语这个部分必须要尽可能的把设计中涉及到的：

1.  新引用的SDK/框架
2.  项目之前没用过的语言
3.  项目/公司内部工具,服务
4.  产品本身的组件Component.

都过一遍，尤其是对一些刚刚进组的朋友，这对他们会有很大的帮助。很多刚刚入职的朋友初来乍到，可能也不太敢在研讨会上问问题，阅读没有项目术语的文档对他们可以说是直接劝退的。作为一个往高级工程师方向努力的朋友们，扩大自己在组内影响力也是一个至关重要的点，如果你的设计文档可以对初级工程师/刚刚进组的朋友更友好，那么你已经成功了一半了。很多在组里面待了很久的老鸟会懒得在`产品本身的组件Component`解释太多，因为他们想当然的会觉得这是一个他自己每天都接触的组件没有必要解释。这其实是不太好的，因为你的文档不是给自己看的，而是给其他组员，甚至老板(老板很多情况下是不了解产品的技术细节的)。

比如你在新的项目中打算使用GraphQL这个查询语言和相应的框架。那么最好的做法是先在术语环节介绍一下:

![ecd5c210ac787891716445cf3367d4a6.png][]

> 1.  GraphQL -> 是一种针对图状数据进行查询特别有优势的查询语言
> 2.  GraphQL Query-> 一种类似于HTTP GET的GraphQL 请求，用来查询后端数据
> 3.  GraphQL Mutation-> 一种类似于HTTP POST 的GraphQL请求，用来修改后端数据
> 4.  GraphQL Subscription-> 一种建立在客户端和后端之间的长链接，用来监听后端数据变化请求，大部分GraphQL框架用websocket来实现

有了这上面的介绍，相信你在接下来设计细节说到Query/Mutation的时候就不会有人懵逼了。

### 技术挑战 ###

这个环节就比较简单了，把该项目的技术难点都列举出来，但是有一个问题要切记:

**不要贴源码！不要贴源码！不要贴源码！**

很多朋友，包括在写博客的时候都是一言不合直接复制粘贴源码，这样的做法是非常让人讨厌的，说白了就是偷懒，连精炼一下源码，哪怕做一份伪代码加comment的功夫都不肯下。还是那句话，文档是写给别人看的，不是写给自己的。

这里我用KunMinX https://juejin.im/user/1081575170900958 大哥的博客里面的伪代码做正面 例子,大家如果看到这一份安卓事件分发的源代码 （KunMinX 大哥如果你看到了觉得不想自己的例子被放进我的文章，请联系我，会及时删掉并替换，在这里先感谢你）:

@Override
        public boolean dispatchTouchEvent(MotionEvent ev) {
            if (mInputEventConsistencyVerifier != null) {
                mInputEventConsistencyVerifier.onTouchEvent(ev, 1);
            }
            // If the event targets the accessibility focused view and this is it, start
            // normal event dispatch. Maybe a descendant is what will handle the click.
            if (ev.isTargetAccessibilityFocus() && isAccessibilityFocusedViewOrHost()) {
                ev.setTargetAccessibilityFocus(false);
            }
            boolean handled = false;
            if (onFilterTouchEventForSecurity(ev)) {
                final int action = ev.getAction();
                final int actionMasked = action & MotionEvent.ACTION_MASK;
                // Handle an initial down.
                if (actionMasked == MotionEvent.ACTION_DOWN) {
                    // Throw away all previous state when starting a new touch gesture.
                    // The framework may have dropped the up or cancel event for the previous gesture
                    // due to an app switch, ANR, or some other state change.
                    cancelAndClearTouchTargets(ev);
                    resetTouchState();
                }
                // Check for interception.
                final boolean intercepted;
                if (actionMasked == MotionEvent.ACTION_DOWN
                        || mFirstTouchTarget != null) {
                    final boolean disallowIntercept = (mGroupFlags & FLAG_DISALLOW_INTERCEPT) != 0;
                    if (!disallowIntercept) {
                        intercepted = onInterceptTouchEvent(ev);
                        ev.setAction(action); // restore action in case it was changed
                    } else {
                        intercepted = false;
                    }
                } else {
                    // There are no touch targets and this action is not an initial down
                    // so this view group continues to intercept touches.
                    intercepted = true;
                }
                // If intercepted, start normal event dispatch. Also if there is already
                // a view that is handling the gesture, do normal event dispatch.
                if (intercepted || mFirstTouchTarget != null) {
                    ev.setTargetAccessibilityFocus(false);
                }

是不是瞬间没有任何兴趣了？请注意我还没有全部都复制上来，就只是一小段而已。

再看KunMinX大哥的精简版伪代码:

https://juejin.im/post/6844903894103883789\#heading-1

![47447823cad1e5334faa0fb304404e91.png][]

是不是瞬间就豁然开朗了。

写文档也是这样，如果我是审查者看到上来就贴项目内部的源代码的设计文档，对不起，我会直接打零分，贴源代码的设计文档，像极了初中的时候为了凑八百字而生硬的加排比句的作文一样，看起来很丰满，其实都是骨头没有肉。当你自己想钻研技术的时候，一行行的研究源码是没毛病的，但是如果你是要分享给他人的时候，千万别直接复制粘贴。

### 完成要求 ###

这个环节也不多做介绍，这是和公司/产品内部的需求有关系。比如你做结构的修改，做完之后是否会影响到原有的开发流程，如果有，是否会严重的影响，这些都是需要列出来的。

### 现有架构和建议架构 ###

一提到架构，很多人都会觉得很虚，感觉无从下手。其实在这方面，流程图和组件通信图都是很好的帮手。有时候可能自己会觉得无从写起，但是其实只要把流程图/组件通信图一画，其实就豁然开朗了。

这里我以我司的一个最近刚刚开源的移动开发框架 Amplify(https://aws.amazon.com/cn/amplify/)为例。

![38c8e501c1d353ca42ef232123f46d4a.png][]

假如我在我的最新设计中提议使用这么一个新的框架,那么首先我得阐明这个框架是做什么的(PS:这是我自己总结的，和公司文案无关):

> Amplify Mobile sdk 给客户端提供了一套离线应用解决方案，它包括了离线存储，和服务端数据增量更新，还有身份验证，日志发送等等移动端所需的功能。该框架以GraphQL语言为基础，通过WebSocket保持和服务器端的实时连接，还有基于时间戳的增量/全量更新保持客户端和服务端的数据一致。

好了，那你们组的高级工程师可能会问，那这个Amplify Mobile SDK内部是大概怎么实现离线还有和服务器端数据一致性的呢？

这个时候组件通信图就派上用场了。话不多说，先上图 (这里我们用 https://arcentry.com/app/ 来做示范，这个工具提供了很多AWS相关的服务组件图，比较好上手)。

![91062157ddec0e2316dbdc912afe8bc9.png][]

同时，让我来以一个设计者的角度来说明这个架构图大概内容:

> 1.  在Amplify Android SDK的架构设计上，每当用户在客户端进行数据操作(CRUD)的时候，Amplify都会通过Data 组件把用户本地的数据先进行修改(Model DataBase),在修改数据的同时，会把每一次CRUD操作进行序列化，存储在另一个Mutation数据库里面。

> 1.  Amplify Android SDK的Engine组件通过Observer模式，注册了一个数据源变化的观察者，如果有新的Mutation，Engine就会从Mutation数据库将Mutation取出并发送到API组件，API组件再将其封装成一个GraphQL的Mutation 请求发送至后端

> 1.  图中的左边的区域为客户端，右边为后端

有了组件通信图，描述架构就变成了看图说话，小学四年级咱就学过了，非常轻松！

从以上的图和描述中，我们队友们就应该知道，数据存储在Sqlite 数据库内，同时保存了数据本身和对数据操作的序列化对象，并且他们也会有更多的问题,比如说

1.  既然有Model数据库，我们怎么定义客户端的model，model长啥样，是Amplify有工具自动生成，还是必须我们手写?
2.  既然是先写入数据库再和服务端更新，万一网络连接暂时不可用怎么办？Amplify怎么处理数据不一致？

这些都是文档阅读者在阅读完你写的简明易懂的架构简介之后会问的问题，是一个顺其自然的事情，当他们问到这里的时候，你应该感到高兴而不是紧张害怕，因为这说明大家把你的文档读进去了，而不是敷衍和不耐烦。能让阅读者和作者产生互动的技术文档，是好文档！

有了架构图，再加入一个流程图，就更棒了。这里我会用 http://www.plantuml.com/ 作为师范工具来构建流程图。

还是以Amplify为例子。既然我们决定使用Amplify了，那使用Amplify前后我们的代码和架构会发生很大的变化么？

**假如我们的产品是一款点餐的软件**，我们的Model(数据模型)是一道一道的菜，同时菜本身可以修改相应的元数据，比如辣的程度，是否加入了配菜等等。每当我们把菜加入到购物车的时候，不同设备同一账号的软件的购物车应该出现相同的菜品。

在使用Amplify之前，我们都是手动存入自己设置好的数据库，然后马上发送给服务端，来更新购物车的。

![f7633e6a5bce495559129566edcaf278.png][]

在使用Amplify之后，我们不需要存进自己的数据库了，而是直接面向Amplify的Model编程

![a60bf5b29719d69bcba61edc78c1e1c6.png][]

如果大家觉得对比还明显，咱再来一个一刀切式的对比，把两幅图放在一起，再使用中间切割的方式：

![6df8450393a3fa7dcebe7b7ac8ff3d1a.png][]

通过上面这个对比图，阅读者可以很清晰的看到，在现有的设计中，我们完全没有修改Adapter和View之间的通信方式和流程顺序，仅仅是修改了Adapter和数据源的操作，从原来的Adapter修改本地数据库和发送网络请求两手一把抓，变成了现在仅需向Amplify SDK修改模型Model数据。

配上组建通信图和流程图，可以让你的文档不只是有枯燥的文字，使阅读者有更大的想象空间，加上和原有架构的对比，高级工程师看了也会直呼你是老司机。

![ff5195186c12b9e56c6f6ceded891f08.png][]

### 开发时间线 ###

开发时间线一般需要和产品经理协商，但是一个很重要的小技巧是，当你设计你的开发时间线的时候，最好是通过功能/产品发版的时间进行**倒推**，算时间线。

比如，我要2020年10月一号正式发版，那么假设我们Beta内测需要两个周，Beta bug修复一个周，QA测试内测版release两个周，那么我们开发的Code Freeze日期就定下来，大概是八月26号左右。有了Code Freeze日期，设计，开发周期就有了：

<table> 
 <thead> 
  <tr> 
   <th>开发项目</th> 
   <th>日期</th> 
  </tr> 
 </thead> 
 <tbody> 
  <tr> 
   <td>正式发版</td> 
   <td>10/01/2020</td> 
  </tr> 
  <tr> 
   <td>Beta bug修复</td> 
   <td>09/24/2020</td> 
  </tr> 
  <tr> 
   <td>Beta QA</td> 
   <td>09/10/2020</td> 
  </tr> 
  <tr> 
   <td>Beta 发布</td> 
   <td>08/27/2020</td> 
  </tr> 
  <tr> 
   <td>Code Freeze</td> 
   <td>08/26/2020</td> 
  </tr> 
  <tr> 
   <td>开发</td> 
   <td>07/26/2020</td> 
  </tr> 
  <tr> 
   <td>设计/文档</td> 
   <td>07/15/2020</td> 
  </tr> 
  <tr> 
   <td>技术选型调研</td> 
   <td>07/01/2020</td> 
  </tr> 
 </tbody> 
</table>

### 其他可选架构 ###

有时候，对于同一个项目，同一个功能，还有其他的第三方类库或者结构可用，那么最好也要列举出来，同时比如各自的优劣势，这是给你选用的架构的很好的背书。这里就不列举例子了。这个环节也可以参考之前讲过的架构描述方法。

### 参考文献 ###

是的，虽然咱不是写论文，但是肯定多多少少有引用到一些文章，技术博客，哪怕是第三方类库的官方简介，也都要放在文末，以供其他组员参考。同时这也是一个霸气的结尾,“老子调研的这么辛苦这么尽责，看了这么多文献，你好意思反对么?”,此时无声胜有声。。。。。

![4550b8b71e8f73d1ed009cca288a412e.png][]

### 最后。。。。 ###

其实写文档就像写作文一样，是一件非常消耗时间，并且需要积累的过程。我记得大二考雅思和GRE的时候，写作都是拿最低分的一part，当时的大学英语老师和我说，写作就是一个输入和输出的关系，你需要有100%的输入，才可能有10%的输出。要看很多，练很多，才可能有你练和看的那10%的成果，是一件非常辛苦的事情。但是在公司里面，写好了文档真的是一件对职业发展非常有利的事情。在谷歌的朋友曾经和我说，他在Android Support Libray组工作(现在是AndroidX了)，因为support library太复杂，而且需要很强的backward compatible(向后兼任)的设计，所以经常性的是改几行代码，写1000字的文档和申请，在谷歌，写文档成了高级工程师常规操作，我相信大部分大厂也都是一样的。所以希望大家都能多写，多练，多拿反馈，不要害怕一开始被人批评或者吐槽，这些都是你的垫脚石。

[efe878f8e758bb27621e9a793de4de9c.png]: /images/20221014/ff63159292784de59f7821a2e2956f92.png
[ecd5c210ac787891716445cf3367d4a6.png]: /images/20221014/f9866ebb41d24800ace4be84964790e3.png
[47447823cad1e5334faa0fb304404e91.png]: /images/20221014/492830ccf38848e0b980e2860fe9b5e4.png
[38c8e501c1d353ca42ef232123f46d4a.png]: /images/20221014/19fa6cb779bc482599ffcd59192384b6.png
[91062157ddec0e2316dbdc912afe8bc9.png]: /images/20221014/e0a42cdb796741bfb87d8fd9f291e90c.png
[f7633e6a5bce495559129566edcaf278.png]: /images/20221014/711ccf1b52964dbf95369ec5707319fb.png
[a60bf5b29719d69bcba61edc78c1e1c6.png]: /images/20221014/a8a868bec4034cdaaafa17e29d98e1f4.png
[6df8450393a3fa7dcebe7b7ac8ff3d1a.png]: /images/20221014/61f3b13c56a140c5abbca9ae170f4b40.png
[ff5195186c12b9e56c6f6ceded891f08.png]: /images/20221014/87b2fb8969684bb3ab5177aabcd0c913.png
[4550b8b71e8f73d1ed009cca288a412e.png]: /images/20221014/24837130da764c0d952d5903bff838e1.png