每个系统都包含一系列架构决策, 定义了设计和实现的边界和限制,
架构设计文档的核心是以某种方式的选型决策, 而开发团队可能不太清楚这个决策背后的假设和思考.
对于这些决策, 由于我们缺少当时的上下文, 只能盲目的接受和盲目的做出改变.
闲逛 ThoughtWorks Radar 偶然发现一个在 17 年和 18 年都被 ADOPT(采用) 的技术叫 "ADR - Lightweight Architecture Decision Records", 轻量的架构决策记录, 针对演进式架构而提出的一种架构文档管理方法.
https://assets.thoughtworks.com/assets/technology-radar-vol-18-cn.pdf
ADR
敏捷开发和 ADR
敏捷宣言说:"可以工作的软件, 强过全面的文档"
(agile manifesto: Working software over comprehensive documentation)
--- 意思不是说不需要文档!
特别是敏捷类型的项目, 软件架构需要适应新的业务, 市场的变化, 架构技术重要的决策是如何做出的, 为什么这么选择, 背后有怎样的假设.
所以, 主要的问题是架构的文档形式和内容, 架构文档需要与项目的状态保持紧密的关系, 并且简洁, 明了, 便于维护和阅读, 不然, 架构的文档就没有人看, 更不会有人去更新他.
什么是 ADR
接下来我们就来简单看一下什么是 ADR, 如何解决篇头提出的几个疑虑.
ADR, 先来看一下什么是 AD(Architecture Decision)?,
在《Documenting Architecture Decisions》一文中说道架构文档应该关注和收集的内容包括:"affect the structure, non-functional characteristics, dependencies, interfaces, or construction techniques".
因此, 架构决策, 是一个软件设计的选择, 涵盖了功能性和非功能性所需要的重要架构选型和设计, 系统架构的质量是可以被衡量的 (Architecturally Significant Requirement (ASR) ).
Architectural Decision Record (ADR) 是一个单一的架构决策的记录文件, 例如架构师所做出的架构决策思考, 或者架构设计会要的记录等, 而 ADRs 则是维护了一系列架构记录文件集合 (ARD), 通常存储在项目的 doc/adr 目录下, 文件名的格式形如: adr-NNNN-title-with-dashes.md , 或者 NNNN-title-with-dashes.md,NNNN 是一个单调的数字序列, 例如 0001.
注意 , 当某个决策被废除, 这个旧的 ADR 文件应该保留, 只是做个标记, 表示被取代, 因为它也是曾经决策思考的结果.
ADR 文件的结构:
- # [short title of solved problem and solution]
- * Status: [proposed | rejected | accepted | deprecated | ... | superseded by [ADR-0005](0005-example.md)] <!-- optional -->
- * Deciders: [list everyone involved in the decision] <!-- optional -->
- * Date: [YYYY-MM-DD when the decision was last updated] <!-- optional -->
- Technical Story: [description | ticket/issue URL] <!-- optional -->
- ## Context and Problem Statement
- [Describe the context and problem statement, e.g., in free form using two to three sentences. You may want to articulate the problem in form of a question.]
- ## Decision Drivers <!-- optional -->
- * [driver 1, e.g., a force, facing concern, ...]
- * [driver 2, e.g., a force, facing concern, ...]
- * ... <!-- numbers of drivers can vary -->
- ## Considered Options
- * [option 1]
- * [option 2]
- * [option 3]
- * ... <!-- numbers of options can vary -->
- ## Decision Outcome
- Chosen option: "[option 1]", because [justification. e.g., only option, which meets k.o. criterion decision driver | which resolves force force | ... | comes out best (see below)].
- ### Positive Consequences <!-- optional -->
- * [e.g., improvement of quality attribute satisfaction, follow-up decisions required, ...]
- * ...
- ### Negative Consequences <!-- optional -->
- * [e.g., compromising quality attribute, follow-up decisions required, ...]
- * ...
- ## Pros and Cons of the Options <!-- optional -->
- ### [option 1]
- [example | description | pointer to more information | ...] <!-- optional -->
- * Good, because [argument a]
- * Good, because [argument b]
- * Bad, because [argument c]
- * ... <!-- numbers of pros and cons can vary -->
- ### [option 2]
- [example | description | pointer to more information | ...] <!-- optional -->
- * Good, because [argument a]
- * Good, because [argument b]
- * Bad, because [argument c]
- * ... <!-- numbers of pros and cons can vary -->
- ### [option 3]
- [example | description | pointer to more information | ...] <!-- optional -->
- * Good, because [argument a]
- * Good, because [argument b]
- * Bad, because [argument c]
- * ... <!-- numbers of pros and cons can vary -->
- ## Links <!-- optional -->
- * [Link type] [Link to ADR] <!-- example: Refined by [ADR-0005](0005-example.md) -->
- * ... <!-- numbers of links can vary -->
注意, 有很多项是 optional 的, 根据情况, 自行取舍.
一个例子:(doc/adr/0005-help-comments.md)
- 5. Help comments
- Date: 2016-02-13
- Status
- Accepted
- Amended by 9. Help scripts
- Context
- The tool will have a help subcommand to provide documentation for users.
- It's nice to have usage documentation in the script files themselves, in comments. When reading the code, that's the first place to look for information about how to run a script.
- Decision
- Write usage documentation in comments in the source file.
- Distinguish between documentation comments and normal comments. Documentation comments have two hash characters at the start of the line.
- The adr help command can parse comments out from the script using the standard Unix tools grep and cut.
- Consequences
- No need to maintain help text in a separate file.
- Help text can easily be kept up to date as the script is edited.
- There's no automated check that the help text is up to date. The tests do not work well as documentation for users, and the help text is not easily cross-checked against the code.
- This won't work if any subcommands are not implemented as scripts that use'#' as a comment character.
小结
总结一下, 越来越多的基于敏捷的项目开发模式, 要求我们有演进式的架构设计眼光, 因此我们也需要采用一种类似的技术, 去有效的, 敏捷的整理架构文档, 去跟踪记录你或者你们团队, 曾经对一系列功能所做出的架构思考和取舍权衡的过程.
参考
- https://adr.github.io/ Homepage of the ADR
- https://www.thoughtworks.com/radar/techniques/lightweight-architecture-decision-records
- https://www.hascode.com/2018/05/managing-architecture-decision-records-with-adr-tools/ Managing Architecture Decision Records with ADR-Tools
- https://resources.sei.cmu.edu/asset_files/Presentation/2017_017_001_497746.pdf
- https://agilemanifesto.org
来源: https://www.cnblogs.com/xguo/p/11144324.html