コードとしてのアーキテクチャ図

C4モデリングのためのオープンソースプロジェクトであるModelと、modelプラグインを通じたGoaとの統合を使用して、アーキテクチャ図を作成および維持する方法を学びます。

マイクロサービスを中心に構築された現代のソフトウェアアーキテクチャには、 明確で保守可能なドキュメントが必要です。サービス契約とAPIドキュメントは 不可欠ですが、サービスがどのように相互作用し、より大きなシステムに適合するかを 理解することは、しばしば課題となります。ここでアーキテクチャ図が非常に 重要になります。

Modelを理解する

Modelは、アーキテクチャドキュメントに コードの力をもたらすオープンソースプロジェクトです。異なる抽象化レベルを通じて ソフトウェアアーキテクチャを記述および伝達するための階層的な方法を提供する C4モデルアプローチを実装しています。

アーキテクチャ図をコードで定義することで、Modelは以下を可能にします:

  • アーキテクチャドキュメントのバージョン管理
  • 実装と並行した図の保守
  • 図の更新の自動化
  • ドキュメント全体の一貫性の確保

Modelを始めるには、必要なコマンドラインツールをインストールします:

# 図のエディタとビューアをインストール
go install goa.design/model/cmd/mdl@latest

最初の図を作成する

データベースを使用するサービスとユーザーの相互作用を示す簡単なシステム図を 作成してみましょう。以下の例は、Modelの設計言語の主要な概念を示しています:

package design

import . "goa.design/model/dsl"

var _ = Design("はじめに", "これは私のソフトウェアシステムのモデルです。", func() {
    // メインのソフトウェアシステムを定義 - これはアプリケーション全体を表す
    var System = SoftwareSystem("ソフトウェアシステム", "私のソフトウェアシステム。", func() {
        // システム内のデータベースコンテナを定義
        Database = Container("データベース", "情報を保存", "MySQL", func() {
            Tag("Database")  // スタイリングとフィルタリングに役立つタグ
        })
        
        // データベースを使用するサービスコンテナを定義
        Container("サービス", "私のサービス", "Go and Goa", func() {
            Uses(Database, "データの読み書き")
        })
    })

    // システムの外部ユーザーを定義
    Person("ユーザー", "私のソフトウェアシステムのユーザー。", func() {
        Uses(System, "使用")  // システムとの関係を作成
        Tag("person")        // スタイリング用のタグ
    })

    // アーキテクチャを可視化するビューを作成
    Views(func() {
        SystemContextView(System, "システム", "システムコンテキスト図。", func() {
            AddAll()                    // すべての要素を含める
            AutoLayout(RankLeftRight)   // 要素を自動的に配置
        })
    })
})

この例は以下の主要な概念を紹介しています:

  1. Design関数はアーキテクチャのスコープを定義
  2. SoftwareSystemはアプリケーションを表す
  3. Containerは主要なコンポーネント(サービス、データベースなど)を定義
  4. Personはユーザーまたは役割を表す
  5. Usesは要素間の関係を作成
  6. Viewsはアーキテクチャを可視化する異なる方法を定義

C4ビューを理解する

Modelは、ソフトウェアアーキテクチャを記述するためのC4モデルの階層的アプローチを 実装しています。各ビュータイプは、C4モデルで定義されて いるように、特定の目的と対象者に役立ちます:

Views(func() {
    // システムランドスケープ:企業ランドスケープ内のすべてのシステムと人を表示
    SystemLandscapeView("landscape", "概要", func() {
        AddAll()
        AutoLayout(RankTopBottom)
    })

    // システムコンテキスト:1つのシステムとその直接の関係に焦点を当てる
    SystemContextView(System, "context", func() {
        AddAll()
        AutoLayout(RankLeftRight)
    })

    // コンテナ:高レベルの技術的な構成要素を表示
    ContainerView(System, "containers", func() {
        AddAll()
        AutoLayout(RankTopBottom)
    })

    // コンポーネント:特定のコンテナの内部を詳細に表示
    ComponentView("System/Container", "components", func() {
        AddAll()
        AutoLayout(RankLeftRight)
    })
})

各ビュータイプを詳しく見てみましょう:

システムランドスケープビュー

このビューは、ソフトウェアシステムのランドスケープの全体像を示します。 ステークホルダーがシステムが全体的な企業ITシステムにどのように適合するかを 理解するのに役立ちます。

