Zenn
📖

Github Actionsでユビキタス言語を管理しよう！

2025/03/02に公開
GitHub
GitHub Actions
DDD
ドメイン駆動設計
ai駆動開発
tech

概要

この記事は、ユビキタス言語の管理を自動化するGitHub Actionsの紹介記事です。ドキュメントとソースコードを密接に関連付けることで、ユビキタス言語の統一と管理を容易にできます。
https://github.com/Glider2355/ubi-doc

執筆時点では下記の言語に対応しています。

  • PHP
  • Java
  • Kotlin
  • Ruby

主な機能

  • Docコメントに記載されたユビキタス言語、コンテキスト、説明、該当箇所へのリンクを含むHTMLを生成します。
  • 出力されたHTMLをGithub Pagesでホスティングすることでユキビタス言語表をチームに公開できます。

出力されるHTMLのデザインサンプルは下記をご参照ください！
https://glider2355.github.io/ubi-doc/

自動生成するメリット

Docコメントでユビキタス言語表を生成するメリットはいくつかあると考えています。

1. ドキュメントとソースコードの紐付け

Docコメントを基に自動生成されるため、ドキュメントがソースコードが紐づけされ、管理しやすくなります。

2. ソースコードの該当箇所が見つけやすい

HTMLには該当するソースコードのリンクが含まれており、ユビキタス言語の定義がどこで使用されているのかを簡単に特定できます。

3. AIによる理解の向上？？

Docコメントにユビキタス言語を明示することで、Copilot等がユビキタス言語を理解してくれる。。。かもしれません。

使い方の紹介

1. Docコメントでユビキタス言語を記載する

ユビキタス言語を設定したいクラスにDocコメントを記載します。

Example(PHP, Java, Kotlin)

/**
 * @ubiquitous オーダー
 * @context ショップ
 * @description 顧客の注文書を表します。
 */
class Order

Example(Ruby)

# @ubiquitous オーダー
# @context ショップ
# @description 顧客の注文書を表します。
class Order

2. リポジトリの設定

Github ActionsのPR作成を許可します。
Setting > Actions > Generalで下記のようにPR作成を許可する必要があります。

Github PagesでHTMLの生成先のディレクトリを指定します。
下記の画像ではmainブランチのdocsディレクトリのHTMLをホスティングしています。

3. GitHub Actionsの設定

READMEを参考にGithub Actionsを設定します。
ここでは各stepsの簡略的な記載内容を説明します！

  • steps
    • Checkout repository
    • UbiDoc
      • ユビキタス言語表のHTMLを生成します。
      • output_dirは出力先のディレクトリを設定してください。
    • Check for differences in ubi-doc directory
      • 生成されたHTMLと現在のdiffを確認します。
      • diffがない場合はその時点で終了します。
      • 生成先のディレクトリを指定する必要があります。
    • Close existing auto-generated HTML PRs
      • 過去に自動作成されたOpenのPRがあれば自動でクローズします。
    • Create Pull Request (via gh CLI)
      • 生成されたHTMLを元にPRを作成します。
      • 下記のように設定すると自動マージされます。
- name: Create PR
    run: |
      PR_URL=$(gh pr create \
        --base main \
        --head "$BRANCH_NAME" \
        --title "Add generated HTML via GitHub Actions" \
        --body "This Pull Request includes the latest auto-generated HTML files." \
        --json url -q .url)
      echo "PR_URL=$PR_URL" >> $GITHUB_ENV
    env:
      GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}

- name: Auto merge PR
    run: |
      gh pr merge --auto --squash "$PR_URL"
    env:
      GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}

さいごに

ユビキタス言語をDocコメントで管理する例は、筆者の知る限りではあまり見られません。
しかし、スプシ等で管理するのもそれはそれで大変です。コードとスプシが乖離する可能性があります。
「コードと乖離しないようにユビキタス言語を管理したい！」という方がいればぜひ使ってみてください！

Discussion