内容概要

我们今天先从最最常用的平日工作中经常要用到的你的主管、老板让你留文档这种常用技术文档（含设计文档）入手来入门吧。

第一大段-虎头

哎，这个名字起的好。今年是虎年，祝愿各位虎虎生威。

为什么叫虎头？虎头威武吧？虎头是不是很美？它有金黄色的毛发、额头有着明显的“王”字，用国家地理杂志形容老虎，那真是“一头美丽的动物”。

从感观上来讲是不是夺人二目？

老虎吼一声，那是自带次声波的，一般狗啊、猫啊、其它食草类动物包括人类听到老虎如果近距离吼直接四脚是“瘫软”的，是不是。。。“先声夺人”啊？

回到正题来。

业务需求你要对它进行设计、或者是出于某个创新目的你要做设计，上手先说一下这个需求的背景。

业务需求背景属于“虎头”。

你不要无脑只是copy一下业务的需求简介，笔者近10多年来包括接触的好多供应商讲标，一般这个需求背景写的好的往往者是深入研究过业务需求和了解本行业眼下潮流知道基本痛点的，那是一种基于自我理解后对业务需求的“再翻译”。

要写一下：

业务是出于什么目的出的这个需求；
这个需求解决了本企业、运营中的什么痛点；
我是如何理解这个需求的；
我准备怎么去满足这个需求；

这个很重要，这就是“业务理解”能力。我是一个搞技术出身的，可是为什么近10年来变得口口声声业务、业务呢？

哎，各位！再回到我在10年前写过的博客里你们可以去翻一下。什么叫业务：IT界的业务是运用技术手段去解决企业在运营中的重复工作和痛点，为企业在运营和生意上形成不对称竞争优势的手段而己。

我10年前就写过了，对于科学家来说他的业务可能是：天体运动。对于医生来说它的业务是发现早期癌变组织。

业务就是“解决方案”，解决方案不纯粹是打单、跟单、做财务，而是一个企业要如何引流、挣钱、增单的一种“实际操作的抽象逻辑”，这个抽象逻辑去用IT的语言再实现。因为业务本身=技术实现+企业运营抽象逻辑。一切都是业务方案，你把性能提高是为了顶住更多的流量、更多的单量，性能优化其实也是“业务解决方案”，一切都是业务解决方案。

请自动把业务和解决方案划上等号吧！

借此多说一句：运营逻辑=市场销售=挣钱手段。

这点很重要，技术团队的“业务方案”都要符合运营逻辑。如果两者大相径庭，你这个方案是不合格的。那么我要做设计前我写一下我对你提出的业务逻辑的理解。这个理解可以错、可以对、可以有偏差、也可以有争议。

这正是业务和技术相互进一步沟通、融合的手段。我从来没有看到过技术解决方案一次就可以满足业务需求的。

这本来就是一个团队工作，双方就是就这个业务理解和业务需求进行互相进一步探讨才能形成“接地气的解决方案”。

技术通过这个“需求理解”的虎头可以借此告诉业务方，你的这个需求有90%可以满足，有10%因为等等诸因素需要另一种满足手法。

有问题就说，有问题才是好事。碰撞才能出火花！

业务借着技术写得这个“需求理解”也能知道技术是不是可以100%满足或者是有我不知道的坑存在？业务不是万能，业务的话也不是100%必须听，业务也是人，是人他是想不全，是人都有自己擅长的领域和自己不擅长的领域局限。

因此，需求理解是非常非常重要的。

设计原则属于“虎头”

在上手写完业务背景理解后，写上你的设计原则。

什么叫设计原则？为什么这篇要写在业务需求理解的后面。

这叫“因为。。。所以。。。”。因为有了这样的需求，所以我准备使用如下的“方法论”来设计，它们分别为1、2、3、4等等等。。。。。。

不需要多，以1，2，3，4控制在100-150字了不得了。

需求如果不能满足或者业务提出的这个构思有风险也属于“虎头”

