1. はじめに
業務でClaude Codeに実装を依頼した際、@Builder アノテーションが付与されたクラスがいくつか登場し、「この使い方、どういう意図なんだろう？」と気になったことがきっかけで調査を始めました。
本記事では、@Builder の基本的な使い方や@Builder(toBuilder = true) を使ったImmutable設計との組み合わせ、実際のユースケースを簡単に整理してご紹介します。実装の際の参考になれば幸いです。
2. @Builder(toBuilder = true)とは？
@Builder(toBuilder = true)を指定すると、Lombokは元のオブジェクトから新しいビルダーを生成するtoBuilder()メソッドを追加します。これにより、既存のインスタンスをベースにして、一部のフィールドだけを変更した新しいインスタンスを簡単に作成できます。
3. 使用例
以下は、User クラスに @Builder(toBuilder = true) を付与した例です。
@Builder(toBuilder = true)
public class User {
private final String name;
private final int age;
}
このクラスを使って、元のインスタンスをベースに一部の値だけ変更することができます。
User original = User.builder()
.name("Taro")
.age(30)
.build();
User updated = original.toBuilder()
.age(31)
.build();
このように、originalの状態を引き継ぎつつ、ageだけを変更した新しいUserインスタンスを生成できます。
4. 実践的なユースケース
toBuilder() は、以下のような場面で活用できます。
-
ImmutableなDTOの更新
REST APIのリクエストやレスポンスで、変更不可なオブジェクトを部分的に更新したいとき -
テストデータの部分変更
テスト用のオブジェクトをベースに、特定のフィールドだけ変えて複数パターンを検証するとき -
状態遷移の表現
状態管理が必要なドメインモデルで、前の状態を保持しつつ新しい状態を作る必要があるとき
toBuilder()はディープコピーではないため、参照型フィールドの扱いには注意が必要です。
6. まとめ
@Builder(toBuilder = true) は、Immutableな設計を保ちながら柔軟なオブジェクト操作を可能にする強力な機能です。特に、DTOやテストコード、状態遷移のあるドメインモデルなどで活用することで、コードの可読性と保守性を高めることができますね。
調べてみると奥が深く、設計の幅を広げてくれる便利な仕組みでした。今後もより理解を深め、積極的に活用していきたいと思います。
7. 参考