de_DEen_USes_ESfa_IRfr_FRhi_INid_IDjapl_PLpt_PTru_RUvizh_CNzh_TW

すべてをズームインする：C4 コード図の理解――それらとは何か、どのような場面で価値を発揮するか、そして実践的な PlantUML の例

C4 コード図とは何ですか？

コード図はレベル4――シモン・ブラウンのC4モデルにおける最も深く、最も詳細なレベルです。

The Ultimate Guide to C4 Model Visualization with Visual Paradigm's AI Tools - ArchiMetric

以下を示します：

  • クラス, インターフェース, 列挙型, レコード、または特定のコンポーネント（レベル3から）を実装する、その他のコードレベルの構成要素。

  • 関係性そのクラス間の関係（継承、組成、依存関係、インターフェースの実装など）。

  • 重要な設計要素コンポーネント内部に適用されたパターン（例：リポジトリ、サービス、DTO、ドメインエンティティ、ファクトリなど）。

実際には、このレベルはほぼ常にUMLクラス図（または簡略化されたバージョン）であり、1つ（または非常に少数の）コンポーネントに焦点を当てています。

重要な補足：

  • レベル4はではありません全体のコードベースについてのものではありません。

  • それはではありませんすべてのクラスを表示するために必要です。

  • これは…をマップしています必須の構造のみ複雑または重要なコンポーネントが実際にどのように構築されているかを理解するために必要なもの。

  • 公式のC4の推奨事項：理想的には自動生成されるソースコードから（Doxygen、Javadoc + UMLプラグイン、yWorks、Structurizr、CodeSeeなどツールを経由して）自動生成されるべきであり、手描きではない。

コード図を作成するタイミング

レベル4の図は控えめに作成する——以下の状況でのみ。

  • コンポーネントは非常に複雑, ミッションクリティカル、またはソースコードだけでは理解しにくいソースコードだけでは（たとえば、複雑なドメインロジック、デザインパターンの多用、暗号化フロー、状態機械、技術的負債で溢れたレガシーコードなど）。

  • あなたが働いているのは厳格に規制された業界（金融、医療、航空宇宙、防衛）において、監査担当者やコンプライアンスチームが、アーキテクチャ → 設計 → 実装への明確なマッピングを要求する。

  • …の間大規模なリファクタリング, レガシーコンポーネントの徐々な排除、または新しいアーキテクチャパターンの導入（ハニカム、クリーン、垂直スライス、DDDアグリゲート）——前後比較のビューが変更を伝えるのに役立つ。

  • オンボーディングシニア開発者またはアーキテクト高リスクのコードの明確でない内部構造を素早く理解する必要がある人

  • すでに以下に投資しています自動生成ツール — そのため、レベル4の維持コストはほとんどありません。

  • チームは以下の通り合意しました「生きているドキュメント」クラスレベルでのこれは、この特定のサブシステムにとって価値があります。

以下の場合は、レベル4の図を作成しないでください：

  • コンポーネント構造が良い名前付け、小さなサイズ、またはクリーンなコードから明らかである（大多数の現代的なマイクロサービスがこれに該当する）。

  • すでに以下を持っています良いユニット／統合テスト, 明確なインターフェース、および説明的なコメント.

  • チームの大多数はコードを簡単に移動できる。

  • 維持コストが利益を上回る（手書きのクラス図は非常に早く陳腐化する）。

サイモン・ブラウンと大多数の実務家は強調している：大多数のチームはレベル4を必要としない. レベル1＋2通信の80～90％をカバーする；レベル3残りの大部分を処理する。レベル4は例外であり、ルールではない。

コード図を使うのはなぜか？（価値を生むとき）

  • アーキテクチャ ↔ 実装の橋渡し— 高レベルのコンポーネントが実際にコードでどのように実現されているかを示す。

  • 複雑な内部設計を明確にする— パターン（戦略、ファクトリ、デコレータ、リポジトリ）の使用、レイヤー違反、強い結合、または巧妙なドメインモデリングを明らかにする。

  • 監査およびコンプライアンスを支援 — アーキテクチャ上の意思決定がコードにまで反映されていることを示す。

  • リファクタリングおよび移行に関する議論を支援 — 前後のクラス構造を比較することで、提案の内容が明確になる。

  • 「部族的知識」を削減する — 新しい上級エンジニアが、すべてのソースファイルを読むよりも、複雑な部分を素早く理解できるように支援する。

  • 自動生成されたバージョンは「生きているドキュメント」になる — ツールが整っていれば、ほとんど手間をかけずに正確な状態を維持できる。