前面说了，业务也是人、业务有自己的领域局限。比如说业务对于某个需求存在“网络个人信息安全法”上的知识的欠缺，此时IT有Information Security也有架构，一眼看出你这样做的话或者你没考虑这些因素，这种需求做出来后你的网站都要被“干掉”。或者说你这个需求不能找开发而是要去找大数据找BI否则APP或者网站会被你搞垮。

此时你就需要把这些内容写出来，并且以相关风险，或者是“进一步需要澄清”，或者是“需要业务确认”，然后以1，2，3，4这样的方式列出来就行了。

虎头的内容不会太多。它起到的作用就是：

有事拣重点说；
有问题有风险早点报；
我想要干什么、怎么干抽象总结一下列在最前面以起到重要告知为目的以引发进一步可能的探讨，不要怕探讨，群策群力才能把方案做了更完善；

这也是一种向上或者向下管理方法中的“管理心理学“。

有一些领导或者平级是综合能力专家，有一些是技术专家，它们有时看前面那300来个字就知道你这样走下去是否可行、是否有偏差甚至后面可以不用多看就知道你的思路对不对或者你的方案靠不靠谱，亦或者直接觉得这个需求在眼下来说太占资源又不能带来直接经济效应那也就把优先级降低了。

说白了一点这叫“不要浪费大家时间”。大家想一下，比如说有一个方案，我看过建筑、造房子的方案还，非常非常有意思，给你们说一下：

当地要造一幅48层的标志性建筑，设计书BLA BLA BLA说了一堆有140多页，最后两页告诉你地下土质疏松只适合建造不超过4层楼的房子并附上地质探测报告。140多页啊？come on，一群人要看多少时候？你不能把这件事放在一开始就说呢？那边挖土机已经调了15台过来了都，油费，运费，高速公路过关费。。。唉。。。

还有一件事也是很好玩，一个医生对着家属讲了3小时的近乎于“免疫学入门”级话术，最后只花了1分钟来告诉家属这个人已经救不了了。

你们说，这种“沟通”这种“话术”。。。碰到的很多技术人员如果没有经过专业培训都会陷入这种上手给你BLA BLA BLA，而这样的人如果成为了习惯、不自我认知，随着时间一长、次数一多，领导或者平级的同事真的不需要再多听他说话了或者干脆不再多用他去做设计了。

因此，虎头的本质是体现让沟通更高效。

第二大段-猪肚

当然，猪头猪后半部一般我们是不太会去吃的，至少普通大众是不会去吃的。

大家想想猪肚子，有哪些可以吃的？

麻酱爆肚；
上海还有一道本地名菜叫青椒炒肚皮，大火一开、小锅一翻，那叫一个嫩呀，那叫一个爽口呀，就热吃，咪上一口“石库门”，那叫一个鲜呀；
炒肥肠？霍。。。伴着花椒，炒一大碗，看了口水都流下来了；
夫妻肺片；
猪排，淮海路著名的存在了近90年的老克勒炸猪排+罗宋汤；
里脊肉；
还有很多很多，能举几十种菜出来；

猪肚是不是很丰富哈？

因此第二大段内容叫猪肚，是代表了第二大段里的东西绝对少不了、且很丰富还“很好吃”。

因此我们会把如下内容都归于第二大段中，它们分别为：

1. 技术栈

准备使用的技术栈，它可以为一个“表格”，分成3列：

第1列为：序号
第2列为：使用的技术栈名如：JDK版本、组件版本
第3列为：技术栈说明或者是为什么要用这个组件，很简要的说明一般不超过20个字；

2. 架构设计

有些需求、模块会比较复杂，那么你的架构图是需要上的。

架构图掌握好“组件该有逻辑不该有原则”：

该有，把该有的且一定会用到的按照“上下-南北向”数据流走向、“左右-东西向”横向不同组件间的交互以“概要、粗略”的手法画一下。
不该有，逻辑细节、数据流放到下一章不放在架构图里

（简单架构图示例）

（复杂架构图示例）

3. 数据流

各个需求点每一个需求点的“数据流”，即棱、框、图。数据流很重要很重要，它是代码的一种导读，数据流理解错了开发出来的东西不会好到哪里去的。因此在数据流上是要非常的清晰标注出以下内容：

