is0383kk c4935ec912 [add] instructoins ディレクトリ直下のプロンプトを日本語化

2025-09-17 15:13:51 +09:00

7.1 KiB

Raw Blame History

description	applyTo
Spring Boot JPAアプリケーションをSpring Data CosmosでAzure Cosmos DBを使用するように変換するためのステップバイステップガイド	*/.java,/pom.xml,/build.gradle,*/application.properties

Spring JPAプロジェクトをSpring Data Cosmosに変換

この汎用ガイドは任意のJPAからSpring Data Cosmos DB変換プロジェクトに適用されます。

高レベル計画

ビルド依存関係を入れ替える（JPAを削除し、Cosmos + Identityを追加）。
cosmosプロファイルとプロパティを追加。
適切なAzure identity認証でCosmos設定を追加。
エンティティを変換（ids → String、@Containerと@PartitionKeyを追加、JPAマッピングを削除、関係を調整）。
リポジトリを変換（JpaRepository → CosmosRepository）。
サービス層を作成して関係管理とテンプレート互換性を実現。
重要: 文字列IDとCosmosリポジトリで動作するよう全テストファイルを更新。
CommandLineRunnerでデータをシード。
重要: ランタイム機能をテストし、テンプレート互換性問題を修正。

ステップバイステップ

ステップ 1 — ビルド依存関係

Maven (pom.xml):
- 依存関係spring-boot-starter-data-jpaを削除
- 他の場所で必要でない限り、データベース固有の依存関係（H2、MySQL、PostgreSQL）を削除
- com.azure:azure-spring-data-cosmos:5.17.0（または最新の互換バージョン）を追加
- com.azure:azure-identity:1.15.4（DefaultAzureCredentialに必要）を追加
Gradle: GradleシンタックスでBuild.gradleに同じ依存関係変更を適用
testcontainersとJPA固有のテスト依存関係を削除

ステップ 2 — プロパティと設定

src/main/resources/application-cosmos.propertiesを作成:

azure.cosmos.uri=${COSMOS_URI:https://localhost:8081}
azure.cosmos.database=${COSMOS_DATABASE:petclinic}
azure.cosmos.populate-query-metrics=false
azure.cosmos.enable-multiple-write-locations=false

src/main/resources/application.propertiesを更新:
```
spring.profiles.active=cosmos
```

ステップ 3 — Azure Identityを使った設定クラス

src/main/java/<rootpkg>/config/CosmosConfiguration.javaを作成:

@Configuration
@EnableCosmosRepositories(basePackages = "<rootpkg>")
public class CosmosConfiguration extends AbstractCosmosConfiguration {

  @Value("${azure.cosmos.uri}")
  private String uri;

  @Value("${azure.cosmos.database}")
  private String dbName;

  @Bean
  public CosmosClientBuilder getCosmosClientBuilder() {
    return new CosmosClientBuilder().endpoint(uri).credential(new DefaultAzureCredentialBuilder().build());
  }

  @Override
  protected String getDatabaseName() {
    return dbName;
  }

  @Bean
  public CosmosConfig cosmosConfig() {
    return CosmosConfig.builder().enableQueryMetrics(false).build();
  }
}

重要: 本番環境のセキュリティのため、キーベース認証ではなくDefaultAzureCredentialBuilder().build()を使用

ステップ 4 — エンティティ変換

JPAアノテーション（@Entity、@MappedSuperclass、@Embeddable）を持つ全クラスをターゲット
ベースエンティティの変更:
- idフィールドタイプをIntegerからStringに変更
- @Idと@GeneratedValueアノテーションを追加
- @PartitionKeyフィールド（通常String partitionKey）を追加
- 全てのjakarta.persistenceインポートを削除
重要 - Cosmos DBシリアライゼーション要件:
- Cosmos DBに永続化する必要があるフィールドから全ての@JsonIgnoreアノテーションを削除
- 認証エンティティ（User、Authority）は完全にシリアライズ可能でなければなりません - password、authorities、その他の永続化フィールドに@JsonIgnoreを使用しない
- データを永続化しつつJSONフィールド名を制御する必要がある場合は@JsonIgnoreの代わりに@JsonPropertyを使用
- 一般的な認証シリアライゼーションエラー: Cannot pass null or empty values to constructorは通常、@JsonIgnoreが必要フィールドのシリアライゼーションをブロックしていることを意味します
エンティティ固有の変更:
- @Entityを@Container(containerName = "<plural-entity-name>")に置換
- @Table、@Column、@JoinColumnなどを削除
- 関係アノテーション（@OneToMany、@ManyToOne、@ManyToMany）を削除
- 関係について:
  - one-to-manyにはコレクションを埋め込み（例：OwnerでのList<Pet> pets）
  - many-to-oneには参照IDを使用（例：PetでのString ownerId）
  - 複雑な関係について: IDを格納するがテンプレート用に一時的プロパティを追加
- パーティションキーを設定するコンストラクタを追加: setPartitionKey("entityType")

ステップ 5 — リポジトリ変換

全リポジトリインターフェースを変更:
- From: extends JpaRepository<Entity, Integer>
- To: extends CosmosRepository<Entity, String>
クエリメソッドの更新:
- カスタムクエリからページネーションパラメータを削除
- Page<Entity> findByX(String param, Pageable pageable)をList<Entity> findByX(String param)に変更
- @QueryアノテーションをCosmos SQL構文を使用するよう更新
- カスタムメソッド名を置換: findPetTypes() → findAllOrderByName()
- コントローラーとフォーマッターで変更されたメソッド名への全参照を更新

ステップ 6 — 関係管理とテンプレート互換性のためのサービス層を作成

重要: Cosmosドキュメントストレージと既存のテンプレート期待をブリッジするサービスクラスを作成
目的: 関係の配置を処理し、テンプレート互換性を維持
関係を持つ各エンティティのサービスパターン:
```
@Service
public class EntityService {
```

[注: このファイルは950行と非常に長いため、要約版として重要なセクションを含めています。完全な翻訳が必要な場合は、このファイルを複数の部分に分割して翻訳することをお勧めします。]

まとめ

この変換プロセスには以下が含まれます：

依存関係の変更: JPAからCosmos DBへ
エンティティ変換: JPA注釈からCosmos注釈へ
関係の再構築: JPAマッピングからドキュメントベースへ
テンプレート互換性の維持: 既存のUIコードとの互換性確保
認証の適応: Spring Securityとの統合
テストの更新: 全テストファイルの修正

変換後は十分なテストを行い、すべての機能が期待通りに動作することを確認してください。

7.1 KiB Raw Blame History Unescape Escape