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

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 の呼び出し

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

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

三つの制限:

@Introspected: すべて

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

@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) は、その部分があるかどうかを伝えます。

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

入力:

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) もメソッドもありません。

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) なので、記述全体が定数です。

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

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()}');
}
const Introspection<Shout>(
  className: r'Shout',
  properties: [
    IntrospectedProperty<Shout>(
      r'text',
      typeInfo: ClassType<String>(),
      get: _$get75,
    ),
  ],
  parts: {IntrospectionPart.read},
),

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

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

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

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) にあります。バインダーと他のものが使うクラスは、他の記述と一緒に残ります。

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

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

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

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

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

関連項目