这个数据来自于前端哪个按钮点下去时触发的然后走到什么地方去。
经过了controller层哪一根api。
落到了哪个service。
在这个service里怎么走的redis、redis里有值如何、没值如何。
匹配逻辑的必要条件Y/N分支。
然后跑到了数据库里哪个表进行了什么样的条件（>1、<1、=101）查询。
图、图片下部居中加括号简要这个图的说明性代表性标题-又叫图标题、图片上完如果这个流程图、逻辑图、数据流比较复杂辅以1、2、3的简要说明。
必须对每一个需求点进行数据流的说明。
当然后期水平高了可以把数据流+泳道就成了流程图又叫“BPM”或者是“Workflow“图，一张图里表示。当然你也要分情况的。如果系统交互一多导致了你的word在15寸屏幕甚至是投影打出来这个字都要凑到屏幕前5公分才看得清，或者把个文档的局部放大300%以后才看得清，这种效果就不好了。
适当切割、适当合并你的图。

（简单数据流图-其实是一种逻辑图）

（复杂逻辑图）

4. 核心技术/算法

有些系统、模块是含有比较复杂的算法的如：卷积神经网络-CNN算法或者是“希尔排序”或者是“令牌环桶限流”。你要写出这个算法、或者是你使用的第三方开源的算法库的调用是什么、为什么、原理、使用场景在哪些地方；

5. POC

poc不是说要求把每个代码都写出来，如果是每一行代码都写出来这就变成了直接上代码了不用设计了。POC指的是一些影响面非常大的、核心的框架级别、原理验证报告放在设计文档上。POC、POC，即Proof Of Concept的缩写。有时一个模块看看很大其实它的核心原理和技术点只有3个POC，那么每个POC不会消耗你3个例子-5天时间的。

举例来说支付超时后的补偿，它可以有周期性跑JOB来补偿也可以有“延时队列”来跑补偿，那么这两者的优缺点是肯定有的。

一个容易造成并发场景下的数据库锁。
另一个高效当然增加了额外的MQ组件但是不会存在数据库在多个应用服务器跑批时互锁的问题。

（POC结果-两种注册中心的POC结果对比）

为了证明这两个优缺点和性能，你是不是需要做一个POC，这个POC当然也要涵盖这两种技术呢？

当然此时因为是POC，你可以模拟数据、模拟场景、代码和工程甚至可以unit test case级别的就可以了；

6. 数据库表设计

请把每一个涉及到的数据库表以如下形式列出

字段名	类型	长度	是否必填	默认值	字段涵义
xxxx	int	8	Y	-	主键，使用分布式自增主键
xxxx	number
xxxx	varchar	32	Y	-
xxxx	timestamp	-	Y	current_timestamp()

如果表和表之间（物理上或者逻辑上）存在ER，那么你必须要画ER关系图，如果你的ER图有多达几十张表，那么请根据“业务领域”分类分开成一个个ER图附上（太多开源工具可以根据数据库表逆向生成ER图，我就不一一介绍了，我还真没看到过有人用手把几十个、上百个表手绘的）。

（ER图示例）

7. 网络拓扑设计图

到了这点我又要说了。我不知道为什么现在的“程序猿”们从不关心网络结构设计的。这个点我不想展开了，TCP导论、TCP概要、TCP原理、网络基础，这些大学都是学的。IP隔离、IP分层、这些是计算机大一、大二的课程，是基础。

至少。。。哎。。。兄弟，你把这些点写了，就是这个组件要用到以下：

几号端口
只进不出还是只出不进还是in & out
TCP还是UDP还是Both

为什么要画这个呢？我看到太多太多。。。真的。。。我这边能看到50%左右的猿或者是一些公司给到的网络拓扑设计上写的是“开放所有端口”。没有分层概念都放在一起好了。没有告诉我哪个部件是最吃流量。也没有告诉我需要百兆、千兆、万兆带宽的。

对于Mbps、Gbps甚至TPS和QPS都搞不清的。

一个正规的企业它至少有“南北向、东西向”的网络分层原则，这是等保2的内容啊更不要说是做电商、零售类的是需要等保三级证书的啊，如果等保证书拿不到这个公司就直接可以“被关门”了。

