オブジェクトのメソッド: @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 に置きます。
==、hashCode、toString()は、クラスの記述 (Introspection.objectMethods) にある型付きの関数です。copyWithは拡張 (extension $Book on Book) で、そのcopyWithは関数型のゲッターです。
ミックスイン 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 です。
重要な違い:
- Lombok はコンパイル時にメソッドをクラスに書き込みます。ここではジェネレーターがクラスの記述に書き出し、クラスはそれを呼ぶ
IntrospectedObjectをミックスインします (withが一つ、自分のファイルに生成されるメンバーはありません)。 copyWithは、呼び出すライブラリがインポートする生成ファイルにあります。Lombok の@Withはクラスのメンバーです。@WithはフィールドごとにwithTitle(...)を作りますが、ここでは一つのcopyWithがすべてを名前付き引数で受け取り、nullで消せます。- ビルダーはありません。Lombok のビルダーの役目は、Dart の名前付きコンストラクター引数と
copyWithが果たします。