MongoDBドキュメントクラスをJSONに変換!

MongoDBドキュメントクラスを入力するとサンプルJSONを作ります!Spring Data MongoDB @Document 対応。API ドキュメントやテスト用のリクエストボディ(sample JSON)に。
Spring Data MongoDB
結果
 

MongoDBドキュメントクラスをJSONに変換!

Spring Data MongoDB の @Document クラスを埋め込みのクラスや record と一緒に渡すと、コントローラーがそのドキュメントを返したときのレスポンスの例を JSON で作ります。形は Spring Boot の既定の Jackson シリアライズに従うので、MongoDB に保存される BSON ではなく API のレスポンスを表します。

埋め込みのリスト、Map のフィールド、Instant のタイムスタンプだらけの MongoDB ドキュメントでは、レスポンスのサンプルを手で書くのは面倒です。その手間が省けるうえ、保存形式とレスポンス形式の違いも見えるようになります。

使い方

  1. Spring Data MongoDB 欄に、@Document クラスとその埋め込みのクラスや record を貼り付けます。
  2. 他のどのクラスからも参照されていないドキュメントクラスが、出力のルートになります。
  3. ドキュメントやテストに JSON を使う前に、id や日付の仮の値を現実的な値に置き換えてください。

例

入力 (Java · Spring Data MongoDB)
@Document(collection = "devices")
public class Device {
    @Id
    private String id;
    private String serial;
    @Field("fw")
    private String firmwareVersion;
    private Map<String, Double> lastReadings;
    private List<Alert> alerts;
    private Instant registeredAt;
}

record Alert(String level, String message, Instant raisedAt) {}
出力 (JSON)
{
  "id": "",
  "serial": "",
  "firmwareVersion": "",
  "lastReadings": {
    "key": 0
  },
  "alerts": [
    {
      "level": "",
      "message": "",
      "raisedAt": "1970-01-01T00:00:00Z"
    }
  ],
  "registeredAt": "1970-01-01T00:00:00Z"
}

List<Alert> の Alert は record なので、コンポーネントの level、message、raisedAt がフィールドになります。Map<String, Double> は {"key": 0} に、Instant は Z で終わる UTC の文字列になります。@Field("fw") が変えるのは MongoDB に保存されるフィールド名だけなので、JSON のキーは firmwareVersion のままです。

対応機能

  • record Alert(String level, ...) のような Java の record のコンポーネントをフィールドとして読み取ります。
  • List と Set は要素1つの配列に、Map<String, T> は {"key": value} になります。
  • Instant、ZonedDateTime、OffsetDateTime は 1970-01-01T00:00:00Z を、LocalDateTime はオフセットのない文字列を出力します。
  • ObjectId 型のフィールドには、16進数のサンプルの ObjectId 文字列が入ります。
  • @DBRef でつないだクラスは、入力に含まれていればネストしたオブジェクトになります。
  • @JsonIgnore、@JsonProperty、@JsonIgnoreProperties、継承したフィールドは、JPA のページと同じルールに従います。

利用シーン

埋め込みドキュメントの多いレスポンス

レビューの一覧、オプションのマップ、履歴の配列など、MongoDB が1つのドキュメントに詰め込む構造は、レスポンス例も長くなります。クラスを貼り付ければ、ネストしたすべての階層を書き出してくれます。

保存される形と返される形を比べる

@Field による短い名前や _id に対応付けたフィールドがあると、データベースのキーと API のキーが食い違います。出力は API 側を示すので、2つを並べて比べられます。

注意点と制限

  • @Field("...")、@Indexed、@TextIndexed のようなマッピング用のアノテーションは JSON のキーを変えないので、反映されません。
  • @Id String id は _id として保存されますが、Jackson からは id として出ていくので、出力もそうなっています。
  • Spring Boot の既定の Jackson は、org.bson.types.ObjectId を16進数の文字列ではなく timestamp と date を持つオブジェクトとして書き出します。ここに示した文字列の形で送るには、ToStringSerializer を登録するか、String の id を使ってください。
  • GeoJsonPoint のような Spring Data の型も含め、入力にないクラスは null になります。

よくある質問

@Id は ObjectId と String のどちらにすべきですか?

String にすれば、Spring Data が保存時に ObjectId に変換し、API はきれいな16進数の文字列を返します。ObjectId 型のままにすると、レスポンスのために Jackson の追加設定が必要になります。

@DBRef のフィールドは本当にネストしたオブジェクトで返ってきますか?

@DBRef は読み込み時に(lazy なら最初のアクセス時に)参照先のドキュメントを解決するので、レスポンスにはネストしたオブジェクトが入ります。ObjectId や String の id だけを保存する手動の参照なら、id だけが返ります。

自由形式の Map<String, Object> フィールドはどう表示されますか?

値の型がわからないので {"key": null} になります。ドキュメントに載せる前に、実際に保存している種類の値に置き換えてください。