因此，都是有：“原则上close to all”，而需要时：再“按需开放端口”的。

一个典型的基本防火墙申请是有如下内容：

所以网络拓扑图里至少要包括：

网络的分层设计
防火墙端口列表

（简单的网络结构拓扑图）

要不然：IT运维、DEVOPS自己去设计这个结构喽？那要你架构干什么？要你研发、开发干什么？

要是你防火墙端口来个open to all，直接公司里搞IT Security也会把你“毙”了。

8. 模块、系统达到的性能指标

从不考虑的？是吧？我们坚持的是要“程序员”不要“猿”。

你的设计或者要求达到24*7？10*5？每个接口、API响应时间、多少个CPU、峰值使用内存，这你必须要写的吧？

不写，运维说我给你一台2核2G内存的VM你去用好了。

（一个简单by门店商品查询的性能要求设计例子）

9. 安全设计

非法字符要不不要过滤？你准备怎么过滤？使用前端的javsscript、APP、小程序前端过滤？过滤方法使用“黑名单过滤”还是“白名单过滤”。
验证码重试次数？4位字符还是6位字符？底图打斜杠还是数字错位显示还是点选文字？
至少不要有log4j漏洞吧？
权限矩阵，就是到菜单级别还是按钮级别+角色？还是+用户还是到字段级别权限并且要把敏感字段内容mask掉？
数据查看权限是by省、by市、by部门？
需要对哪些db schema是读还是需要写还是both需要开发？
https还是http就够用？泛域名证书还是单域名证书？
有没有跨域问题？
用jwt还是web basic authentication（用户名密码登录）就够了？
加解密你用bouncycastle还是jdk标准的？密钥算法？长度？

猪肚！对吧？很丰富！

以上9大点把它们写清了。有些图我是有颜色的，甚至画的有点“beautiful”，这些都只是“浇头”，刚开始写根本不需要关注这些beautiful。如何beautiful我会在后续的章节特别花费时间传授。你甚至可以用文字、表格+黑白图，1、2、3、4的讲清，enough了。

第三大段-豹尾

哎，这个“豹尾”很好玩，为什么叫豹尾呢？

大家注意看哈，豹子的尾巴一般是翘起来的，它的尾尖指向了它的“头”。

这叫“点题”、“回到主题”。即：总结啊！

各位看我在写“猪肚”部分时，列了很多点，每一点下面我都会有“说白了。。。”，“总结一下。。。”，“敲黑板。。。”一类的话术对吧？这种就是总结。

你不要写了一堆，最后没有结论。这就不是豹尾了，这是“蛇尾”甚至“没尾”，你以为是诺兰的“烧脑片”留给观众的是一个“开放式结局”呢？

要总结，因为。。。所以。。。因此。。。

这边就是“因此。。。这个东西怎么怎么样，可以怎么怎么怎么满足你的需求”。

千万记得，不要把风险或者根本不可行的这样的内容放于“豹尾”处。

豹尾处可以放上这样的一层意思：“因为基于上述需求、设计。因此我需要多少硬件、开发、资源，甚至需要买点什么样的工具、商业组件”。

所以在豹尾处，我们经常会放什么知道吧？

放项目计划、甘特图；
放财务计划（预算）；
人员或者是团队的组成；
甚至也有一同放上的招聘计划；

领导、董事会、或者相应的leader看完。。。嗯嗯。。。写了不错，不过有几个错别字（领导很喜欢挑错别字）。。。然后拿出笔或者是私人图章来，哈一口气，“梆”一声，那这就给确认了。或者邮件回一个“go”。

这事就搞定了。

总结

当然，上面有一些半开玩笑的话术（当然平时大家也碰到很多哈），设计文档的主要目的就是：

形成团队知识库的积累；
使得企业、团队可持续发展；
想清楚再做（这点是最最重要的）；

因此，一个标准的程序员所需要涉及到的知识、技能点其实也无外乎上述这些“小标题”，可惜的是很少有人并且在我看来少于10%的市面上的公司、团队是这样操作的。

