TypeScript Compiler APIを利用したデータベースドキュメントの自動生成

はじめに

こんにちは！バックエンドエンジニアの中野です。

突然ですが皆さん、データベースのドキュメントはどのように運用されてますか？

ドキュメントの管理はどの会社でも課題になることがあるかと思います。令和トラベルも例外ではなく、ドキュメントの運用方法で課題がありました。今回は、そんな私たちの抱えていた課題を解決したTypeScript Compiler APIを利用したデータベースドキュメントの自動生成について紹介したいと思います！

データベースドキュメントが必要な背景

令和トラベルでは、データベースの活用が社内の様々な部門に広がっています。

例えば、マーケティングチームを例にすると、分析メンバーが予約状況を可視化するダッシュボードをRedashで作成するといったことがあります。

もしデータベースドキュメントがない場合、その分析メンバーたちはテーブル名やカラムの情報のみから自分の集計したい目的に応じてクエリを書かないといけないことになります。

テーブル名やカラム名のみでデータベースを理解することはエンジニア以外だけでなく、中途入社でジョインするエンジニアにとってもかなり辛い作業になってしまいます。

このようなことからエンジニア以外のメンバーでもデータベースを理解できるようにするために、テーブル定義やテーブル間の関係を理解できる環境が必要とされていました。

従来の取り組みと課題

この課題に対して私たちはSchemaSpyを導入し、データベースのエンティティ関係図を含むHTMLドキュメントを生成して公開していました。

テーブルのメタデータを使用した場合、コメントを追加する際に対象オブジェクトに対してメタデータロックがかかるため、データベースの外で管理するようにしました。SchemaSpyの導入により、エンジニア以外のメンバーはデータベースの構造を視覚的に理解できるようになり、必要な情報へのアクセスが容易になりました。

しかし、この解決策は新たな課題を生み出すことになります。エンジニア以外のメンバーがデータベースの中身を理解しやすくなった一方、エンジニアはSchemaSpyへのドキュメント反映作業が負担となっていたのです。

従来のドキュメント反映方法は以下のプロセスで行なっていました。

説明を記載したマークダウンファイルを作成

SchemaSpyのメタ情報の形式に則したXMLファイルに変換する

この反映方法でも十分自動化されていて便利だったのですが、課題が1点ありました。それはソースコードとテーブル定義ドキュメントが別ファイルとして管理されている点です。

このように別ファイルとして書かれていることで、ドキュメントの作成を忘れ、反映が漏れてしまうケースが発生していました。

上記の課題を解決するために私は、以下2点のゴールを設定しました。

💡

コメントとソースファイルを一箇所にまとめる

エンジニアにコメントを追加することのメリットを作る

コメントとソースファイルを1つのファイルにすることで、コメントを書きやすくし、エンジニアの負荷を減らせます。さらに、エンジニアがコメントを書くことで開発しやすい環境を作ることができるなら、エンジニアがコメントを積極的に書くようになると考えました。

JSDocとTypeScript Compiler APIの活用

私は上記の目的を達成するために、JSDocとTypeScript Compiler APIを用いたドキュメント自動生成の仕組みを導入しました。

今まではマークダウンでドキュメントを別ファイルで管理していましたが、ソースファイルにJSDocでコメントを記載する方針に変更しました。

JSDocは、JavaScriptのソースコードに注釈を追加するために使われるマークアップ言語です。JSDocを使用することで、ソースファイルとドキュメントを1箇所にまとめました。

また、JSDocで記載することで、エディター上でそのコメントをホバー形式で表示可能となり、開発中に簡単にコメントを確認できるようになることで、エンジニアにとってもコメントを書くことの直接的なメリットが生まれました。

このJSDocで目的を達成できるのですが、SchemaSpyでコメントを確認できるようになるためには、これらJSDocのコメントをSchemaSpyへ反映させなくてはなりません。

そこで私は、TypeScript Compiler APIを使ってソースファイルからJSDocを抽出し、XMLファイルを作成することにしました。TypeScript Compiler APIはTypeScriptのコードをプログラムで解析・操作できるようにするためのAPIです。ソースコードを変換したASTを元に解析処理が可能です。

TypeScript Compiler APIを使用することで、ソースファイルを解析してJSDocを抽出することが容易に実装可能でした。また、JSDocだけでなく@Entityなどの情報もAPIを通して取得できるのでソースファイルの特定も容易にできました。

実装のプロセス

実装は以下2つのフェーズに分けました。

既存のマークダウンファイルからJSDocコメントへの移行

JSDocからSchemaSpyにおけるメタデータの形式に則したXMLファイルを作成

これによって既存のマークダウンファイルをJSDocに移行し、そのJSDocからSchemaSpyへ反映する方針への完全移行を進めました。

第１フェーズ　既存のマークダウンファイルからJSDocコメントへの移行

