
# 実行されるものだけ: イントロスペクション

`ObjectMapper`、バリデーション、データバインディング、SpEL は、クラスのプロパティを読み書きし、インスタンスを生成し、名前でメソッドを呼ぶ必要があります。Java はそれをリフレクションで行います。Dart には Flutter、Web、AOT 実行ファイルでリフレクションがないため、ジェネレーターは代わりに各クラスの記述を書き出します。プロパティを読む、設定する、コンストラクターを呼ぶ、メソッドを呼ぶクロージャーを持つ `Introspection` です。

記述は Bean ではなく、クラス (`@Introspected` のクラス、またはビルドが使用中と見つけたクラス) のものです。そのため型の名前は `Introspection`、`Introspector`、`IntrospectedProperty`、`IntrospectedMethod`、`IntrospectedConstructor`、`IntrospectedParameter` で、「Bean」はコンテナーの言葉のままです。古い `Bean...` の名前は、一回のリリースの間、これらの非推奨の typedef として残ります。`BeanWrapper` は Spring と同じ名前のままで、コンテキストのイントロスペクターは今も Bean `beanIntrospector` です。

ジェネレーターは、すべてのクラスのすべての部分を記述するわけではありません。ビルドから見える範囲で、**アプリケーションがクラスに対して行うことについてだけ** クラスを記述します。

## 使う理由

クラスの完全な記述には、プロパティごとのゲッターのクロージャーとセッターのクロージャー、すべてのパラメーターを持つコンストラクターの記述、メソッドごとのクロージャーがあります。DTO の多いアプリではそれが積み重なり、そのほとんどは決して実行されません。リクエストボディは生成されて値を入れられるだけで、JSON として読み返されることはありません。レスポンスは読まれるだけで、フレームワークが生成することはありません。

各クロージャーは、コンパイラーが残さなければならないコードです。クロージャーが決して呼ばれないことをコンパイラーは知りえないからです。そこでビルドは、何も使うのを見なかったものを省きます。記述は自分が何を保持しているかを示し、欠けている部分を必要とするコードは、クラス、部分、修正方法を示すメッセージで失敗します。

## 部分

| 部分 | 記述の中での形 | 書かれる条件 (クラスが...) |
|---|---|---|
| ゲッター | `IntrospectedProperty.get` | 書き出される: JSON に変換される、式から読まれる、設定からバインドされる |
| コンストラクターとセッター | `IntrospectedConstructor`、`instantiate`、`IntrospectedProperty.set`、`fromJson` | 読み込まれる: JSON から生成される、リクエストや設定からバインドされる |
| 制約付きプロパティのゲッター | 制約、`@Valid()`、`@Each()` を持つプロパティだけの `get` | バリデーションされる |
| メソッド | `IntrospectedMethod` | メソッドを呼びうる式の対象である |

クラスのアノテーションとそのプロパティのリスト (名前、型、アノテーション) は常に書かれます。

## 各部分を求めるもの

| アプリケーションでの使い方 | 部分 |
|---|---|
| コントローラーの戻り値の型 (`Future`、`Stream`、`ResponseEntity`、`Page` の中も)、`@ExceptionHandler` の応答 | ゲッター、そしてコンストラクターとセッター (テストは `mapper.readValue<BookDto>(res.body)` で応答を読み返し、`test/` はスキャンされないため) |
| `@RequestBody`、`@RequestPart` | コンストラクターとセッター |
| `@RequestBody @Valid()` | コンストラクターとセッター、そして制約付きプロパティのゲッター |
| WebSocket の `@OnMessage` ハンドラー | メッセージ: コンストラクターとセッター。返信: ゲッター |
| クライアントの引数 (Feign、`@WebSocketClient`) | ゲッター |
| クライアントの応答 | コンストラクターとセッター |
| `@ConfigurationProperties` | ゲッター、そしてコンストラクターとセッター (バインダーはプロパティを設定し、入れ子のオブジェクトをその場でバインドするために現在の値を読むため) |
| `mapper.readValue<T>`、`treeToValue<T>`、`readList<T>`、`readMap<T>` | `T`: コンストラクターとセッター |
| `mapper.writeValueAsString(v)`、`valueToTree(v)` | `v` の静的な型: ゲッター |
| `mapper.convertValue<T>(v)` | `v`: ゲッター。`T`: コンストラクターとセッター |
| WebSocket セッションの `sendJson(v)`、レジストリーの `broadcast(pattern, v)` | `v` の静的な型: ゲッター |
| `@PreAuthorize`、`@PostAuthorize`、`@PreFilter`、`@PostFilter` | 引数 (式が `#name`、`#p0`、`#a0`、`args`、`@PreFilter` では `filterObject` に触れる場合) または結果 (`returnObject`、`filterObject`): ゲッターとメソッド。`target`: Bean 自身 |
| `@Cacheable`、`@CachePut`、`@CacheEvict`、`@Caching` (key、condition、unless) | 同様: 引数、結果 (`#result`)、Bean (`target`) |
| ビルドがコンパイルしない `:#{...}` を持つ `@Query` (データスターター) | 式が到達するクラス: ゲッターとメソッド |
| `@JsonValue`、`@JsonAnyGetter`、`@JsonAnySetter` | それらが示すメソッド (ゲッター、またはセッターとともに) |
| 書き出されるクラスの `@JsonInclude(JsonInclusion.nonDefault)` | コンストラクターとセッターも: マッパーは各値を新しいインスタンスのものと比べる |
| 独自のアノテーション `@BeanMethodAnnotation()` を持つメソッド | そのパラメーターと戻り値の型のすべて: ビルドは自分のフレームワークがそれらで何をするかを知らない |
| `@Scheduled`、`@Secured`、WebSocket の `@OnOpen`、`@OnClose`、`@OnError` | なし |
| `@JsonView` が列挙するクラス | なし: 知られるだけ |