但是我告诉你们呀，BAT等一些公司对于碰到“汇战”、“攻坚战”、“重大项目”、“中型模块开发”时就是需要这些设计的。

并且，一点不夸张的告诉大家：为什么一些公司面试有6-8轮，每一轮就是在面这些不同的点。

随便举例来说，鹅厂的面试好了：socket通讯、TCP原理、C++、数据结构、基本OWASP TOP10、百万级并发秒杀场景设计、4亿条URL里去重。唉。。。就是这些技能点的集中表现。

这是“基本”，基本中的基本。

95-2010年间的“中国程序员”分为4个级别考核，用现在的话说这个证放在现在的作用就是如果你拿到高级等级证书，那么你在北京、上海居住证申请时是可以加分的（现在已经没有了，主要是因为技术已经普及了）。4个等级里的程序员第二个级别（中级）时已经要求到了DB设计、程序设计、数据结构设计、网络TCP原理设计这些基本要求了。

如果还只是认为程序员是增、删、改、查。。。我建议你快点改行去。

现在明白了我说的：计算机、程序员其实是一门“科学”工作，它并不是像现在外面的“沦为了X农”这种东西。你一直以来觉得是“X农”只是因为你没有看到正规的操作而己。

最后是结束本篇内容。后面会进一步讲文档能力=软实力的另外一种表现手法。

程序员文档写作能力(二)-大三段式构架你的文档相关推荐

从程序员到项目经理（二十九）：怎样写文档
在软件项目中,文档既是一项的重要成果,也是项目管理的有力工具.通过文档,可以稳定.明确的传达信息,实现项目内的有效沟通.所以写文档对项目经理来说,是一项必备的技能. 然而很多项目经理害怕写文档,似乎 ...
程序员突破年薪50万的唯一门坎-文档写作能力(一)
第一篇算是一个导论不知道大家有没有经常回溯.追溯或者抱怨过这样的内容. 第一种抱怨:工作了4年.5年,晋升不明显,最最多做到一个小Team Leader,管了3-5个人.跳来跳去工资增涨只不过多个2 ...
程序员初入公司：10大经验让你能力提升20倍！
IT企业普遍有个特点,"把女人当男人用,把男人当**(此处略去2个字)用." 有句俗话说,"男怕入错行",我想这句话其实也同样适用IT女生. 我们可以做个小测试 ...
程序员初入公司：10大经验让你能力提升20倍！ 1
IT企业普遍有个特点,"把女人当男人用,把男人当**(此处略去2个字)用." 有句俗话说,"男怕入错行",我想这句话其实也同样适用IT女生. 我们可以做个小测试 ...
程序员如何坚持写作？
对于程序员来说,总结和整理自己的知识是非常重要的!还记得巧哥之前分享过一篇文章<涅槃重生:我的技术转管理之路>,其中这几年,他就积累了超过 150 篇原创技术文章,在 iOS 技术圈子里面 ...
程序员如何坚持写作？ 1
对于程序员来说,总结和整理自己的知识是非常重要的!还记得巧哥之前分享过一篇文章<涅槃重生:我的技术转管理之路>,其中这几年,他就积累了超过 150 篇原创技术文章,在 iOS 技术圈子里面 ...
如何提升程序员的代码编写能力
啊呀妈呀,那个熟悉的阿朱又回归了,呕心之作,跪了. 一.先列三个常见的开发场景: 1.拿到一个模块详细设计文档,大部分程序员的通常做法就是开始搭建界面代码,然后从第一个按钮点击事件或页面Load事件开 ...
程序员你伤不起（五）大结局
程序员你伤不起(五)大结局到这里,"程序员你伤不起",这本书的大概内容已经介绍給大家了,当然,我里介绍的只是书中的一部分,大家可以找那本书看看. 前面的一些: 程序员你伤不起(一 ...
百万年薪程序员的7点能力
作者介绍 findyi,腾讯.360码农,前哒哒少儿英语技术VP,现任土豆教育CTO. 几周前,微盟爆了个大雷,数据库让内部员工删库跑路.写了篇文章,做了一些我的判断:从微盟36小时故障,谈谈数据安全 ...

程序员文档写作能力(二)-大三段式构架你的文档