README

一个架构决策是可能对您的代码库产生重大影响的设计决策。从技术角度和业务角度来看，这些决策为什么被采纳是非常重要的，因此它们应该得到适当的记录。这个库允许您将架构决策记录（ADR）作为代码库中的属性进行记录。这样做提供了一些可能有用的功能

• 架构决策与您的代码库紧密相连。也就是说，决策就在仓库中，您不需要在其他系统中搜索就能找到它。
• 架构决策是您代码库中的代码。作为一个属性，您可以在代码中标记受此决策影响的区域。这使得现有维护者更容易记住，也使得新开发者更容易意识到有关信息。如果您按照此库的约定实现ADR，PHPStorm和其他IDE将通过悬停属性向您显示该决策。
• 静态分析您决策的影响。随着时间的推移，当您的代码库中越来越多的属性被标注后，您可能能够从中提取更多关于决策的信息。

安装

composer require cspray/architectural-decision

要求

在使用此库之前，我做出了几个假设，尤其是在使用提供的bin/architectural-decisions CLI工具时。如果您使用Composer进行安装和自动加载，则假设是相当安全的，但它们值得关注。

1. 项目根目录中存在一个composer.json文件。
2. 该配置具有一个包含psr-4或psr-0条目的autoload，指定了项目根目录中的1个或多个目录。
3. 在您的自动加载器中指定的目录中至少存在一个实现ArchitecturalDecisionRecord的属性。
4. 所有ArchitecturalDecisionRecord实现都应能够无构造函数依赖项创建。

如果这些假设与您的情况不符，此库提供的许多功能都包含在Cspray\ArchitecturalDecision\ArchitecturalDecisionAttributeGatherer和Cspray\ArchitecturalDecision\XmlDocumentGenerator实现中。实现此库与您自己的假设应该是相当直接的。

使用说明

首先，您需要实现一个架构决策记录！这是通过Cspray\ArchitecturalDecision\ArchitecturalDecisionRecord接口处理的。我建议您使用抽象的Cspray\ArchitecturalDecision\DocBlockArchitecturalDecision类。此实现将使用属性作为决策内容的DocBlock。

<?php declare(strict_types=1);

// src/ArchitecturalDecisions/MyFirstDecision.php

namespace Acme\ArchitecturalDecisions;

use Cspray\ArchitecturalDecision\DecisionStatus;
use Cspray\ArchitecturalDecision\DocBlockArchitecturalDecision;
use Attribute;
use DateTimeImmutable;

/**
 * Explain the decision and its potential business impact. 
 */
#[Attribute]
final class MyFirstDecision extends DocBlockArchitecturalDecision {
    
    public function date() : DateTimeImmutable {
        return new DateTimeImmutable('2022-07-19');
    }
    
    public function status() : string|DecisionStatus {
        return DecisionStatus::Draft;
    }

}

可选地，您还可以在代码库中适当的位置进行标注。之后，您可以运行一个命令来生成一个XML文档，详细说明所有决策以及它们在代码库中的标注位置。

./vendor/bin/architectural-decisions

如果成功，将生成一个名为architectural-decisions.xml的文件，并存储在项目根目录中。您可以使用此文件来生成内容视图，协助静态分析，或者您可能想要用ADR信息及其在代码库中的使用进行的其他操作。

设置自定义元数据

可能存在一些您想包含在《架构决策记录》（ArchitecturalDecisionRecord）中但不符合决策内容的信息。这可能是可以用于静态分析的数据。也许您想包含有关谁制定了决策或其他元数据的信息。您可以通过实现 ArchitecturalDecisionRecord::setMetaData(DOMElement $meta) 方法，将您希望添加的数据添加到生成的XML文档中。请参阅 DOMDocument 文档，了解如何适当地向 <meta> 元素添加元素和属性。

示例XML文档

此文档是通过解析此库生成的。我们包含一个轻量级示例，说明为什么您应该为ADR使用属性！

<?xml version="1.0" encoding="UTF-8"?>
<architecturalDecisions xmlns="https://architectural-decision.cspray.io/schema/architectural-decision.xsd">
  
  <architecturalDecision 
      id="UsingAttributesForArchitecturalDecisions"
      attribute="Cspray\ArchitecturalDecision\ArchitecturalDecisionRecords\UsingAttributesForArchitecturalDecisions">
    <date>2022-07-19</date>
    <status>Accepted</status>
    <contents><![CDATA[Architectural Decision Records (ADR) can be useful in determining why a piece of software is the way it is. While these type of documents can live anywhere, an Attribute in your codebase can be a good place to store this info. For more information, please check out the README in this repo or at https://github.com/cspray/architectural-decision]]></contents>
    <codeAnnotations>
      <codeAnnotation>
        <class>Cspray\ArchitecturalDecision\ArchitecturalDecisionRecord</class>
      </codeAnnotation>
    </codeAnnotations>
    <meta />
  </architecturalDecision>
  
  <!-- Additional architecturalDecision would be listed here -->
  
</architecturalDecisions>