ブログトップ

公開日:

更新日:

9 min read

技術革新

AstroでPlantUMLを実装する方法

Astro PlantUML UML システム設計 技術文書 コンポーネント開発 MDX
AstroでPlantUMLを実装する方法のイメージ

この業界に入って最初の案件はプログラマーでしたが、その次からは機能設計を発注元から任されました。 その後、基本設計、要件定義とどんどん上流を登っていきました。 24歳でシステム設計も担当するようになったのですが、当時は設計書の記述がバラバラで標準的なものありませんでした。 世の中の大半は汎用機によるCOBOLでの勘定系システムの開発でしたが、 そちらは設計書の記述方法がメーカーごとに確立されていたようでした。 しかし制御系になると、担当者の裁量で設計書を書いていました。

UML

当時はネットもなくて、書店で本を買って勉強していました。 なので紀伊国屋とか三省堂にはよく行っていました。 そうして、世の中には頭のいい人がたくさんいるので、統合的な設計手法や記述を研究している人がいるんじゃないかと思った矢先に出会ったのが、 OOM（Object-Oriented Modeling）という本でした。著者はスタローンだったっけ？ と、今でも間違って記憶していますが、ジェームズ・ランボー（James Rumbaugh）です。

この本はとても衝撃的でした。まず、理論が分かりやすい。すっきりして、シンプルで、理にかなっている。 試しに業務案件をこの手法で設計してみたら、なんということでしょう！

誰も理解できませんでした…。ですよねー。

ですが、このころからクラス図やステートチャートを使っていました。 クラス図は、システムの実装時に役立ちました。 フローチャートは構造化を記述できる、書き慣れたものがあったので、それを使っていました。 その後、UMLが提唱され、設計書の記述方法が標準化されました。

PlantUML

ただ、割と最近までUMLを記述するのが面倒でした。 いろんな専用ツールを使ってみたのですが、いずれもしっくりしません。 UMLやER図からプログラムを生成しようというアプローチが無理があるんです。 結局、最もしっくりきたのがMS-Wordでした。何と言っても私はMS-Word Ver1.2からのユーザーです。 とはいえ、Wordで図を描くのは、一苦労です。

そこに出会ったのがPlantUMLです。 こいつはすごい！テキストで図が書ける！生産性が爆上がりです。 さらにAIの登場。AIとPlantUMLで生産性がまたまた急上昇！その上Githubで設計資料が管理できる！ これはもう最高です。

あ、mermaidもいいですね。ガントチャートとかはmermaidの方が好きです。 私にとってmermaidの最大の欠点はユースケース図が書けないことです。 要件定義や基本設計段階で、システムを整理するときにユースケース図は必須です。 しかし、ユースケース図の有効性を知らない人の多いこと。

だって、最近のフリーランスのプログラマーって、独学でプログラミングを覚えた人が多いんです。 だから、システム開発なんてしたことが無い。だから、ユースケース図なんて知らない。 そもそも、21世紀になってから、日本人SEは実装なんてしませんよね。全部オフショアです。 非効率極まりない。ITシステムで考えられないようなバグで社会に大きな影響があるのは、 間違いなく、実装を知らないSEが設計しているに違いない、と個人的には思っています。

で、PlantUMLはとても便利ですが、ウェブに掲載するには、PlantUMLの図をキャプチャーしていました。 いちいち図を保存するのが面倒臭い。 PlantUMLを直すたびに、図をキャプチャーするのは、エレガントではありません。 直接表示できれば、なんということはない。 astroで出来ないか？できるのか？調べてみたところ…

できんじゃん‼

ということで、前置きが大変長くなりましたが、これよりastroでPlantUMLを表示する方法を解説します。

AstroでPlantUMLを実装する

1. パッケージのインストール

   # PlantUMLエンコーダーと型定義をインストール
pnpm add plantuml-encoder
pnpm add -D @types/plantuml-encoder

2. コンポーネントの作成

src/components/PlantUML.astroを作成します：

   ---
// src/components/PlantUML.astro
interface Props {
  diagram: string;
  className?: string;
}

const { diagram, className = 'w-full max-w-4xl mx-auto' } = Astro.props;
import plantumlEncoder from 'plantuml-encoder'

const encodedDiagram = plantumlEncoder.encode(diagram)
const serverUrl = 'http://www.plantuml.com/plantuml/svg/'
---

<img
  src={`${serverUrl}${encodedDiagram}`}
  alt='PlantUML diagram'
  class={className}
/>

3. 使用方法

基本的な使用法

   ---
フロントマター
---

import PlantUML from '@/components/PlantUML'

<PlantUML
	diagram={`
@startuml
// PlantUMLのダイアグラムコードをここに記述
@enduml
`}
/>

カスタムクラスの適用

   <PlantUML diagram={`...`} className='w-full max-w-2xl mx-auto my-8 shadow-lg' />

4. MDXでの使用

MDXファイルでPlantUMLを使用する場合：

   ---
// your-post.mdx
---

import PlantUML from '@/components/PlantUML'

記事の内容...

<PlantUML diagram={`
@startuml
!theme plain
participant Browser
participant Server
participant Database

Browser -> Server: "リクエスト送信\\nGET /api/data"
Server -> Database: SELECT \* FROM users
Database --> Server: "ユーザーデータ\\n(JSON形式)"
Server --> Browser: レスポンス
@enduml
`} />
PlantUML diagram

5. 重要な注意点

  1. 改行の扱い

    • PlantUMLでの改行は \n ではなく \\n を使用する必要があります
    • メッセージに改行を含める場合は引用符で囲む必要があります 例: A -> B: "1行目\\n2行目"

  2. SSR対応

    • PlantUMLコンポーネントはビルド時に静的に生成されます

  3. 画像の最適化

    • Astroの画像最適化機能は外部URLには適用されません

PlantUMLの文法や詳細な使用方法については、PlantUMLの公式ドキュメントを参照してください。

おまけ：pnpm vs npm

  1. パッケージ保存方法
  • pnpm: コンテンツアドレス可能なストレージを使用し、同じパッケージを複数プロジェクトで共有
  • npm: 各プロジェクトごとに個別にパッケージをインストール
  1. ディスク使用量
  • pnpm: ハードリンクによる共有で大幅な容量削減
  • npm: プロジェクトごとに重複して保存するため容量を多く使用
  1. インストール速度
  • pnpm: 並列処理とキャッシュ共有により高速
  • npm: 比較的遅い
  1. コマンドの違い

パッケージ追加の場合:

   npm install = pnpm install （プロジェクトの依存関係全体のインストール）
npm install パッケージ名 = pnpm add パッケージ名 （個別パッケージの追加）

パッケージ削除の場合:

   npm uninstall = pnpm uninstall
npm remove = pnpm remove
npm rm = pnpm rm

混乱を避けるための一般的な使用パターン：

  • npmの場合: npm install/uninstall
  • pnpmの場合: pnpm add/remove