オブジェクトのメソッド: @EqualsAndHashCode、@ToString、@CopyWith

@EqualsAndHashCode、@ToString、@CopyWith は、データクラスに ==、hashCode、toString()、一部の値だけを変えたコピーを与えます。ジェネレーターがクラスのフィールドから書き出します。

使う理由

データクラスには同じメソッドが何度も必要です。同じ値を持つ二つのオブジェクトは等しく、Set の中で互いを見つけられるべきです。toString() はフィールドを表示すべきです。値を一つ変えるために、他の値をすべて手でコピーしたくはありません。これらを書いて保守するのは間違いのもとで (新しいフィールドを hashCode に入れ忘れる)、toString() は簡単にパスワードをログに出してしまいます。

四つのアノテーションは、ジェネレーターにそれらを書かせます。どれもクラスを記述の対象にします (@Introspected は不要です)。オプションはパラメーターだけです。

例

import 'package:spring_core_dart/spring_core_dart.dart';
// copyWith is in the module's generated file:
import 'package:shop/spring_gen/src/app.spring.introspection.dart';

@EqualsAndHashCode()
@ToString(mask: ['card'])
@CopyWith()
class Book with IntrospectedObject {
  const Book({
    required this.title,
    this.pages = 0,
    this.tags = const [],
    this.card,
  });

  final String title;
  final int pages;
  final List<String> tags;
  final String? card;
}

final dune = Book(title: 'Dune', tags: ['sf', 'classic']);

dune == Book(title: 'Dune', tags: ['sf', 'classic']); // true (lists by content)
dune.toString();
// Book(title: Dune, pages: 0, tags: [sf, classic], card: ******)
dune.copyWith(pages: 412);        // the other values are kept
dune.copyWith(card: null);        // null clears a nullable field

何がどこに生成されるか

自分のファイルには何も書き込まれません。ジェネレーターは、コードをモジュールの lib/spring_gen/<library>.spring.introspection.dart に置きます。

ミックスイン IntrospectedObject (フレームワークのもので、手で一度だけ書かれています) が、オブジェクトの実行時の型でその関数を見つけます。その ==、hashCode、toString() がそれらを呼びます。そのためクラスには with IntrospectedObject が必要で、欠けているとビルドがそう伝えます。自分の記述を持たないサブクラスは、記述のある最も近いスーパークラスのものを使います。

copyWith はクラスのメンバーではないので、それを呼ぶライブラリは生成されたファイルをインポートします。クラス自身のファイルには何も要りません。

アノテーション

アノテーション パラメーター 与えるもの
@EqualsAndHashCode include、exclude、callSuper == と hashCode
@ToString include、exclude、includeNames、callSuper、mask、reveal toString(): Book(title: Dune, pages: 412)
@CopyWith include、exclude、constructor 型付きの copyWith

フィールド

対象のフィールドは、クラスが宣言する public のインスタンスフィールドで、宣言の順です。include は使うものだけを、exclude は外すものを指定します (両方は不可)。callSuper はスーパークラスの部分 (その記述のもの、またはそれ自身のメソッド) を加えます。List、Set、Map 型のフィールドは、ネストしたものも含めて内容で比較され、ハッシュされます。異なるクラスのオブジェクトが等しくなることはありません。private なフィールドは生成されたライブラリから読めないため、警告つきで外されます。

記述が登録されていないと、この三つのメソッドは登録の仕方を伝える StateError を投げます。黙って同一性で比較することはありません。

秘密のマスク

@ToString は、名前が秘密らしく見えるフィールド (password、apiKey、refresh_token など) を ****** と書きます。mask に挙げたフィールドも同じです。reveal は、規則が隠すフィールドをそのまま表示します。これはビルド時に決まります。マスクされたフィールドの値は一度も読まれません。

ログではオブジェクトが toString() を通して出力されるため、マスクはそこに効きます。JSON の出力には効き ません。フィールドを JSON に出さないようにするには、@JsonProperty('', access: JsonPropertyAccess.writeOnly) を使います。

copyWith

省略した引数は値を保ち、null は nullable なフィールドを消し、型の違う値はコンパイルできません。コピーは、名前のないコンストラクター (または constructor が指定するもの) で作られるため、各フィールドはコンストラクターのパラメーターと名前が一致する必要があります。

単体テストでは

記述は、コンテキストが起動するときに登録されます。コンテキストのない単体テストでは、生成されたファイルのゲッターで自分で登録します。

import 'package:shop/spring_gen/src/app.spring.introspection.dart';

void main() {
  setUpAll(() => Introspector.shared.registerAll($appIntrospections));
  // ...
}

ビルドエラー

ビルドは、どの誤用に対しても、直し方を示すメッセージで失敗します。ミックスイン、列挙型、抽象クラスへのアノテーション、with IntrospectedObject のないクラス、include と exclude の併用、フィールドでない名前 (「もしかして」つき)、mask と exclude の両方にある名前、そして copyWith が使えないコンストラクターです。final でないフィールドが hashCode に入っているときは警告します。

ビルドのキーはありません。メソッドはアプリケーションの実行時の動作で、どのビルドでも同じです。

Spring (Java) との対応

Spring にはこのようなアノテーションはありません。Lombok にあり、これらはそれに倣っています。

@EqualsAndHashCode(exclude = "cover")
@ToString(exclude = "cover")
@With
class Book { String title; int pages; byte[] cover; }

Spring 自身の道具は、手で書く方法です。ObjectUtils.nullSafeEquals、ObjectUtils.nullSafeHashCode、ToStringCreator です。

重要な違い:

関連項目