🗂

HARファイルをシーケンス図に変換するツールを作成しました

2024/06/08に公開

Mermaid

シーケンス図

tech

概要

Webサービスの動きを理解する上で、HTTPリクエストとレスポンスの流れを視覚化することは非常に有効です。様々なエンドポイントを経由する場合、新しく加わったメンバーにどのエンドポイントがどの順番でアクセスされているのかを説明する必要があります。シーケンス図を書いたドキュメントを常に新鮮に保っておけば楽ですが、手動で管理している場合はなかなかしんどいです。

ドキュメント作成を楽にするために、HARファイルからMermaid.jsのシーケンス図を自動生成するツールを作成しました。

以下は実行イメージです。

$ har2sequence -config config.yaml -har ./www.google.com.har
sequenceDiagram
    participant Browser
    participant www.google.com
    participant ogs.google.com
    Browser->>www.google.com: 🟢 GET /
    activate www.google.com
    www.google.com-->>Browser: 200
    deactivate www.google.com
    Browser->>www.google.com: 🟢 GET /complete/search
    activate www.google.com
    www.google.com-->>Browser: 200
    deactivate www.google.com
    Browser->>www.google.com: 🟢 GET /client_204
    activate www.google.com
    www.google.com-->>Browser: 204
    deactivate www.google.com
    Browser->>www.google.com: 🟢 GET /async/hpba
    activate www.google.com
    www.google.com-->>Browser: 200
    deactivate www.google.com
    Browser->>ogs.google.com: 🟢 GET /u/0/widget/app
    activate ogs.google.com
    ogs.google.com-->>Browser: 200
    deactivate ogs.google.com

この記事では作成したツールの使い方を紹介します。(主にREADMEの内容を翻訳したものになります)

(※ちなみにほぼ個人用に作ったものなのでエラーハンドリングなどはめっちゃ雑です！)

har2sequenceとは？

「har2sequence」は、HARファイルを解析し、その内容を基にシーケンス図を生成するツールです。このツールを使用することで、HTTPリクエストとレスポンスの流れを直感的に理解できる視覚的な図として表現することができます。以下では、主な機能や使い方について詳しく説明します。

主な機能

HARファイルの読み込み: HARファイルを解析して、HTTPリクエストとレスポンスのデータを抽出します。
シーケンス図の生成: mermaid.jsを使用して、HARデータからシーケンス図を生成します。これにより、HTTPリクエストとレスポンスの流れを視覚的に表示します。
設定ファイルのサポート: YAML形式の設定ファイルを使用して、参加者、除外パス、メッセージプレフィックスなどをカスタマイズできます。

インストール方法

「har2sequence」は、事前にビルドされたバイナリファイルをダウンロードしてインストールすることができます。以下のコマンドを使用して、適切なバイナリをダウンロードし、各環境の$PATHの通ったところに配置します。

Macの場合、curlとchmodそれぞれsudoが必要かもしれません。自分はなんとなく強権を振るいたくないので、別途自作コマンド配置用のディレクトリを作って$PATHを通してます。

curl -L -o /<your-PATH-directory>/har2sequence https://github.com/tasuku43/har2sequence/releases/download/v0.1.0/har2sequence-<your-os-and-arch>
chmod +x /<your-PATH-directory>/har2sequence

例えば、Mac（arm64）の場合、以下のコマンドを使用します。

curl -L -o /path/to/bin/har2sequence https://github.com/tasuku43/har2sequence/releases/download/v0.1.0/har2sequence-macos-arm64
chmod +x /path/to/bin/har2sequence

他のプラットフォーム用ダウンロードリンク

使い方

「har2sequence」を使用するには、以下のコマンドを実行します。

har2sequence -config <path_to_config_file> -har <path_to_har_file>

例えば、config.yamlという設定ファイルとexample.harというHARファイルを使用する場合、以下のコマンドを実行します。

har2sequence -config config.yaml -har example.har

設定ファイルの例

設定ファイルはYAML形式で記述します。以下は、config.yamlの例です。

participants:
  - "example.com"
  - "api.example.com"
excludePaths:
  - "example.com/exclude-this-path"
  - "api.example.com/exclude-this-path"
messagePrefixes:
  GET: "🟢 "
  POST: "🟠 "
  PUT: "🟣 "
  PATCH: "🟡 "
  DELETE: "🔴 "

Configパラメータの説明

participants: シーケンス図に含めるドメインリスト。ここに指定したドメインがシーケンス図に表示されます。ここを絞らないと関心外のリクエスト/レスポンスもたくさん出ちゃいます。未指定の場合は、すべてのドメインをシーケンス図に表示します。
excludePaths: シーケンス図から除外するURLパスのリスト。ここに指定したパスはシーケンス図に表示されません。例えば、jsファイルの取得やcssファイルの取得は除きたい時などに便利です。具体的な使用例は後述のケーススタティを参照してください。
messagePrefixes: シーケンス図で使用するHTTPメソッドごとのプレフィックスのマップです。例えば、GETリクエストには「🟢」を付けるなど、リクエストの種類ごとにプレフィックスを設定できます。色がついてるとだいぶ視覚的に楽になります！

Googleのホームページのシーケンス図を生成するケーススタディ

ここでは、Googleのホームページにアクセスした際のHARファイルを使用してシーケンス図を生成する例を紹介します。
自分はChromeを使っているので、HARファイルは以下の手順で取得しました。

設定ファイルの例

participants:
  - "www.google.com"
  - "ogs.google.com"
excludePaths:
  - "www.google.com/js"
  - "www.google.com/xjs"
  - "www.google.com/images"
  - "www.google.com/gen_204"
messagePrefixes:
  GET: "🟢 "

シーケンス図の生成

以下のコマンドを実行します。

har2sequence -config config.yaml -har ./www.google.com.har

生成されるシーケンス図の例

このシーケンス図は、Googleのホームページにアクセスした際のHTTPリクエストとレスポンスの流れを示しています。

依存関係

このプロジェクトは以下の依存関係を使用しています。

gopkg.in/yaml.v2: YAML設定ファイルの解析に使用。

余談

実装もREADMEの記述もほぼChat-GPT4oとGitHub Copilotにやってもらいました。まずは「GoでHARファイルからmermaid.jsのシーケンス図を作りたい」ということを伝え、あとは「こういうstructを作って欲しい」「その処理はこのstructに持たせたい」など注文してく事でどんどん実装してくれて助かりました。

「READMEを書いて！」と言ったら70%くらいの出来のものを出力してくれるのでそれを微修正しました。

AIすごい！！

概要

har2sequenceとは？

主な機能

インストール方法

他のプラットフォーム用ダウンロードリンク

使い方

設定ファイルの例

Configパラメータの説明

Googleのホームページのシーケンス図を生成するケーススタディ

設定ファイルの例

シーケンス図の生成

生成されるシーケンス図の例

依存関係

余談

Discussion