IT项目架构设计文档编写规范
项目流程中技术评审环节，需要做架构设计评审，本文档主要讲解架构设计文档编写原则，约束架构设计文档的格式、内容，以达到提高技术评审质量，提升项目开发质量的目的。
编写流程
首先技术负责人，做为一个项目的技术决策人员，需要了解业务需求，按如下步骤组织编写技术评审文档：
- 了解业务需求和现有系统架构，按架构原则整理项目架构相关文档
- 完成架构相关考虑后，按需求对项目拆分功能模块，并对每个模块标注必须设计点
- 按人员情况将功能模块分配到人，组织编写所有功能模块的详细设计
- 验收每个模块的详细设计是否达标
- 所有模块详细设计完成后组织技术评审
编写原则
架构设计文档主要分为两个层面，架构层面和设计层面。
架构层面原则
- 项目架构描述：如果是迭代项目，现有项目架构情况需要描述清楚，可以传送到固定的项目架构文档，不用每次都写
- 路由规划：相关功能的路由调用链路，域名、SLB、nginx、gateway、微服务链路
- 安全规划：内外网功能划分，鉴权、反黑产等
- 性能&可用性规划：QPS、限流、集群配制、资源规格等
- 扩展性规划：根据后续项目的迭代计划，要预留哪些扩展考虑哪些问题
- 上线规划：新老版本兼容问题、灰度计划、试点计划等
- 事故恢复：如何保障异常出现后恢复系统和数据，要求第一层兜底
- 门店服务要按非可靠网络下大型分布式系统架构，考虑弱网模式、断网模式、断电重启、磁盘损坏等场景下数据和服务的可靠性。
以上为架构层面主要考虑的内容，各项目技术负责人可以根据实际情况补充，如不需要相关设计标不需要相关设计即可，但必须标注以示思考过相关层面问题。
设计层面原则
- 从需求角度用技术语言简要说明需求和实现的大体逻辑。
- 从系统角度说明要修改哪些系统的哪些功能。
- 从接口角度说明要新增/修改哪些微服务的哪些接口。
- 从数据角度说明涉及数据的来源、数据量大小、数据一致性等方面情况。
- 从事故角度说明异常出现后如何恢复系统和数据，要求第一层兜底
接口注意事项
接口分为外部接口和内部接口。
外部接口是提供给网关和C端使用的接口，修改出入参必须在文档中说明。
外部接口的新增和修改会影响前端上线发布，要考虑兼容性和是否影响上线。
内部接口，因为可以同时上线，没有第三方调用，需要考虑历史数据的兼容性。
数据注意事项
数据来源：数据库、es、redis、第三方接口
涉及数据查询必须提供生产数据量和未来数据量变化的评估，主要判断有没有性能问题。
新增或修改数据来源必须有详细说明：
- 数据库要有字段来源说明或SQL语句
- ES要有索引和字段说明
- redis要有KEY和值格式说明
- 第三方接口要有出入参数变化说明
文档编写
对于核心的模块或接口，需要以文字、时序图、流程图的方式做出详细设计。
文字主要说明算法步骤。
时序图主要说明一次调用的中间过程和涉及系统。
流程图主要说明业务的流程变化。
技术文档模板
系统架构部分
项目架构
如无修改可以连接现有文档
路由架构
如无修改可以连接现有文档
安全架构
如无修改可以连接现有文档
性能和可用性
说明项目需求在计算、存储、可用性上的问题和解决方案，如无写无问题。
扩展性
说明项目需求在计算、存储、可用性上的问题和解决方案，如无写无问题。
上线规划
新老版本兼容问题、灰度计划、试点计划等
事故恢复
架构层面的事故恢复机制，如无修改可以连接现有文档
功能详细设计
功能模块1（张三）
需求1
技术负责人标注：需要特殊说明的功能点和要求
需求简述：
功能开发逻辑：
- 功能层面：以文字、时序图、流程图等方式说明功能的流程步骤
- 系统层面：在哪几个系统上新增或修改的接口清单
- 数据层面：存取了哪些数据，数据怎么流转的，数据的关系，数据量大小，是否有性能问题
- 外部交互：是否是外部接口或三方接口，迭代扩展如何保障
需求2
技术负责人标注：需要特殊说明的功能点和要求
需求简述：
功能开发逻辑：
- 功能层面：以文字、时序图、流程图等方式说明功能的流程步骤
- 系统层面：在哪几个系统上新增或修改的接口清单
- 数据层面：存取了哪些数据，数据怎么流转的，数据的关系，数据量大小，是否有性能问题
- 外部交互：是否是外部接口或三方接口，迭代扩展如何保障
功能模块2（李四）
需求1
技术负责人标注：需要特殊说明的功能点和要求
需求简述：
功能开发逻辑：
- 功能层面：以文字、时序图、流程图等方式说明功能的流程步骤
- 系统层面：在哪几个系统上新增或修改的接口清单
- 数据层面：存取了哪些数据，数据怎么流转的，数据的关系，数据量大小，是否有性能问题
- 外部交互：是否是外部接口或三方接口，迭代扩展如何保障
需求2
技术负责人标注：需要特殊说明的功能点和要求
需求简述：
功能开发逻辑：
- 功能层面：以文字、时序图、流程图等方式说明功能的流程步骤
- 系统层面：在哪几个系统上新增或修改的接口清单
- 数据层面：存取了哪些数据，数据怎么流转的，数据的关系，数据量大小，是否有性能问题
- 外部交互：是否是外部接口或三方接口，迭代扩展如何保障