typescript-generatorを利用して、HTML に埋め込んだ JSON データをフロントエンドで型安全に扱う

こんにちは！kintone フロントエンドリアーキテクチャチーム (フロリア) の西川 @nissy_devです。

最近のフロントエンド開発で導入されることの多い TypeScript ですが、開発期間の長いプロジェクトに導入する際にはバックエンドとの結合部分の型定義をどう扱うかが問題になる場合があると思います。

今回の記事では、フロリアで取り組み始めた、HTML に埋め込んだ JSON データをフロントエンドで型安全に扱う施策について紹介します。 フロリアのプロジェクトの詳細については、 @koba04が書いた次の記事をご覧ください。

blog.cybozu.io

目次

• フロリアでのバックエンドからのデータ取得
• HTML に JSON データを埋め込む方法の問題点
• Java のクラスから TypeScript の型定義を生成できる typescript-generator
• typescript-generator の導入
  • プロパティに readonly を付与する
  • Java の DateTime 型を TypeScript の string 型に変換する
  • Java が null 安全でないことへの対応
  • カスタムシリアライザへの対応
  • 生成された型定義の利用方法
• 導入して感じたメリットとデメリット
  • 👍 メリット
  • 🙈 デメリット
• まとめ

フロリアでのバックエンドからのデータ取得

フロリアで刷新を進めている画面のフロントエンドは、バックエンド側でルーティングを行う Multi Page Application となっており、フロントエンドがバックエンドからデータを取得する方法については次の 2 つが存在しています。

• API を作成し、フロントエンドから API を呼び出す
• テンプレートエンジンを利用して HTML に JSON データを埋め込み、フロントエンドが参照する

フロリアでは、HTML に JSON データを埋め込む方法を多く採用しています。 これは、既存の画面においても HTML に JSON データを埋め込む方法が多く採用されており、バックエンドの実装を再利用できる場面が多いためです。 フロリアに参加しているエンジニアの多くはフロントエンドを得意としており、Java で API を実装するのはコストが高いと判断しました。¹

HTML に JSON データを埋め込む方法の問題点

kintone では FreeMarker Templateという Java ベースのテンプレートエンジンを利用して HTML に JSON データを埋め込みます²。

<script>  globalData.samplePageData = ${json(samplePageData)}// Javaで生成されたデータをJSONにシリアライズ</script>

フロントエンドからは、globalData.samplePageDataのように参照します。 フロリアで刷新している画面は TypeScript で実装されており、globalData.samplePageDataなどのデータに適切な型をアノテーションする必要がありました。 初めは、各データに対応する Java のクラスを確認しながら手作業でアノテーションを行っていましたが、次第に次のような問題が生じるようになりました。

• Spring Framework と FreeMarker Template をベースとしたバックエンドの実装を理解するコストが高い
• バックエンド変更時における型定義への影響範囲を把握するのが難しい
• 埋め込まれるデータが複雑なケースもいくつか存在し、付与するアノテーションを誤ってしまう可能性がある
• Java は null 安全でないため、ある型で定義された変数に null が代入される可能性がある

これらの問題点を踏まえて、今後も多くの画面を刷新していく必要があることから、Java のクラスから TypeScript の型定義を自動で生成する方法を調査することになりました。

Java のクラスから TypeScript の型定義を生成できる typescript-generator

調査をすすめると、Java のクラスから TypeScript の型定義を生成できる typescript-generatorというツールが見つかりました。

github.com

たとえば、次のような JSON シリアライズ可能な Java のクラスがあったとします。

publicclass User {
    privateint id;
    private String name;
}

このような Java のクラスに対して typescript-generatorを使えば、 TypeScript のインターフェイスを自動生成できます。

interface User {
  id: number;
  name: string;}

Java のプリミティブ型以外にも、Date、List、Enumなど、基本的な型を一通りサポートしています。 さらに、ツールのパラメータ一覧を見てみると、出力ファイルの名前の設定から独自定義による型変換まで、非常に柔軟な設定が可能です。 現時点ではライブラリのメンテナンスも比較的行われている³ことから、フロリアでも PoC として導入してみることにしました。

typescript-generator の導入

kintone では Java のビルドツールに Maven を使っており、typescript-generatorが提供している Maven プラグインを利用できます。 kintone のビルド環境へ適用する際には、pom.xmlに次のようなプロファイルを追加し、型生成に関する設定をオプトインできるようにしました。

<profile><id>typescript-generator</id><build><plugins><plugin><groupId>cz.habarta.typescript-generator</groupId><artifactId>typescript-generator-maven-plugin</artifactId><version>2.35.1025</version><executions><execution><id>generate</id><goals><goal>generate</goal></goals><phase>process-classes</phase></execution></executions><configuration>
                    ...  // パラメータの設定を追加していく
                </configuration></plugin></plugins></build></profile>

型生成は Maven の process-classesのフェーズで実行されるので、型生成をする場合には mvn process-classes -P typescript-generatorを実行します。 typescript-generatorの細かいパラメータの設定については、ドキュメントで丁寧に解説されているので、すでに紹介したパラメータ一覧を確認するのがおすすめです。 ここでは、kintone のコードへ typescript-generatorを適用した際に工夫した点について紹介します。

プロパティに readonly を付与する

今回の型生成の対象となるデータについては、フロントエンドでは参照のみをしたい場合が多いです。 このような場合には、declarePropertiesAsReadOnlyのパラメータを利用し、生成されるインターフェイスのプロパティに readonlyがつくようにします。 デフォルトでは falseなので、利用した際には trueの設定を加えました。

