rust-lombok-macros

Rust Lombok マクロ

lombok-macros は、Java の Lombok に相当する Rust の完全な実装ではなく、手続き型マクロの依存関係および API ジェネレーターとして扱ってください。ボイラープレートを削除する前に、生成される各メソッドのシグネチャ、可視性、失敗時の動作、互換性の境界を確認してください。

適用範囲

次のような用途でこのスキルを使用してください。

• すべてのフィールドの組み合わせが有効な DTO、設定スナップショット、内部メッセージ、テストフィクスチャ、その他のデータキャリア。
• Getter、GetterMut、Setter、Data、New を使って機械的なメソッドを減らす場合。
• CustomDebug を使って、明示的に特定した機密フィールドを除外する場合。
• 既存の属性のレビュー、クレートのアップグレード、または手書きメソッドの移行。

次のものに対しては、メソッドを無条件に生成しないでください。

• 検証が必要なドメインエンティティ、値オブジェクト、セキュリティ境界。
• 安定した公開契約、カスタムエラー、監査、または副作用を伴うメソッド。
• 欠如やエラーの情報を保持する必要がある Option または Result のアクセスパス。
• ビルダー、デフォルト値のポリシー、シリアライズ、比較、ハッシュ化。バージョン 2.0.32 はこれらの機能を提供しません。

依存関係のバージョン、機能、サプライチェーンポリシーについては rust-cargo-build に、一般的な手続き型マクロの実装については rust-macros に、API とセキュリティのレビューについては rust-code-review に、より広範なテスト設計については rust-testing に引き継いでください。

ワークフロー

1. 正確なベースラインを確認する

バージョンを推測せず、プロジェクトを調査してください。

rustc --version --verbose
cargo metadata --format-version 1
cargo tree -i lombok-macros -e features

Cargo.toml、Cargo.lock、エディション、rust-version、対応ターゲットを確認してください。バージョン 2.0.32 は Edition 2024 を使用し、Rust のバージョンを宣言していないため、プロジェクトの実際の MSRV でコンパイルしてください。現在の crates.io ページや GitHub のリリースバッジだけを見て、選択されているバージョンを推測しないでください。

依存関係を追加する場合は、cargo add lombok-macros または cargo add [email protected] のようにレビュー済みの明示的なバージョンを使用してください。lombok-macros = "latest" を Cargo.toml にコピーしないでください。Cargo の依存関係では、latest キーワードではなくセマンティックバージョン要件を使用します。

2. クレートのバージョンに応じて例を選別する

ブログ記事、生成された回答、古いコード例が、ロックされたクレートに対応しているとは限りません。特に、2.0.32 は Lombok derive をエクスポートしません。#[derive(Lombok, Debug, Clone)] のような例は、たとえば #[derive(Getter, Setter, Debug, Clone)] のように、現在の必要最小限の derive で書き換えるか、ミュータブルゲッターも意図する場合に限り Data を使用してください。

機能の提供元を明確にしてください。

• Debug と Clone は標準ライブラリの derive であり、lombok-macros が生成する機能ではありません。
• 選択したフィールドをスキップする必要がある場合は、クレートが提供する代替手段として CustomDebug を使用します。
• DisplayDebug と DisplayDebugFormat は既存の Debug 表現から Display を実装します。Debug 出力を安定した表示形式にするものではありません。
• 手続き型マクロは手書きのソースを減らしますが、コンパイル時の処理と生成された動作は追加されます。条件を明示せず、コストがないと説明しないでください。

3. 生成前の API を棚卸しする

各フィールドについて、既存メソッドのシグネチャ、可視性、所有権の扱い、検証、副作用、エラー、呼び出し元を記録してください。生成されるインターフェースが同等であるか、契約の変更が承認されている場合に限り、メソッドを置き換えてください。

必要最小限の derive を選択してください。

要件	Derive	デフォルトのリスク
読み取り専用アクセス	Getter	デフォルトの Option および Result ゲッターは unwrap し、内部の値を返します
ミュータブルな借用	GetterMut	呼び出し元がフィールドの不変条件を迂回できます
直接置換	Setter	セッターは検証せず、書き込みアクセスを追加します
3 種類すべてのアクセサー	Data	API の範囲が必要以上に広くなりがちです
全フィールドの構築	New	コンストラクターはデフォルトで公開され、省略されたフィールドには Default が使われます
Debug 出力の秘匿化	CustomDebug	新しい機密フィールドには、引き続き明示的なレビューが必要です
Debug を Display として再利用	DisplayDebug*	構造的な出力は漏えいしやすく、安定したユーザー向け契約ではありません

4. 生成されるセマンティクスを明示する

固定したバージョンのソースとドキュメントに基づいて属性を記述します。2.0.32 の場合：

