【PlantUML】Railsの画像アップロード機能を図に起こしてみる

VSCodeでPlantUMLを使用して、Rails, CarrierWave, Amazon S3を用いた画像アップロード機能のシーケンス図を作成していきます。

プロジェクトに関わっているメンバー全員がRailsを知っていればいいのですが、必ずしもそうとは限りません。

プロジェクトのフロント業務を担う人からすると「どうやって画像をアップロードするの？」「S3使うんでしょ？」「ユーザー操作から順を追って理解したい」と思うかもしれません。

エンジニアには嬉しい、テキストベースでUMLダイアグラムを作成できるのが「PlantUML」です。

PlantUML 拡張機能のインストール

1. VSCode を開き、左サイドバーから拡張機能 (四角が重なったアイコン) を選択します。
2. 検索バーに「PlantUML」と入力し、検索結果から拡張機能を見つけましょう。
3. クリックして拡張機能をインストールします。

要件を整理

CarrierWaveを利用した画像アップロードとのことなので、「PlantUML」で書き起こす内容はざっくり以下の通り。

1. ユーザーが画像を選択し、WEBサーバーにリクエスト
2. 意図した形式の画像かを検証
3. エラーの場合はViewに返す
4. 画像アップロード（URLを取得する）
5. データを生成

シーケンス図の作成

1. VSCode で新しいファイルを作成し、ファイルの拡張子を .puml または .plantuml にします。
2. ファイルにシーケンス図のコードを書いていきます。

シンプルに書くと以下の通りです。

@startuml
# ここで図上下のアイコンなど
actor ユーザー as User
participant "Web Server" as Web
database モデル as Photos
collections 画像S3 as S3

# ここで各フローを可視化する
User -> Web: POST /images
Web -> Photos: 検証
Photos -> User: if: [エラー] エラーメッセージを表示
Web -> S3: 画像URLを取得
Web -> Photos: データを作成
@enduml

シーケンス図のプレビュー

コードを記述した後、alt + D でプレビューを開くことができます。

シーケンス図の調整

必要に応じてシーケンス図のコードを調整し、プロセスの詳細や関連するアクションを追加しましょう。

使い方

先ほどのシーケンス図を見やすく書き換えていきす。

@startuml
actor ユーザー as User
participant "Web Server" as Web
box CarrierWave #whitesmoke
  database モデル as Photos #orange
  collections 画像S3 as S3 #pink
end box

group リクエストと検証
    User -> Web: POST /images
    activate Web
    Web -> Photos: 検証
    alt 検証エラー
        Photos -> Web: if: エラー
        Web -> User: エラーメッセージを表示
    end
end

group アップロード
    Web -> S3: 画像URLを取得
    Web -> Photos: データを作成
    deactivate Web
end
@enduml

• 処理をなるべくグループ化し、見やすくしてあげよう。
• 必要に応じて色をつけてあげよう。

※ 自身偉そうに言えるほど纏めるのはうまくはないんですが、シーケンス図にしてあげると喜ぶ人多いです。

エクスポート

• Ctrl + Shift + P でコマンドパレットを開く
• PlantUML: ファイル内のダイアグラムをエクスポート を選択すると、拡張子を指定したエクスポートが可能です。

慣れてくるとスラスラ書けるものの、あまりゴチャつかないように。
全てを網羅しようとせず、直感的なわかりやすさを意識しましょう！