<declarePropertiesAsReadOnly>true</declarePropertiesAsReadOnly>

Java の DateTime 型を TypeScript の string 型に変換する

kintone のバックエンドでは、日付データに java.timeや Joda Timeなどを利用していますが、フロントエンドでは JSON にシリアライズされた文字列のデータを参照します。 このような場合には、mapDateのパラメータを利用し、Java の日付データの型を TypeScript の string 型に変換します。 デフォルトでは asDateなので、利用した際には asStringの設定を加えました。

<additionalDataLibraries>joda</additionalDataLibraries><mapDate>asString</mapDate>

Java が null 安全でないことへの対応

Java は、ある型で定義された変数に null が代入できるため、型変換の際にはこの null をどう扱うかが問題になります。 今回の型生成の対象となるデータに関しても、多くの場合で次のような Lombok で定義されたクラスになっており、プロパティが null になるケースもいくつか確認できました。

import lombok.Setter;
import lombok.Getter;

@Setter@Getterpublicclass SamplePageData {
    private String data1;
    private String data2; // ランタイムで null が代入される可能性がある...
}

今回の導入では、フロントエンドとバックエンドのデータのやり取りの不具合をなるべく減らしたかったことから、プロパティを基本的に nullable になるように変換しました。 また、@NotNullなどの null チェックやバリデーションに関するアノテーションがついている場合には、例外として nullable にならないように変換しました。

この方針をパラメータに直すと次のようになります。 optionalPropertiesDeclarationは、requiredAnnotationsで指定されたアノテーションがついてないすべてのプロパティを optional とするパラメーターです。 optional の方法にはいくつかあるのですが、ここでは nullable になるように変換しています。

<optionalPropertiesDeclaration>nullableType</optionalPropertiesDeclaration><requiredAnnotations><annotation>lombok.NotNull</annotation>
        ... // nullable にしたくない場合のアノテーションを追加する
</requiredAnnotations>

カスタムシリアライザへの対応

今回の型生成の対象となるデータの中には、Jackson の StdSerializerを拡張したカスタムシリアライザを適用しているケースがありました。 このカスタムシリアライザは、シリアライズ過程でプロパティの型を変換する処理を行っており、この処理に対応した型を生成する必要があります。 そこで、カスタムシリアライザの処理に対応した typescript-generator向けの独自拡張を実装しました。

typescript-generatorは、型変換の際に拡張を適用できるシステムを持っており、メンテナーが実装したいくつかの拡張があります。 これらの実装を参考にしながら、今回の拡張についても実装しました。 実装した拡張については、次のような設定を追加することで利用できます。

<extensions><extension>xxx.yyy.zzz.SampleExtension</extension>
      ... // 利用したい拡張のクラスを追加する
</extensions>

ここでは実装の詳細については触れませんが、次のリポジトリで拡張のサンプルを実装してみたので、参考にしてもらえればと思います。

github.com

生成された型定義の利用方法

今まで紹介した設定を適用した型変換を、次のような JSON データのクラスに実施します。

import lombok.Setter;
import lombok.Getter;
import lombok.NotNull;
import org.joda.time.DateTime;
import xxx.yyy.zzz.CustomSerializer; // List<int> を List<String> に変換するようなシリアライザだとする@Setter@Getterpublicclass SamplePageData {
    private String data1;
    @NotNullprivate Integer data2;
    private DateTime data3;
    @JsonSerialize(using = CustomSerializer.class)private List<Integer> data4;
    ...
}

すると、次のような TypeScript のインターフェイスが生成されます。

exportinterface SamplePageData {readonly data1: string | null;readonly data2: number;readonly data3: string | null;readonly data4: Array<string> | null;
  ...
}

そして、上記のインターフェイスをグローバル変数の型定義に利用することで、HTML に埋め込んだ JSON データをフロントエンドからも安全に扱うことができました。

importtype{ SamplePageData }from".....";declarenamespace globalData {readonly samplePageData: SamplePageData;}

導入して感じたメリットとデメリット

今回の導入における typescript-generatorのメリットとデメリットをまとめてみます。

👍 メリット

• フロントエンド側の型定義を自動生成することによる実装コストの削減
• Java のコードから生成される型なので、手動でアノテーションするより安全
• 豊富なパラメータや拡張を適用できるシステムにより、柔軟な型生成が可能

🙈 デメリット

• フロントエンドとバックエンドとのインタフェース部分は、Java クラスでデータモデル化しておく必要がある
• 生成される型が基本的に nullable であるため、フロントエンド側でバリデーションを実装するコストがかかる
• Java のビルド環境に依存したツールであり、フロントエンドのビルド環境に組み込むことが難しい

このように、型生成を自動化できることによるメリットはありますが、バリデーションの実装コストなども考慮して導入する必要があると感じました。

まとめ

今回の記事では、HTML に埋め込んだ JSON データをフロントエンドで型安全に扱うために導入した typescript-generatorを紹介しました。 開発期間の長いプロジェクトでは、Open API や gRPC などを導入することが難しく、typescript-generatorのような型生成のツールが役に立つこともありそうです。 同様の悩みを持っているプロジェクトがあれば、 Java 以外の言語でも typescript-generatorのようなツールがある⁴ので、今回の記事が参考になれば幸いです。