## 和集合と、クラスを構成するもの

複数の使い方で到達されるクラスは、それらの部分の **和集合** を受け取ります。レスポンスでもありリクエストボディでもあるクラスは、ゲッターと、コンストラクターとセッターを受け取ります。

クラスを構成するものは、そのクラスと同じ部分を受け取ります。プロパティの型、コンストラクターのパラメーターの型、`Page<BookDto>` の型引数、`@JsonSubTypes` が列挙するサブタイプです。プロパティ `List<OrderLine> lines` を持つレスポンス `Order` は、`OrderLine` も書き出し用に記述します。

## `ObjectMapper` の呼び出し

ビルドはマッパーの呼び出しを読み、その **静的な型** を使います。

```dart
final book = mapper.readValue<Book>(json);      // Book: 読み込まれる
final text = mapper.writeValueAsString(order);  // Order: 書き出される
final copy = mapper.convertValue<Dto>(entity);  // Dto: 読み込まれる。エンティティのクラス: 書き出される
```

三つの制限:

- 記述されるのは、呼び出しのあるパッケージのクラスだけです。別のパッケージのクラスは `@Introspected(classes: [...])` に列挙します。
- 静的な型が `Object` や `dynamic` の値はクラスを示しません。`mapper.writeValueAsString(value as Object)` は何も記述しません。
- `sendJson` と `broadcast` が数えられるのは、`spring_boot_starter_websocket` をインポートするライブラリだけです。それ以外の場所では別のメソッド (`StreamController.broadcast`) です。

## `@Introspected`: すべて

クラスに付けた `@Introspected()` はすべての部分を求め、`@Introspected(classes: [...])` に列挙されたクラスも同様です。それらのクラスを構成するものもすべての部分を受け取ります。ビルドから見えない場所でクラスが使われる場合に使います。`Object` として渡される値、プラグインだけが読むクラス、別のパッケージのクラスです。

```dart
@Introspected()
class Report {
  Report(this.title);
  final String title;
  String summary() => title.toUpperCase();
}

// 別のパッケージのクラス: スキャンされるパッケージの任意のクラスに列挙する。
@Introspected(classes: [Money, Address])
class IntrospectionConfig {}
```

## 記述が保持すると示すもの

各記述は、その部分を `Introspection.parts` (`Set<IntrospectionPart>`) に列挙します。

| `IntrospectionPart` | 意味 |
|---|---|
| `read` | ゲッター |
| `write` | コンストラクター、`instantiate`、セッター、`fromJson` |
| `methods` | 式が呼びうるメソッド |

三つの部分すべてを持つ記述は `parts:` を省略します (デフォルトは三つすべて)。`describesPart(part)` は、その部分があるかどうかを伝えます。

### 例: バリデーションされるリクエストボディ

入力:

```dart
class NewBook {
  const NewBook({required this.isbn, required this.title, this.stock = 0});

  @NotBlank()
  @Size(min: 4, max: 13)
  final String isbn;

  @NotBlank()
  final String title;

  @PositiveOrZero()
  final int stock;
}

@RestController()
@RequestMapping('/api/books')
class BookController {
  BookController(this.books);

  final BookService books;

  @PostMapping()
  Future<ResponseEntity<Book>> create(
    @RequestBody() @Valid() NewBook book,
  ) async {
    final created = await books.create(book);
    return ResponseEntity.created(Uri.parse('/api/books/${created.isbn}'))
        .body(created);
  }
}
```

出力 (Web スターターのテストアプリケーションから。プレフィックスは外しています)。`NewBook` は読み込まれ、バリデーションされます。コンストラクターと、制約付きの各プロパティのゲッターです。三つのプロパティすべてに制約があるので、三つすべてにゲッターがあります。セッター (フィールドは `final`) もメソッドもありません。

