如何写好面向新人的开发文档

前言

大家在进入公司的时候，或多或少会接触到公司或者来自前辈的文档。文档水平层次不齐，好的事无巨细，层次清晰，拉跨的可能就像正确的废话，正确的说了正确的话。文档形式也是多种多样，word、markdown、云文档、知识库等等，我觉得这东西最好上云，好修改好共享。我公司呢，是有个知识共享文档平台供大家发文互相分享，但你懂的，这玩意上一次更新在八月一。更新频率低就是很大的问题了，而且文档质量嘛，也只能说一般，除了必要的一些中间件和框架简要说明，和一些架构说明还算有点意思，其他的还不如平时看的技术公众号文章。基于种种原因，我选择自己来写一篇开发文档，真正的开发指导说明书，拿着能用的那种。

文档迭代过程

最开始想着要写文档，纯粹是一腔热血，我来创造我来写。反正就开始了，刚开始写的很简单啊，因为就是我一个人看，相当于一个我的一个快捷开发备忘录，都是我自己的一些小套路。后来我写了自己的spring boot starter，当时想着要规范一点放到Github上，就写了一个Wiki。21年中的时候写了一个单点登录组件，为了让大家能用明白，就写了一个使用说明。后来我想着要统一技术组件，就把我自己的工具组件的说明合起来变成了一个初版的开发文档。
初版比较简单，就是一些常用的开发工具以及单点登录组件的解析，更多的还是靠口口相传或者开发者自身的能力。慢慢的我开始做统一的技术规划，因为这个门户网站，属实是需要一套统一的技术架构，不然错误莫名其妙，不同的人会出现不同的问题，我就一个人疲于奔命，独木难支。所以我做了一个开发模板放到Devops平台，主分支是我的，大家可以在上面二开，并且对开发文档进行了扩展，更多维度的提供开发建议和开发样例。对必要以及基础的模块做了统一的开发规范，比如Excel的相关操作。同时增加组件的引入，从源头控制开发工具的版本以及规范，比如redis编码、Kafka生产和消费。
完成了以上的工作之后，此时将开发文档更名为开发百宝箱。为啥这么改名呢？是因为我觉得我想提供给大家的是能开箱即用的实用工具，而不是一些没啥卵用懒得看的规范或者废话。规范这东西我希望能从框架或者组件去控制最好，不能仅仅依靠开发自身，比如我自己就会不想规范随便写，一着急了BUG频出也很正常，规范这东西我放在那里想起来了我看一下，记住了就记住了，用不用那不一定。现在开发百宝箱已经属于组内必看文档，新人来了先看，能快速了解技术架构以及扩展组件的技术栈和用法，配合老项目和同事带能一两天内迅速上手开发，效果还是比较好。同事有问题问我，我也是让他先看开发百宝箱，实在没有了我才帮忙处理，如果有必要我也会添加到开发百宝箱中，作为问题记录。

文档正文书写

规范和环境配置

开发肯定是要用规范的，没有规矩不成方圆，开发的良好素质就来源于对规范的理解和应用。好的程序员一定能写出大家都能看懂的代码，大家都能看懂，那就需要一套行之有效的规范，这里我首推阿里的开发小册，非常详细。在此基础上可以增加一些公司独有的规范，比如安全、代码质量，这里简要提几个点，从公司开发规范摘出来的。环境配置肯定是必须的，不然谁知道你要怎么玩，又不是开源项目，肯定会有一些保密或者瞎逼操作。不写出来，谁知道怎么开发项目，万一岔劈了，不是白干了。

• 开发环境配置—JDK版本、集成公司框架、集成公司开发环境
• 软件开发过程中的注意事项和规范要求—代码规范、数据库规范、组件引入规范、单点登录规范、代码质量分析
• 如何测试—单元测试和功能测试、测试工具
• 如何部署—Devops操作指南，模板项目
• 如何发布上线—这个值得单独拉出来，毕竟谁也不喜欢生产事故
• 运维记录—比如禅道或者飞书企微自带的一些记录工具

如何创建一个新项目

其实这个还是蛮重要的，值得单独领出一个模块来好好写写，图文并茂最好。下面提几个要点，当然这也看公司的技术基础设施完整度，根据公司情况写即可。

1. 新建服务—这个需要项目负责人申请，在注册平台去注册服务，填一堆服务的基本信息以及负责人的信息
2. 新建应用—使用Devops平台的模板项目去初始化项目，填一些服务的基本信息
3. 环境配置—Devops上面的部署环境配置等等
4. 拉取代码—这一步就是在模板项目上定制化修改，标注下哪些配置需要修改，可以改成啥样

说的比较简单啊，其实会比较复杂，看公司。比较好的就是一键全解决，做的粗糙的可能就是每一步都得人看着，稍不留神就弄错了。

模板项目

• 模板地址—模板的下载地址以及使用方式
• 模板分支—标注分支作用，比如master就是主分支，由我来做持续更新，其他人根据规范在主分支基础上建立新分支
• 模板依赖—注明重要依赖的作用以及版本号
• 模板包结构—提前建好包结构，并在文档注明，比如service、controller、mapper
• 模板基础功能—模板提供什么样的基础功能，已经内置了哪些东西。比如公司框架、扩展组件
• 模板通用案例—一些提示性的案例，比如controller怎么写、异常怎么处理、远程调用怎么写

常用开发工具框架介绍

这个就是一些推荐用的工具或者框架的简单介绍和使用方法，可以贴一下官网或者粘贴一些代码中的真实案例辅助开发同事理解运用。下面推荐一些我常用的小工具

