模块说明模板

前言：

最近在做团队项目的架构改造时，从改造之初的评估，如是否有这样的必要，改造价值，当前的问题等；到项目该怎么架构、功能划分，任务分配；模块的评估设计、评审。切切收获很多。

现在是都是团队一起来开发一个项目，会遇到以下问题：

       1. 如果整个项目架构模块不清晰，就很难划分责任、任务到人；

       2. 同时开发，互相干扰的可能变大，出现问题的可能性变大。

       3.代码纠结在一起，会出现互相干扰理解的状况，维护成本增加。

       4. 功能扩展难，易引起其它问题。

这时就需要模块化我们的项目，以解决这些问题。如有以下这些优点。

      1. 沉淀稳定化的功能模块，可供其它项目使用。也会减少其它项目的干扰。

      2. 模块化，形成规范化的文档，为交接、维护、任务责任划分打下基础。

      3. 模块化测试，能更快的保证某一块的稳定性、性能提升。

下面内容是模块说明的模块，以便大家参考。

XXX模块说明

---

【中括号中的内容是提示性说明，具体模块说明书的正式文档中应该删除。】

【模块说明书是写给别人看的，理应尽量详实和表述清楚。】

【模块处在不断改进的过程中，模块说明书也应及时更新】

【每个模块都有自己的特征、特质，模块请根据自身的特点来增加或删除某一些小点，使得模块说明书更加的详实。】

 

变更记录

【主旨是：谁在什么时间更新了什么内容。以便备注查找跟踪。】

序号

更新内容

负责人

更新时间

1

XXX

XXX

XXX

2

 

XXX

XXX

3

 

XXX

XXX

1 需求分析

【主旨：明确模块的需求和目标，这样才能确定模块是否有存在的必要。这是模块设计、开发的前提。】

1.1    问题

【主旨：分析问题，明确模块是否有必要封装，进而选择模块的封装形式】

【目前模块的三种封装形式：

1.       封装，不提供源码给第三方使用。

在主体基本无变化的情况下使用。

2.       不封装，仅有演示demo,演示某一功能块怎么样使用，简化学习成本。

已有方案已经封装较好，没有多余的封装，通过demo演示方案所有的调用方式，避免文档不足、不详实导致实施人员到处查找资料的耗时，提高学习效率，降低学习成本。

3.       封装主体，提供源码给实施团队。

涉及到界面的的封装，在不同的业务场景可能会有定制需求。封装主体流程并提供源码给实施团队。实施团队直接使用，或根据需求修改定制源码。

】

 

【下列问题1、问题2是必须思考的问题，这决定了模块的封装形式的选择。】

【问题1：需不需要，重要性是多大？

模块在哪些场景下使用，是必要场景，还是可有可无的使用。通过查看，明确模块的重要性。】

【问题2：是否有必要封装？

模块在未封装前会遇到哪些问题或特殊需求，是否是到了必须解决的地步，封装后是否可以解决或避免这些问题，或带来哪些明显的好处、优势。】

【其它问题：关于模块的其它问题。

根据模块自身特点，选择一些重要的问题进行回答。如：模块有哪些第三方的解决方案；为什么使用第三方解决方案；该怎么选择等。】

1.2    调研

【主旨：寻找模块的解决方案、设计思路和设计方案】

【理应避免闭门造车，通过多看、多问、多思等途径来寻找模块的解决方案、设计思路和设计方案。】

 

【内容一：模块重要的基础概念、基础知识

模块重要的基础概念、基础知识是每个维护者必须知道的知识。简单介绍或指引学习资料，普及进一步学习的基础。】

【内容二；解决方案的基本思路和理念

了解并总结一些其它人的解决方案的思路，优缺点等，开阔认知和思路。】

【内容三：同类产品是怎么操作的

查看同类产品是怎么选择的，理由是什么。】

 

【如网络模块：通过代理发现，招商等银行的网络请求的安全是通过双向验证完成的。双向验证、单向验证、不验证的http优劣势，最终模块会选择什么样的解决方案。】

【如网络模块：因为银行的安全等级要求，要求使用Ynet平台的项目都必须做双向验证，以保证安全性。】

1.3    结论

【主旨：给出模块需求分析的结果】

 

【模块概述：用一句话对模块进行概述或定义，给出清晰的界定。

封装方式：采用哪种封装方式。

使用方案：说明模块选择的实施方案或核心。如使用哪个第三方解决方案。

选择理由：说明选择相关方案的理由

模块目标：通过模块封装能达到的目标

模块构成：整个模块构成的部分有哪些？必有的是演示demo和模块文档说明。

使用场景：说明模块可在哪些场景下得到使用。

】

2  模块设计

【主旨：这是模块开发的基础。

软件的迭代过程是：先有设计思路、架构设计，再具体开发；在开发过程中再不断完善初始的设计和架构。清楚了设计思路、架构设计，在模块开发中才不会混乱。】

2.1    设计思路

【主旨：简述模块的设计思路、思想或设计原理。可无】

【如安全键盘模块的设计思路描述为：上层业务使用过程中无法接触到第三方安全键盘的sdk，所使用的类或接口都是杭州银行安全键盘模块自定义的。解耦第三方安全键盘的sdk与业务层。】

 

2.2    架构图

【主旨：以UML图加文字说明模块的内部关系

使用类图、时序图、生命周期图等UML图形来表达模块的架构。辅以文字说明以增加理解。】

 

2.3    流程图

【主旨：用流程图表示模块内部主要的逻辑流程、数据流程等。可无】

【如果模块仅有一个入口，可以从该入口开始画自己的流程图，涵盖整个模块大体的逻辑处理跳转过程，直到从模块出去。】

 

2.4    交互示意图

【主旨：用示意图来说明模块与业务怎么交互的】

【如：业务从哪些途径进入模块，模块怎么处理，然后是否返回结果。】

3 模块说明

【主旨：这是模块开发过程定义好的，供模块使用者学习了解的。尽量少的改变。】

3.1 使用说明

3.1.1 集成说明

【主旨：说明模块的集成过程，有截图演示。】

3.1.2 使用注意

【主旨：如果模块在使用前有前置条件或要求，在此说明。

是否需要提前做初始化，该怎么做初始化，初始化的步骤是。

是否需要其它模块前置先做初始化，

或模块在运行使用中有什么要特别注意的地方，如内存、配置等】

 

3.2  API说明

 【主旨：模块对外的类，需要说明其提供的API接口有哪些，参数含义、作用】

 

3.2.1 XXX.java

【主旨：说明XXX.java提供了哪些api】

 

1.  设置随机数

方法名称

void setCipherKey(String key)

参数

String key

备注

设置32位随机字符串。此串用于AES/SM4等的加密。

返回值

无

 

4 测试

【主旨：模块必须得到完整的测试，保证其稳定性、正确性。然后才可提供给别人使用】

【思维导图的测试：用于对demo、页面的测试。完善测试步骤。】

【自动化的测试：用于对Api的接口测试。完善测试用例。】

【测试要求：说明对测试的技术要求、输入数据、预期结果、进度安排、人员职责、设备条件、驱动程序及桩模块等的规定。】