use lombok_macros::{CustomDebug, Getter, New, Setter};

#[derive(Getter, Setter, New, CustomDebug)]
#[new(pub(crate))]
struct WorkerConfig {
    #[get(pub)]
    #[set(pub, type(Into<String>))]
    name: String,

    #[get(pub, type(copy))]
    #[set(pub)]
    workers: usize,

    #[debug(skip)]
    #[new(skip)]
    token: String,
}

• 呼び出し側が所有権を必要としない限り、コストの高い値には &T を返します。
• クローンが API 契約の一部である場合に限り、type(clone) を使用します。
• Copy フィールドで値セマンティクスが必要な場合は、type(copy) を使用します。
• ドキュメントの一部に記載されている #[get(pub, clone)] の省略記法は使用しないでください。2.0.32 のパーサーでは type(clone) が必要です。
• セッターで変換する場合は type(Into<T>) または type(AsRef<T>) を使用し、対象の型そのものをコンパイルして確認します。
• 可視性は必要最小限にします。生成される公開メソッドは、ライブラリのセマンティックバージョニング上の公開範囲に含まれます。

derive と属性の全組み合わせについては、マクロリファレンスを参照してください。

5. Rust の不変条件を維持する

• 構築時に状態を検証する場合は、手書きの new 関数または try_new 関数を維持します。
• 変更に検証、監査、または複数フィールドの連携した更新が必要な場合は、名前付きメソッドを維持し、それらのフィールドに Setter や GetterMut を生成しないでください。
• Option と Result には、as_ref、as_deref、またはコンテナーを返すメソッドを明示的に記述します。パニックが発生する可能性を持ち込むデフォルトのゲッターや type(deref) は避けてください。
• キー、トークン、パスワード、個人データには #[debug(skip)] を付け、フォーマットされた出力をテストします。その後、新しいフィールドを追加するたびに確認してください。
• CLI、ユーザー向けエラー、またはプロトコルの出力には Display を手書きします。DisplayDebug は内部診断に限定してください。

既存のメソッドを置き換える場合やプルリクエストをレビューする場合は、導入とレビューを参照してください。

6. 呼び出し側から拡張された契約をテストする

derive がコンパイルされることを確認するだけでなく、生成されたメソッドを呼び出すテストを追加します。

cargo fmt --all --check
cargo check --workspace --all-targets --all-features
cargo test --workspace --all-targets --all-features
cargo clippy --workspace --all-targets --all-features -- -D warnings

メソッドの可視性、戻り値の型、セッターのチェーン、コンストラクターの引数順序、new(skip) のデフォルト値、Debug の秘匿化、手書きの不変条件が引き続き適用されることを網羅します。依存関係をアップグレードした後も、これらの契約テストを再実行します。必要に応じて手動で確認するために cargo expand を使用できますが、nightly 専用ツールだけを品質ゲートにしないでください。

完了条件

• 実際にビルドし、依存関係のバージョン、ソース、エディション、プロジェクトの MSRV を確認します。
• Data をデフォルトで使うのではなく、最小限の derive を使用します。
• 生成されるすべてのメソッドについて、シグネチャ、可視性、所有権、パニックの挙動を確認します。
• 検証、不変条件、副作用、エラーのセマンティクスは、明示的な Rust コードで維持します。
• 機密フィールドが Debug や Display に渡らないようにし、Debug をユーザー向け出力に公開しません。
• 生成された API を呼び出すテストを用意し、fmt、check、test、Clippy を通過させます。

リソース

• マクロと属性のリファレンス
• 導入、移行、レビューのチェックリスト
• 実行シナリオ
• examples/golden-lombok/：2.0.32 に固定された、コンパイル可能な契約例です。

上流ソース

• crates.io：公開バージョン、チェックサム、ライセンス、リポジトリ、機能、依存関係のメタデータを確認します。
• docs.rs 2.0.32：公開されている derive マクロとバージョン固有の rustdoc を確認します。実装時には、内容が変わる latest の URL を避けてください。
• GitHub ソース：実装履歴、タグ、Issue、未リリースの変更を確認します。デフォルトブランチだけでなく、対応するリリースタグを比較してください。
• Rust Reference：手続き型マクロ

説明文、rustdoc の例、実際の挙動が一致しない場合は、生成コードについては選択した crates.io パッケージに含まれるソースを正とし、最小限のコンパイルテストで挙動を再現して、相違点を記録します。Cargo.lock に記載されたバージョンの代わりに、GitHub の master の挙動を黙って適用しないでください。

データプライバシー

このスキルは、ユーザーデータを収集、保存、送信しません。依存関係の変更によって、レジストリにアクセスする場合があります。プライベートレジストリへのアクセス、認証情報の変更、またはクレートの公開を行う前に、許可を確認してください。