優れたコード図の作成方法（ステップバイステップ＋ベストプラクティス）

  1. 1つのコンポーネントを選ぶ — 通常は、内部の複雑さがズームインの正当性を持つレベル3の図から選ぶ。

  2. 決定：手書きか自動生成か？

    • 手書き → ワークショップや提案、または自動ツールでは扱いにくいほど複雑な領域に限定する。

    • 自動生成 → 推奨（PlantUMLを用いて出力のスタイルや微調整は可能）。

  3. 本質に集中する — 表示するもの：

    • 重要なクラス／インターフェース

    • 重要な関係性（→ 依存、— コンポジション、<| 実装、^ 継承）

    • 集約、エンティティ、値オブジェクト（DDDスタイル）

    • 強調したい重要なパターンまたはアンチパターン

  4. 簡潔に保つ — クラス数は最大15個まで。それ以上なら、焦点を絞った図に分割する（例：「認証スライス」、「注文処理エンティティ」など）。

  5. ベストプラクティス

    • 好むべきは自動生成 可能な限り（陳腐化が少ない）。

    • 使用するべきはPlantUML classDiagram 構文 — 明快でバージョン管理可能。

    • 追加するノート明白でない意思決定のため（例：「アンエミック・ドメインモデルを使用中 – 計画中の再設計」）

    • 表示を避けるすべて— つまらないゲッター/セッター、ユーティリティクラスは省略する。

    • リポジトリに保存 → コードとして扱う（コンポーネントの近くに.pumlファイルをコミットする）。

    • 慎重に使用する — 複雑なコンポーネントごとに1つまで。マイクロサービスごとではなく。

    • 以下と組み合わせる動的ビュー（シーケンス/協調）— 実行時フローが静的構造よりも重要である場合。

PlantUMLの例 – 認証コンポーネント（Big Bank plcスタイルの拡張）

ここでは、実際のレベル4の例を示す。以下のコンポーネントにズームインする。セキュリティ／認証コンポーネント以前のAPIアプリケーション図から。

@startuml
title C4 レベル4 – コード図：APIアプリケーション内の認証

skinparam monochrome true
skinparam shadowing false
skinparam class {
  BackgroundColor White
  BorderColor Black
  ArrowColor Black
}

abstract class AuthenticationProvider {
  + authenticate(credentials): Authentication
}

class JwtAuthenticationProvider {
  - tokenProvider: JwtTokenProvider
  - userDetailsService: UserDetailsService
  + authenticate(credentials): Authentication
}

class JwtTokenProvider {
  - secretKey: String
  - validityInMilliseconds: long
  + generateToken(userDetails): String
  + validateToken(token): boolean
  + getUsernameFromToken(token): String
}

interface UserDetailsService {
  + loadUserByUsername(username): UserDetails
}

class DatabaseUserDetailsService {
  - userRepository: UserRepository
  + loadUserByUsername(username): UserDetails
}

class UserRepository {
  + findByUsername(username): Optional<User>
}

class User {
  - username: String
  - passwordHash: String
  - roles: Set<Role>
}

class JwtAuthenticationToken << (T,orchid) Authentication >> {
  - principal: UserDetails
  - credentials: Object
  - authorities: Collection<GrantedAuthority>
}

' 関係
JwtAuthenticationProvider -up-> JwtTokenProvider : 使用
JwtAuthenticationProvider -up-> UserDetailsService : 使用
DatabaseUserDetailsService .up.|> UserDetailsService
DatabaseUserDetailsService --> UserRepository : 使用
UserRepository --> User : 戻り値

JwtAuthenticationToken .up.|> Authentication

note right of JwtAuthenticationProvider
  JWTベースのステートレスセッションの主な認証フロー
end note

note bottom of JwtTokenProvider
  HS512を使用してJWTの署名と検証
end note

@enduml

この小さな図では：

  • 認証の内部構造にのみ焦点を当てる

  • 主要なクラス、インターフェース、依存関係を示す

  • パターン（プロバイダー、リポジトリ）を強調する

  • ノートを文脈の説明に使用

任意のPlantUMLレンダラーに貼り付ける — ドメインに合わせてカスタマイズする（例：JWTをOAuth2に置き換え、MFAクラスを追加など）。

要約の注意点：レベル4は強力だが、稀である。意図的に使用し、自動生成を優先し、決して無駄な作業にならないようにする。C4の最大の価値はレベル1～3に集中する。（選択的に）モデル化を楽しんでください！

リソース