システムコンテキストビュー

この図は、環境内のソフトウェアシステムを示し、それを使用する人々と相互作用する 他のシステムに焦点を当てます。技術的および非技術的な対象者との文脈を文書化し 伝達するための優れた出発点です。

コンテナビュー

C4モデルコンテナ図ガイドで説明されて いるように、コンテナビューはソフトウェアシステム内部にズームインして、高レベルの 技術的な構成要素を示します。この文脈における「コンテナ」は、コードを実行または データを保存する、個別に実行/デプロイ可能なユニットを表します:

  • サーバーサイドWebアプリケーション
  • シングルページアプリケーション
  • デスクトップアプリケーション
  • モバイルアプリ
  • データベーススキーマ
  • ファイルシステム

このビューは、開発者と運用スタッフが以下を理解するのに役立ちます:

  • ソフトウェアアーキテクチャの高レベルな形状
  • 責任がどのように分散されているか
  • 主要な技術選択
  • コンテナがどのように相互に通信するか

このダイアグラムは、クラスタリング、ロードバランサー、レプリケーションなどの デプロイメントの詳細を意図的に省略していることに注意してください。これらは 通常、環境によって異なります。

コンポーネントビュー

このビューは個々のコンテナ内部にズームインして、そのコンポーネントと それらの相互作用を示します。コードベースで作業する開発者が、コンテナが 内部でどのように構造化されているかを理解するのに役立ちます。

図の操作

Modelはmdlコマンドを通じてインタラクティブなエディタを提供し、図の 改良とエクスポートを容易にします。エディタを以下のように起動します:

# デフォルトの出力ディレクトリ(./gen)で起動
mdl serve goa.design/examples/model/design

# または、カスタム出力ディレクトリを指定
mdl serve goa.design/examples/model/design -dir diagrams

これにより、http://localhost:8080 でWebインターフェースが起動し、以下が可能になります:

  • 要素をドラッグして配置
  • 関係のパスを調整
  • リアルタイムで変更をプレビュー
  • 図をSVGファイルとしてエクスポート

インタラクティブな編集

エディタは図を操作するためのいくつかの方法を提供します:

  1. 要素の配置:

    • 要素をドラッグして位置を決める
    • 矢印キーで微調整
    • SHIFTキーを押しながら矢印キーで大きく移動
  2. 関係の管理:

    • ALT + クリックで関係に頂点を追加
    • 頂点を選択してBACKSPACEまたはDELETEで削除
    • 頂点をドラッグして関係のパスを調整
  3. 選択ツール:

    • クリックで個々の要素を選択
    • SHIFT + クリックまたはドラッグで複数の要素を選択
    • CTRL + Aですべてを選択
    • ESCで選択を解除

キーボードショートカットリファレンス

以下のショートカットを使用してエディタを効率的に操作できます:

カテゴリショートカット効果
ヘルプ?, SHIFT + F1キーボードショートカットを表示
ファイルCTRL + SSVGを保存
履歴CTRL + Z元に戻す
履歴CTRL + SHIFT + Z, CTRL + Yやり直し
ズームCTRL + =, CTRL + ホイールズームイン
ズームCTRL + -, CTRL + ホイールズームアウト
ズームCTRL + 9全体を表示
ズームCTRL + 0100%ズーム
選択CTRL + Aすべて選択
選択ESC選択解除
移動矢印キー選択を移動
移動SHIFT + 矢印キー選択を速く移動

図のスタイリング

Modelはスタイルを通じて図の外観をカスタマイズすることができます:

Views(func() {
    // ビューを定義
    SystemContextView(System, "context", func() {
        AddAll()
        AutoLayout(RankTopBottom)
    })
    
    // カスタムスタイルを適用
    Styles(func() {
        // "system"タグが付いた要素のスタイル
        ElementStyle("system", func() {
            Background("#1168bd")  // 青い背景
            Color("#ffffff")       // 白いテキスト
        })
        
        // "person"タグが付いた要素のスタイル
        ElementStyle("person", func() {
            Shape(ShapePerson)     // 人物アイコンを使用
            Background("#08427b")  // 濃い青の背景
            Color("#ffffff")       // 白いテキスト
        })
    })
})

Structurizrとの統合

mdlツールはローカル開発とSVGエクスポートに最適ですが、Modelは高度な機能のために Structurizrサービスとも統合されています。