```dart
const Introspection<NewBook>(
  className: r'NewBook',
  properties: [
    IntrospectedProperty<NewBook>(
      r'isbn',
      typeInfo: ClassType<String>(),
      get: _$get68,
      annotations: [NotBlank(), Size(min: 4, max: 13)],
    ),
    IntrospectedProperty<NewBook>(
      r'title',
      typeInfo: ClassType<String>(),
      get: _$get69,
      annotations: [NotBlank()],
    ),
    IntrospectedProperty<NewBook>(
      r'stock',
      typeInfo: ClassType<int>(),
      get: _$get70,
      annotations: [PositiveOrZero()],
    ),
  ],
  parts: {IntrospectionPart.write},
  constructor: IntrospectedConstructor<NewBook>(
    parameters: [
      IntrospectedParameter(
        r'isbn',
        type: ClassType<String>(),
        symbol: #isbn,
        isRequired: true,
      ),
      IntrospectedParameter(
        r'title',
        type: ClassType<String>(),
        symbol: #title,
        isRequired: true,
      ),
      IntrospectedParameter(
        r'stock',
        type: ClassType<int>(),
        symbol: #stock,
        hasDefaultValue: true,
        defaultValue: 0,
      ),
    ],
    create: _$create71,
  ),
),
```

クロージャーはトップレベル関数 (`_$get68`、`_$create71`) なので、記述全体が定数です。

### 例: 書き出されるだけの返信

```dart
class Shout {
  const Shout(this.text);
  final String text;
}

@WebSocketEndpoint('/ws/echo/{name}')
class EchoEndpoint {
  @OnMessage()
  Shout echo(@PathVariable() String name, String text, Principal? user) =>
      Shout('$name: ${text.toUpperCase()}');
}
```

```dart
const Introspection<Shout>(
  className: r'Shout',
  properties: [
    IntrospectedProperty<Shout>(
      r'text',
      typeInfo: ClassType<String>(),
      get: _$get75,
    ),
  ],
  parts: {IntrospectionPart.read},
),
```

コンストラクターもセッターもありません。アプリの中で JSON から `Shout` を生成するものはないからです。

## 欠けている部分が使われたとき

ビルドが省いた部分を必要とするコードは、`IntrospectionPartError` (`StateError`) を投げます。空のオブジェクトを返したり、黙って値をスキップしたりすることはありません。メッセージは、クラス、欠けている部分、それを必要としたもの、修正方法を示します。

```text
Bad state: Book is described without its getters, but it is written out as
JSON. The build described only what it saw used, and did not see that: add
@Introspected() to Book.
```

ランタイムがそのメッセージで示す使い方:

| メッセージの末尾 | 部分 |
|---|---|
| `it is written out as JSON` | ゲッター |
| `it is read in from JSON` | コンストラクターとセッター |
| `it is written with JsonInclusion.nonDefault, which compares each value with the one of a new instance` | コンストラクターとセッター |
| `an instance is created`、`an instance is created for a nested property` | コンストラクターとセッター |
| `its fields are bound from the input`、`the form is bound to an instance of it` | コンストラクターとセッター |

典型的な原因は、JSON として書かれる前に `Object` にキャストされた値、スキャンに含まれないライブラリが読むクラス、別のパッケージのクラスです。修正方法は常に同じです。クラスに `@Introspected()` を付けるか、`@Introspected(classes: [...])` にクラスを列挙します。

## 記述の置き場所

モジュールの記述は、モジュールの `.spring.dart` の隣にある専用のライブラリ `lib/spring_gen/<library>.spring.introspection.dart` に入ります。ゲッター `$<module>Introspections` (`$appBeansIntrospections`) を持ち、ゲッターなので、ホットリロードで新しいコードの記述が得られます。`.spring.dart` はそれをインポートしてリストをモジュールに渡します。そのため、モジュールのファイルは、何千行もの記述ではなく、Bean と配線を持ちます。

`@ConfigurationProperties` のバインダーだけが使う記述は `<library>.spring.properties.dart` (`$<module>PropertiesIntrospections`) にあります。バインダーと他のものが使うクラスは、他の記述と一緒に残ります。

単体テストは、コンテキストを起動せずに記述を登録できます。

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

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

同じファイルに、[オブジェクトのメソッド](../../spring-core-dart/beans/object-methods.md) (`@EqualsAndHashCode`、`@ToString`、`@CopyWith`) が生成するものも入ります。アノテーションを付けたクラスが記述され、その `==`、`hashCode`、`toString()` は `Introspection.objectMethods` の関数になります。

ジェネレーターの内部では、イントロスペクションは専用のスキャナー、モデル、エミッター (`core/introspection/`) を持ちます。Bean のスキャンとパッケージのパート (Web、WebSocket、データ) は、クラスに何が必要かをそれに伝え、記述はそれが書きます。

## 関連項目


- [最適化の概要](index.md)
- [ビルド速度](build-speed.md)
- [Bean 定義](../bean-definitions.md)
- [オブジェクトのメソッド](../../spring-core-dart/beans/object-methods.md)
- [JSON](../../spring-core-dart/json/index.md)
- [SpEL](../../spring-core-dart/spel/index.md)
- [バリデーションの制約](../../spring-core-dart/validation/constraints.md)