• 参数校验—@Valid和@Validated，Hibernate-Validator提供实现，Spring boot集成注解式校验，配合全局异常监听使用更佳
• 缓存应用—我个人推荐本地缓存用Caffeine，远程缓存用Redis+操作框架Redisson
• 加密工具—当然是推荐Jaspyt啦，配置加密正常加密都可以
• 导入导出—EasyExcel已经牛上天了
• 代码生成—ORM框架我们用的是Mybatis，增强框架我用的是Mybatis-Plus，所以代码生成也是用它自带的，生成模板我稍微改了改。
• …

单点登录

单点登录这一块之所以单独列出来是因为属于基础组件。我希望开发同事能不仅仅知道怎么用，还要知道里面的设计原理，一旦发现问题能够自己通过源码找问题，而不是一个劲的问我。在刚开发完单点登录模块发布测试的时候，包括后面上线后，直到现在也还是不断地有人问我相关问题。恰逢公司更新新网关，两者叠加导致问题频出，有写错的也有程序错误的，有我的也有网关的BUG，找起问题来特别麻烦。为了我自己梳理单点登录逻辑，也为了同事们少给我整点活，我选择写一篇详细的设计文档出来，后端思想-单点登录组件的设计与思考。(⊙﹏⊙)，写完了之后吧，要说有效果吧，好像有点又好像没有，对我有点用，同事依旧直接问我，摆烂。这个模块我是这么写的

• 设计思路介绍—就是贴了下链接，里面有我的设计流程图、思路、自问自答和版更记录
• 使用方法—依赖和配置项，比如配置某个接口跳过单点登录
• 内置实用工具介绍—比如如何获取当前登录人的信息

中间件使用

这一块主要是针对引入的中间件做一个配置和使用说明，因为做了本地化改造，所以还是有必要说说怎么用的，需要配置什么参数。我是引入了分布式事务Seata、定时调度Elastic-Job和我自己设计开发的日志收集系统。

• 环境概述—主要写清楚中间件的部署情况，有没有环境隔离，部署在哪个服务器，几个节点这种基本情况。
• 配置说明—常规的就是配置文件中增加配置项，特殊的比如Seata需要额外在数据库增加表
• 使用方法—给个图文并茂的例子，描述清楚怎么用。代码怎么用，部分有控制台的怎么用也要讲明白
• 项目依赖—这个主要是写一下中间件引入时自带了什么依赖，为了避免依赖版本冲突，还是有必要写一下的
• 注意事项—我自己写一些使用的注意事项以及官网的提示，再补充同事在使用时遇到的问题
• 版更记录—一般中间件还是要本地化改造的，主要是为了统一开发规范，因此组件的版更记录要写下来给有需要的人看

技术工具组件

这个就没啥套路了，就是版本更新记录、使用说明之类的。就重点说说，我提供哪些工具，详细的可以看这篇文章，Spring Boot Starter开发指北(案例+代码地址)。

• Redis工具—推荐用Redisson操作框架，我写了些初始化配置，内置了一些默认参数。
• OA信息查询API—一个静态API调用类，主要是远程获取公司HR信息
• 消息通知API—静态API调用类，内置了对公司邮件、通讯工具API的封装和默认配置，带点业务封装
• Spring工具类—常见的获取Bean之类的小工具
• 数据脱敏—封装Jasypt，对接口入参出参和配置文件的加密解密，同时扩展Mybatis插件进行ORM层的加密解密
• 缓存工具—将SpringCache替换为Redis，增加默认参数配置。同时提供通用配置的Caffeine
• 业务小工具—发号器、限流器、幂等性校验器
• 线程池配置—提供基础的CPU和IO型的线程池对象，动态线程池引入外部框架
• …

业务工具组件

• 数据校验优化—开启Validated快速失败机制，提高校验速度。
• Mybatis Plus配置—常规配置封装，扩展插件例如自动注入字段
• Excel工具—该模块设计详见往日文章
• 异常规范—异常类、错误码、全局异常监听
• …

解决方案汇总

这个部分就是我之前写的那些有意思的设计文章或者解决疑难杂症的文章，发出来让大家思考，同时给我反馈促进大家进步。比如之前的写SQL优化的从零开始的SQL修炼手册-实战篇，多线程开发的性能优化-如何爽玩多线程来开发，就不多发了，喜欢的可以翻翻我之前的文章。

写在最后

回头看下来，感觉这个结构还是井井有条的，希望对大家的文档有所帮助。我最开始进公司的时候，还没有这些文档，可能算有个雏形，规范是有的，但是对新人来说意义并不是很大，我要的是具体怎么做，就这么简单。此后经历了痛苦的成长期，比如基本没人带我，纯靠自学，正式上班第三天开始开发新项目。于是我开始厚着脸皮问身边的前辈们，因为没有可靠的文档，纯靠口口相传和看老项目代码，让我非常难受，又菜又急。
所以平时我就记录下问题，慢慢总结积累，后来过了一两年我就开始琢磨着写一个正式的开发文档，因为组内迟迟没有，所以我一开始没打算公开，男生自用来着。团队内部工作压力也是很大，从我来了之后，三年了，没有新的应届生，只招社招的，我成了我们团队最后一届应届生，也是离谱。莫名其妙的，开始有同事问我问题，找我解决疑难杂症，太多而且重复性较高，忍不了了，就把文档发出来放到大组内，方便整个大团队的技术架构统一。效果还是蛮好的，离谱且重复的问题少了很多，一句看文档就能解决很多问题，写这篇文章也是记录下我写开发文档的整个过程，留个记录。如果能对相同困境的读者有所帮助，那是再好不过了。下一篇，应该是难点的盘点了，这个比亮点感觉还难写，折磨。最近新项目还要学习一些新技术，写文时间再次压缩，那就半个月后见吧！