serde-code-review

Serde コードレビュー

レビューワークフロー

1. Cargo.toml を確認する — serde の機能（derive、rc）、フォーマット用クレート（serde_json、toml、bincode など）、Rust のエディションを確認します（2024 では serde コードに影響する破壊的変更があります）。
2. derive の使用状況を確認する — Serialize と Deserialize が適切に derive されていることを確認します。
3. enum の表現形式を確認する — enum のタグ付けは、ワイヤーフォーマットの互換性と可読性に影響します。
4. フィールド属性を確認する — 名前変更、デフォルト値、スキップ設定は API コントラクトに影響します。
5. エディション 2024 との互換性を確認する — 予約済みの gen キーワード、RPIT のライフタイムキャプチャの変更、never_type_fallback を確認します。
6. 往復変換の正しさを検証する — シリアライズしたデータをデシリアライズしたとき、同じ値に戻る必要があります。

ゲート（指摘を報告する前に）

順番に実行してください。該当するステップに合格するまでは、指摘を記述しないでください。

1. ディスク上の serde コンテキスト — 合格条件： 関連する Cargo.toml（クレートまたはワークスペースのルート）を読み、Rust の edition、デフォルト以外の serde / serde_derive の機能（derive、rc）、レビュー対象コードに適用されるフォーマット用クレート（serde_json、toml、bincode など）を明示できること。その後、そのファイルで該当する場合に限り、エディション固有のチェック項目（例：gen、RPIT／never_type_fallback）を適用します。

2. 指摘ごとの根拠 — 合格条件： 各問題について、該当する struct／enum、Serialize／Deserialize の実装、または属性ブロックの [FILE:LINE] を、現在のツリーから示せること（記憶、ドキュメントのみ、または別ブランチの情報に基づくものではありません）。

3. プロトコルに基づくカテゴリーチェック — 合格条件： 指摘の種類（derive 属性、enum のタグ付け、flatten、カスタム実装、sqlx と serde の整合性）に応じて、review-verification-protocol スキルの対応するチェックを実行していること（例：「表現形式が誤っている」と指摘する前に型定義全体と serde 属性を確認する、エディション 2024 固有の指摘をする前に Cargo.toml でエディションを確認する）。その後、指摘を追加します。

4. 出力形式 — 合格条件： レポートの各行が、以下の「出力形式」（重大度＋説明）に一致していること。

出力形式

次の形式で指摘を報告します。

[FILE:LINE] ISSUE_TITLE
Severity: Critical | Major | Minor | Informational
Description of the issue and why it matters.

クイックリファレンス

問題の種類	参照先
derive パターン、属性マクロ、フィールド設定	references/derive-patterns.md
カスタム Serialize/Deserialize、フォーマット固有の問題	references/custom-serialization.md

レビューチェックリスト

derive の使用

• シリアライズ境界を越える型に #[derive(Serialize, Deserialize)] を指定する
• serde の derive とともに #[derive(Debug)] を指定する（シリアライズの問題をデバッグするため）
• serde がオプションの場合、機能で derive を制御する：#[cfg_attr(feature = "serde", derive(Serialize, Deserialize))]
• serde 専用フィールドには #[allow(unused)] より #[expect(unused)] を優先する（警告を自動的に解消する lint 抑制。1.81 以降で安定版）

enum の表現形式

• 別の形式を意図している場合、serde のデフォルトの外部タグ形式に依存せず、enum のタグ付けを明示する
• タグ名が安定しており、フィールド名と衝突しないことを確認する
• API 全体で #[serde(rename_all = "...")] を一貫して使用する

フィールド設定

• オプションのフィールドには #[serde(skip_serializing_if = "Option::is_none")] を使用する（すっきりした JSON 出力のため）
• デシリアライズ時に代替値を設定する必要があるフィールドには #[serde(default)] を使用する
• Rust のフィールド名とワイヤーフォーマットの名前が異なる場合は #[serde(rename = "...")] を使用する
• #[serde(flatten)] は慎重に使用する（キーが衝突する可能性があります）
• 前方互換性が必要な型には #[serde(deny_unknown_fields)] を指定しない
• gen という名前のフィールドやバリアントを使用しない — エディション 2024 では予約語です（r#gen を使用するか、名前を変更してください）

データベース統合（sqlx）

• #[derive(sqlx::Type)] を指定した enum では、serde と一貫した表現形式を使用する
• serde（rename_all）と sqlx（rename_all）の間で、enum バリアントの大文字・小文字の形式を一致させる

Edition 2024 との互換性

• gen という名前のフィールドや列挙型バリアントがない（予約語です。#[serde(rename = "gen")] とともに r#gen を使用するか、別の名前を選んでください）
• impl Trait を返すカスタム Serialize／Deserialize 実装が、RPIT のライフタイム捕捉の変更に対応している（スコープ内のすべてのライフタイムがデフォルトで捕捉されます。厳密に制御するには + use<'a> を使用してください）
• デシリアライズ時のエラーパスが never_type_fallback に対応している（! は () ではなく ! にフォールバックするため、Result<T, !> パターンの網羅性チェックに影響します）

正確性

• 複雑な型のラウンドトリップテストがある（シリアライズ → デシリアライズ → assert_eq）
• ラウンドトリップテストがある型に PartialEq が導出されている
• 情報が失われる変換がない（例：JSON の数値を f64 から i64 に変換する）
• 金額や精度が重要な値に f64 ではなく Decimal を使用している

重大度の基準

致命的

• シリアライザーとデシリアライザーの間で列挙型の表現が一致しない（データ損失）
• #[serde(rename)] がなく、API 破壊を伴うフィールド名の変更が発生する
• #[serde(flatten)] によってキーの衝突が気付かれないまま発生する
• 情報が失われる数値変換（通貨値での f64 の精度損失）

重大

• 関連する型の間で rename_all が一貫していない（API が分かりにくくなる）
• skip_serializing_if がなく、出力に null／空の値が混在する
• 進化する API が使用する型に deny_unknown_fields が指定されている（前方互換性が損なわれる）
• 複雑な列挙型表現のラウンドトリップテストがない
• r#gen によるエスケープなしで、フィールド名またはバリアント名に gen を使用している（edition 2024 でコンパイルに失敗する）

軽微

• 必須フィールドに不要な #[serde(default)] が指定されている
• より効率的な数値表現ではなく、列挙型に文字列表現を使用している
• derive と属性で十分な箇所に冗長なカスタム実装を使用している
• serde 専用フィールドに #[expect(unused)] ではなく #[allow(unused)] を使用している（自己解消する lint 抑制を推奨）

参考情報

• よりすっきりしたワイヤ形式にするため、列挙型の表現を切り替える提案
• 前方互換性のため、serde とともに #[non_exhaustive] を追加する提案

指摘を提出する前に

上記の ゲート（指摘の報告前） を完了してください。ゲート 3 には、serde 関連の問題種別に対する review-verification-protocol スキルが含まれます。