第１フェーズでは、既存のマークダウンファイルからJSDocコメントへの移行を行いました。まず、マークダウンファイルを検出してパースし、テーブルとカラムの定義を抽出します。次に、これらの情報をJSDocコメントに変換し、TypeScript Compiler APIを使用してソースファイルに適用しました。


 ...

  // カラムのJSDocを更新
  ts.forEachChild(sourceFile, (node) => {
    if (
      ts.isClassDeclaration(node) &&
      node.name &&
      node.name.text === entityName
    ) {
      node.members.forEach((member) => {
        if (
          ts.isPropertyDeclaration(member) &&
          member.name &&
          ts.isIdentifier(member.name)
        ) {
          const propertyName = member.name.text;
          if (columnJSDocs[propertyName]) {
            ts.getDecorators(member)?.forEach((decorator) => {
              // デコレータ名にColumnが含まれているかを特定
              if (decorator.getText().includes("Column")) {
                ...
                if (!hasJSDocComment(member, sourceFile)) {
                  updatedContent =
                    updatedContent.slice(0, propertyStart) +
                    columnJSDocs[propertyName] +
                    "\n " +
                    updatedContent.slice(propertyStart);
                  offset += columnJSDocs[propertyName].length + 2;
                }
              }
            });
          }
        }
      });
    }
  });
...
}

上記コードはTypeScriptのソースファイルにJSDocを適用するコードの一部です。このコードではプロパティについているデコレータを取得し、そのデコレータ名にColumnが含まれているか確認することで、@PrimaryColumn、@Columnのついているプロパティの上部にマークダウンから作成したJSDocを挿入しています。

このようにTypeScript Compiler APIを使用することでソースファイルのデコレータを位置を特定する様なコードは簡単に書けました。

ただこのコードだと対応できないパターンもありました。例えば@Entityの上に別のデコレータがついているパターンです。

上記のようなイレギュラーケースも対応することもできましたが、マークダウンからの移行が済めば使うことのない実装だったという点と、10コメントと失敗しているパターンが少なかった点から手動で修正しました。

このようなことから、解析観点でもコードの書き方が揃っているという点は大事だと改めて学ぶことができました。

第２フェーズ　JSDocからSchemaSpyにおけるメタデータの形式に則したXMLファイルを作成

第２フェーズでは、JSDocからSchemaSpyのXMLファイルを生成する処理を実装しました。まずは、ソースファイルを読み込み ts.createSourceFile でASTの構造に変換します。これによってコードの構造を階層的に扱うことが可能になります。


// ソースファイルからASTを作成
const sourceFile = ts.createSourceFile(
  filePath,
  sourceCode,
  ts.ScriptTarget.Latest,
  true
);

そのASTを走査する形でソースファイルを解析してJSDocを抽出していきます。


// AST(Abstract Syntax Tree)の走査
  const visit = (node: ts.Node) => {
    if (ts.isClassDeclaration(node) && node.name && hasEntityDecorator(node)) {
      entities.push({
        name: camelToSnake(node.name.text),
        description: getJSDocDescription(node),
        properties: extractProperties(node),
      });
    }

    if (!ts.isClassDeclaration(node)) {
      ts.forEachChild(node, visit);
    }
  };

  visit(sourceFile);

@Entityがついているクラスを特定するコードは以下のように書きました。TypeScript Compiler APIを利用するだけで簡単にデコレータがあるかを取得することが可能です。


const hasEntityDecorator = (node: ts.ClassDeclaration): boolean => {
  // クラス宣言からデコレータのリストを取得
  const decorators = ts.getDecorators(node);
  ...

  return decorators.some((decorator) => {
    // デコレータが正しい形式かチェック
    if (ts.isDecorator(decorator) && ts.isCallExpression(decorator.expression)) {
      const expression = decorator.expression.expression;
      // 識別子が'Entity'という名前かチェック
      return ts.isIdentifier(expression) && expression.text === "Entity";
    }
    return false;
  });
};

JSDocを取得するコードも以下のようにシンプルに実装できます。（実装段階では気づかなかったのですが、 ts.isJSDocを用いればもっとシンプルに書けそうです。）


// JSDocコメントから説明文を取得
const getJSDocDescription = (node: ts.Node): string | undefined => {
  const jsDocComments = (node as any).jsDoc;
  if (jsDocComments && jsDocComments.length > 0) {
    return jsDocComments[0].comment;
  }
  return undefined;
};

上記の要素を組み合わせてソースファイルのJSDocを抽出し、SchemaSpyのメタデータ形式に則したXMLファイルへの変換を実装しました。

導入の成果と今後の展望

あたらしい仕組みの導入により、全64ファイルに及ぶテーブル定義を全てJSDocのコメントに変換し、そのJSDocを用いてSchemaSpyにコメントを反映できるようになりました。これによって、エンジニアはホバー機能で詳細を確認できるようになり、ソースコードとコメントが一箇所で管理できるようになりました。

しかし、いくつかの課題も残されています。現在、マークダウンのコメント定義にないテーブルやカラムについては、JSDocもSchemaSpyのコメントも反映できていない状態です。この課題に対応するため、GitHub ActionsでPR時にソースファイルのJSDoc記載をチェックする機能の導入や、モジュールごとのコメント記載率の可視化などをしていきたいと思っています。