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

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

## 使う理由

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

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

## 例

```dart
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` が指定するもの) で作られるため、各フィールドはコンストラクターのパラメーターと名前が一致する必要があります。

## 単体テストでは

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

```dart
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 にあり、これらはそれに倣っています。

```java
@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` が果たします。

## 関連項目

- [イントロスペクション: 実行されるものだけ](../../spring-core-dart-generator/optimizations/introspection.md)
- [BeanModule](bean-module.md)
- [JSON](../json/index.md)
- [生成の仕組み](../../spring-core-dart-generator/how-it-works.md)
