プロジェクトの初期段階で見過ごされがちな、ソフトウェア開発プロセスで非常に重要なことの 1 つは、API ドキュメントです。この問題の解決策の 1 つは、ドキュメントを自動生成するためのフレームワークです。 プロジェクトをマイクロサービスに分割し、イベント ドリブン アーキテクチャを使用する場合、サービス間の相互作用は、メッセージ ブローカーを通じて送信されるイベントを使用して構築されます。 イベント駆動型アーキテクチャの場合にドキュメントを生成するには、  があります。 AsyncAPI は、イベント駆動型アーキテクチャ (EDA) の現在の状態を改善しようとするオープンソース イニシアチブです。 AsyncApi には、コードからドキュメントを生成できる Java ツールがいくつかあります。 では、これらの ツールの 1 つをセットアップする方法について説明しました。 AsyncApi この記事 springwolf この記事では、次のタスク、つまり springwolf が生成する JSON ドキュメントを使用した DTO の生成をどのように解決したかを説明したいと思います。 問題 spring wolf が生成するドキュメント構造は次のようになります。   { "service": { "serviceVersion": "2.0.0", "info": { //block with service info }, "servers": { "kafka": { //describe of kafka connection } }, "channels": { "kafka-channel": { "subscribe": { //... "message": { "oneOf": [ { "name": "pckg.test.TestEvent", "title": "TestEvent", "payload": { "$ref": "#/components/schemas/TestEvent" } } ] } }, //... } }, "components": { "schemas": { "TestEvent": { //jsonschema of component } } } } }  jsonschema はドキュメント内のコンポーネントの記述に使用されるため、この問題を解決するために ライブラリを使用することにしました。しかし、計画を実行しようとする過程で、いくつかの問題に遭遇しました。 jsonschema2pojo コンポーネントを記述するオブジェクトを抽出するには、JSON ドキュメントをさらに解析する必要があります。 jsonschema2pojo は jsonschema オブジェクトを入力として受け取るため、それらは components ブロックにあります。  jsonschema2pojo はポリモーフィズムではうまく機能せず、AsyncAPI にある oneOf ブロックからの標準参照を処理しません。継承の記述には、スキーマ (extends.javaType) 内の特別なフィールドが必要であり、AsyncAPI ドキュメントに単純に追加することはできません。 この場合、生成されたクラスはブローカーからのメッセージを逆シリアル化するために使用する必要があるため、記述子とサブタイプを記述する Jackson アノテーションを追加する必要があります。 これらすべての問題により、ドキュメントから必要な情報を抽出し、ポリモーフィズムをサポートし、Jackson アノテーションを追加する、jsonschema2pojo にラッパーを実装する必要が生じました。その結果、springwolf API を使用してプロジェクトの DTO クラスを生成できる Gradle プラグインが作成されます。次に、ドキュメント用にクラスに注釈を付ける方法と、  プラグインの使用方法を示します。 Springwolfdoc2dto ドキュメントのセットアップ ここで、Enum や Map などの非プリミティブ型の生成の詳細について考えてみたいと思います。また、ポリモーフィズムに必要なアクションについても説明します。 次のメッセージを見てみましょう。   @Getter @Setter @NoArgsConstructor @AllArgsConstructor public class TestEvent implements Serializable { private String id; private LocalDateTime occuredOn; private TestEvent.ValueType valueType; private Map<String, Boolean> flags; private String value; public enum ValueType { STRING("STRING"), BOOLEAN("BOOLEAN"), INTEGER("INTEGER"), DOUBLE("DOUBLE"); private final String value; public ValueType(String value) { this.value = value; } } } このようなメッセージの jsonschema は次のようになります。   { "service": { //... "components": { "schemas": { "TestEvent": { "type": "object", "properties": { "id": { "type": "string", "exampleSetFlag": false }, "occuredOn": { "type": "string", "format": "date-time", "exampleSetFlag": false }, "valueType": { "type": "string", "exampleSetFlag": false, "enum": [ "STRING", "BOOLEAN", "INTEGER", "DOUBLE" ] }, "flags": { "type": "object", "additionalProperties": { "type": "boolean", "exampleSetFlag": false }, "exampleSetFlag": false }, "value": { "type": "string", "exampleSetFlag": false } }, "example": { "id": "string", "occuredOn": "2015-07-20T15:49:04", "valueType": "STRING", "flags": { "additionalProp1": true, "additionalProp2": true, "additionalProp3": true } }, "exampleSetFlag": true } } } } }  DTO クラスを生成すると、次のクラス構造が得られます。 Enum は元のバージョンと同じように処理されることがわかりますが、タイプ のコレクションは別のクラス Flags になり、コレクション自体の値全体が フィールドに分類されます。 Map<String, Boolean> Flags.additionalProperties   package pckg.test; // import @JsonInclude(JsonInclude.Include.NON_NULL) @JsonPropertyOrder({ "id", "occuredOn", "valueType", "flags", "value" }) @Generated("jsonschema2pojo") public class TestEvent implements Serializable { @JsonProperty("id") private String id; @JsonProperty("occuredOn") private LocalDateTime occuredOn; @JsonProperty("valueType") private TestEvent.ValueType valueType; @JsonProperty("flags") private Flags flags; @JsonProperty("value") private String value; @JsonIgnore private Map<String, Object> additionalProperties = new LinkedHashMap<String, Object>(); private final static long serialVersionUID = 7311052418845777748L; // Getters ans Setters @Generated("jsonschema2pojo") public enum ValueType { STRING("STRING"), BOOLEAN("BOOLEAN"), INTEGER("INTEGER"), DOUBLE("DOUBLE"); private final String value; private final static Map<String, TestEvent.ValueType> CONSTANTS = new HashMap<String, TestEvent.ValueType>(); static { for (TestEvent.ValueType c: values()) { CONSTANTS.put(c.value, c); } } ValueType(String value) { this.value = value; } @Override public String toString() { return this.value; } @JsonValue public String value() { return this.value; } @JsonCreator public static TestEvent.ValueType fromValue(String value) { TestEvent.ValueType constant = CONSTANTS.get(value); if (constant == null) { throw new IllegalArgumentException(value); } else { return constant; } } } } @JsonInclude(JsonInclude.Include.NON_NULL) @JsonPropertyOrder({ }) @Generated("jsonschema2pojo") public class Flags implements Serializable { @JsonIgnore private Map<String, Boolean> additionalProperties = new LinkedHashMap<String, Boolean>(); private final static long serialVersionUID = 7471055390730117740L; //getters and setters } ポリモーフィズム それでは、ポリモーフィズム オプションを提供する方法を見てみましょう。これは、複数のメッセージ サブタイプを 1 つのブローカー トピックに送信し、サブタイプごとにリスナーを実装する場合に関連します。 これを行うには、親クラスをプロバイダーのリストに追加し、swagger から @Schema アノテーションをそれに追加する必要があります。   @NoArgsConstructor(access = AccessLevel.PROTECTED) @AllArgsConstructor @Getter @Setter(AccessLevel.PROTECTED) @EqualsAndHashCode @JsonTypeInfo( use = JsonTypeInfo.Id.NAME, include = JsonTypeInfo.As.EXISTING_PROPERTY, property = "type", visible = true, defaultImpl = ChangedEvent.class ) @JsonSubTypes(value = { @JsonSubTypes.Type(name = ChangedEvent.type, value = ChangedEvent.class), @JsonSubTypes.Type(name = DeletedEvent.type, value = DeletedEvent.class) }) @JsonIgnoreProperties(ignoreUnknown = true) @Schema(oneOf = {ChangedEvent.class, DeletedEvent.class}, discriminatorProperty = "type", discriminatorMapping = { @DiscriminatorMapping(value = ChangedEvent.type, schema = ChangedEvent.class), @DiscriminatorMapping(value = DeletedEvent.type, schema = DeletedEvent.class), }) public abstract class DomainEvent { @Schema(required = true, nullable = false) private String id; @JsonSerialize(using = LocalDateTimeSerializer.class) @JsonDeserialize(using = LocalDateTimeDeserializer.class) @JsonFormat(shape = JsonFormat.Shape.STRING, pattern = "yyyy-MM-dd HH:mm:ss") private LocalDateTime occuredOn = LocalDateTime.now(); public abstract String getType(); } /** * Subtype ChangedEvent */ public class ChangedEvent extends DomainEvent implements Serializable { public static final String type = "CHANGED_EVENT"; private String valueId; private String value; } /** * Subtype DeletedEvent */ public class DeletedEvent extends DomainEvent implements Serializable { public static final String type = "DELETED_EVENT"; private String valueId; } この場合、ドキュメント内のコンポーネントの説明は次のように変更されます。   "components": { "schemas": { "ChangedEvent": { "type": "object", "properties": { "id": { "type": "string", "exampleSetFlag": false }, "occuredOn": { "type": "string", "format": "date-time", "exampleSetFlag": false }, "value": { "type": "string", "exampleSetFlag": false }, "valueId": { "type": "string", "exampleSetFlag": false }, "type": { "type": "string", "exampleSetFlag": false } }, "example": { "id": "string", "occuredOn": "2015-07-20T15:49:04", "value": "string", "valueId": "string", "type": "CHANGED_EVENT" }, "exampleSetFlag": true }, "DeletedEvent": { "type": "object", "properties": { "id": { "type": "string", "exampleSetFlag": false }, "occuredOn": { "type": "string", "format": "date-time", "exampleSetFlag": false }, "valueId": { "type": "string", "exampleSetFlag": false }, "type": { "type": "string", "exampleSetFlag": false } }, "example": { "id": "string", "occuredOn": "2015-07-20T15:49:04", "valueId": "string", "type": "DELETED_EVENT" }, "exampleSetFlag": true }, "DomainEvent": { "type": "object", "properties": { "id": { "type": "string", "exampleSetFlag": false }, "occuredOn": { "type": "string", "format": "date-time", "exampleSetFlag": false }, "type": { "type": "string", "exampleSetFlag": false } }, "example": { "id": "string", "occuredOn": "2015-07-20T15:49:04", "type": "string" }, "discriminator": { "propertyName": "type", "mapping": { "CHANGED_EVENT": "#/components/schemas/ChangedEvent", "DELETED_EVENT": "#/components/schemas/DeletedEvent" } }, "exampleSetFlag": true, "oneOf": [ { "$ref": "#/components/schemas/ChangedEvent", "exampleSetFlag": false }, { "$ref": "#/components/schemas/DeletedEvent", "exampleSetFlag": false } ] } } } その後、プラグインは oneOf ブロックと記述された識別子からのリンクを考慮します。その結果、次のクラス構造が得られます。   package pckg.test; // import @JsonInclude(JsonInclude.Include.NON_NULL) @JsonPropertyOrder({ "id", "occuredOn", "type" }) @Generated("jsonschema2pojo") @JsonTypeInfo(property = "type", use = JsonTypeInfo.Id.NAME, include = JsonTypeInfo.As.EXISTING_PROPERTY, visible = true) @JsonSubTypes({ @JsonSubTypes.Type(name = "CHANGED_EVENT", value = ChangedEvent.class), @JsonSubTypes.Type(name = "DELETED_EVENT", value = DeletedEvent.class) }) public class DomainEvent implements Serializable { @JsonProperty("id") protected String id; @JsonProperty("occuredOn") protected LocalDateTime occuredOn; @JsonProperty("type") protected String type; @JsonIgnore protected Map<String, Object> additionalProperties = new LinkedHashMap<String, Object>(); protected final static long serialVersionUID = 4691666114019791903L; //getters and setters } // import @JsonInclude(JsonInclude.Include.NON_NULL) @JsonPropertyOrder({ "id", "occuredOn", "valueId", "type" }) @Generated("jsonschema2pojo") public class DeletedEvent extends DomainEvent implements Serializable { @JsonProperty("id") private String id; @JsonProperty("occuredOn") private LocalDateTime occuredOn; @JsonProperty("valueId") private String valueId; @JsonProperty("type") private String type; @JsonIgnore private Map<String, Object> additionalProperties = new LinkedHashMap<String, Object>(); private final static long serialVersionUID = 7326381459761013337L; // getters and setters } package pckg.test; //import @JsonInclude(JsonInclude.Include.NON_NULL) @JsonPropertyOrder({ "id", "occuredOn", "value", "type" }) @Generated("jsonschema2pojo") public class ChangedEvent extends DomainEvent implements Serializable { @JsonProperty("id") private String id; @JsonProperty("occuredOn") private LocalDateTime occuredOn; @JsonProperty("value") private String value; @JsonProperty("type") private String type; @JsonIgnore private Map<String, Object> additionalProperties = new LinkedHashMap<String, Object>(); private final static long serialVersionUID = 5446866391322866265L; //getters and setters } プラグインのセットアップ プラグインを接続するには、それを gradle.build ファイルに追加し、パラメーターを指定する必要があります。 フォルダーは DTO を生成するためのものでした 新しいクラスのパッケージ springwolf ドキュメントの URL ドキュメントのルート名、通常はサービスの名前 plugins { id 'io.github.stepanovd.springwolf2dto' version '1.0.1-alpha' } springWolfDoc2DTO{ url = 'http://localhost:8080/springwolf/docs' targetPackage = 'example.package' documentationTitle = 'my-service' targetDirectory = project.layout.getBuildDirectory().dir("generated-sources") }  bash コマンドを使用してタスクを実行します。   ./gradle -q generateDTO 結論 この記事では、  プラグインを使用して、AsyncApi ドキュメントに基づいて新しい DTO クラスを生成する方法について説明しました。同時に、新しいクラスは元の継承に従い、正しい逆シリアル化のための Jackson アノテーションを含みます。このプラグインがお役に立てば幸いです。 springwolfdocs2dto

Read My Stories

このオーディオは、ストーリーの元の言語で制作されています。

イベント駆動型アーキテクチャ: イベントドキュメントからの自動 DTO 生成

About Author

コメント

ラベル

この記事は

Related Stories

クラウド移行を成功させるための完全ガイド: 戦略とベストプラクティス

ワークフローを10倍に向上させる方法: 必須アプリ17選

18 種類の開発者ツールで生産性を向上しましょう 🚀🔥

暗号通貨の成長: 効果的なユーザーペルソナの作成

クラウド移行を成功させるための完全ガイド: 戦略とベストプラクティス

ワークフローを10倍に向上させる方法: 必須アプリ17選

18 種類の開発者ツールで生産性を向上しましょう 🚀🔥

暗号通貨の成長: 効果的なユーザーペルソナの作成

Light-Mode

Classic

Newspaper

Dark-Mode

Neon Noir

Minty

HN StartUps

イベント駆動型アーキテクチャ: イベント ドキュメントからの自動 DTO 生成