PlantUMLのインクルード機能完全ガイド：再利用可能な図表作成のベストプラクティス

開発者やアーキテクトにとって、図表の作成は重要な作業の一つです。PlantUMLを使用する際、同じような設定やコンポーネントを何度も書き直すのは非効率です。そこで、インクルード機能を活用することで、効率的で一貫性のある図表作成が可能になります。

インクルード機能の基本

PlantUMLのインクルード機能は、外部ファイルを取り込んで再利用できる強力な機能です

インクルードには複数の方法があります：

• !include – 標準的なインクルード
• !include_many – 同じファイルを複数回インクルード可能
• !include_once – 重複インクルードを防止
• !includesub – ファイルの特定部分のみをインクルード

基本的な使い方は以下の通りです：

plantuml本体コード

@startuml
!include common.iuml
Alice -> Bob: Hello
@enduml

インクルード コード

' common.iuml

' フォントとテーマの基本設定
skinparam DefaultFontName "Helvetica"
skinparam DefaultFontSize 12
skinparam BackgroundColor White
skinparam Shadowing false

' シーケンス図の設定
skinparam Sequence {
    ArrowColor #2688d4
    LifeLineBorderColor #666666
    LifeLineBackgroundColor #f2f2f2
    ParticipantBorderColor #666666
    ParticipantBackgroundColor #e6e6e6
    ParticipantFontColor #333333
    ActorBorderColor #666666
    ActorBackgroundColor #e6e6e6
    ActorFontColor #333333
}

' メッセージスタイル
skinparam Arrow {
    MessageAlign center
    FontSize 11
}

' パーティシパントスタイル
skinparam Participant {
    Padding 20
}

' タイトルスタイル
skinparam Title {
    FontSize 18
    FontColor #333333
}

同じディレクトリにiumlを格納しておけば参照可能です。
※パスをいれれば、別のフォルダのものも参照可能です。

実践的な設定例

共通スタイルの定義

このファイルは統一されたスタイルを定義しています：

• 変数定義で色やフォントを一元管理
• ${変数名} で定義した変数を参照可能
• クラス図のスタイルをコーポレートカラーに統一

' styles/corporate.iuml
!define FONT_NAME Arial
!define PRIMARY_COLOR #1E90FF
!define SECONDARY_COLOR #87CEEB

skinparam {
    DefaultFontName ${FONT_NAME}
    BackgroundColor White
    TitleFontSize 20
    
    Class {
        BackgroundColor ${PRIMARY_COLOR}
        BorderColor ${SECONDARY_COLOR}
        FontColor White
    }
}

カスタムコンポーネントの作成

再利用可能なコンポーネントを手続き（procedure）として定義：

• $database：データベースコンポーネントを作成（デフォルトはPostgreSQL）
• $microservice：マイクロサービスコンポーネントを作成（デフォルトはSpring Boot）
• パラメータ化されており、呼び出し時に名前や技術を指定可能

' components/database.iuml
!procedure $database($name, $type="PostgreSQL")
database "$name\n<$type>" as $name {
}
!endprocedure

!procedure $microservice($name, $tech="Spring Boot")
rectangle "$name\n<$tech>" as $name {
}
!endprocedure

高度な使用方法

条件付きインクルード

環境に応じて異なるテーマを適用：

• %variable_existsで変数の存在確認
• THEMEが定義されている場合はダークテーマ
• 未定義の場合はライトテーマを適用

' config.iuml
!if (%variable_exists("THEME"))
    !include themes/dark.iuml
!else
    !include themes/light.iuml
!endif

部分的なインクルード

ファイル内の特定部分のみを再利用可能：

• !startsub と !endsub で名前付きセクションを定義
• !includesub components.iuml!DATABASE で特定セクションのみ取り込み可能
• 複数の要素を1つのファイルにまとめつつ、必要な部分のみ使用可能

' components.iuml
!startsub DATABASE
database "Database" {
}
!endsub

!startsub API
rectangle "API" {
}
!endsub

インクルードの使い方のコツ

ディレクトリ構造の整理

• styles/ – スタイル定義ファイル
• components/ – 再利用可能なコンポーネント
• themes/ – テーマ関連の設定
• common/ – 共通の設定や定義

命名規則

• インクルードファイルには .iuml 拡張子を使用
• 明確な名前付けで内容を表現
• プレフィックスを活用して種類を区別

注意点と制限事項

• インクルードパスは実行環境に依存
• 相対パスと絶対パスの使い分けに注意
• 循環参照を避ける
• 大規模なファイルのインクルードはパフォーマンスに影響する可能性あり

まとめ

PlantUMLのインクルード機能は、図表作成の効率を大幅に向上させる強力なツールです。共通のスタイル定義、再利用可能なコンポーネント、条件付きインクルードなどを活用することで、保守性の高い一貫性のある図表を作成できます。適切なディレクトリ構造と命名規則を採用し、インクルード機能を効果的に活用することで、より効率的な図表作成ワークフローを実現できます。

おそらくPlantUMLでインクルードができるということを知らない人が結構いるんじゃないのかなと思います。
共通設定としてチームで共有してみんなで使えば、チームで体裁の整った文書が書けるので、非常に有用です！