RustのSerdeでJSONデシリアライズ時に発生する 'missing field' エラーの解決方法

エラーの内容

Rustのserdeクレートを使用してJSONをデシリアライズする際、以下のようなパニックやErrの結果に遭遇することがあります。

Error("missing field `field_name`", line: 1, column: 2)

これは、Rustの構造体が入力データ内に特定のフィールドが存在することを期待しているにもかかわらず、提供されたJSONにそのキーが含まれていない場合に発生します。デフォルトでは、Serdeは厳格です。構造体でフィールドが定義されている場合、それはJSON内に必ず存在しなければなりません。

根本的な原因

よくあるシナリオを考えてみましょう。ユーザープロファイルを表す構造体があるとします。

use serde::Deserialize;

#[derive(Deserialize, Debug)]
struct User {
    id: u32,
    username: String,
    email: String,
}

fn main() {
    let json_data = r#"{"id": 1, "username": "rustacean"}"#; // "email" が不足している
    let user: User = serde_json::from_str(json_data).unwrap();
}

このコードを実行すると、missing field email`` エラーが発生します。email が String として定義されているため、Serdeはそれが存在することを要求します。使用しているAPIや読み込んでいる設定ファイルに一貫性がない場合、アプリケーションはデータのパースに失敗します。

解決方法

データが欠損している場合のアプリケーションの挙動に応じて、不足しているフィールドを処理する方法はいくつかあります。

1. 任意フィールドに Option を使用する

Rustでデータが欠損している可能性を処理する最も慣習的な（idiomaticな）方法は、Option 型を使用することです。フィールドが Option でラップされている場合、JSONにそのキーがなければ、Serdeは自動的に None を割り当てます。

#[derive(Deserialize, Debug)]
struct User {
    id: u32,
    username: String,
    email: Option<String>, // これで任意項目になります
}

この変更により、先ほどのJSONの例も正常にデシリアライズされ、email は単に None になります。

2. 型のデフォルト値に #[serde(default)] を使用する

Option にしたくない場合もあります。代わりに、デフォルト値（整数なら 0、真偽値なら false、空の String など）を使用したい場合は、#[serde(default)] 属性を使用できます。

#[derive(Deserialize, Debug)]
struct Config {
    port: u16,
    #[serde(default)]
    debug_mode: bool, // 不足している場合はデフォルトで false になります
}

JSONに debug_mode がない場合、Serdeはその型の Default::default() を呼び出します（bool の場合は false です）。

3. カスタムデフォルト値

標準の Default トレイトが必要な値を提供しない場合（例：デフォルトのポート番号を 0 ではなく 8080 にしたい場合など）、カスタム関数を指定することができます。

#[derive(Deserialize, Debug)]
struct ServerConfig {
    #[serde(default = "default_port")]
    port: u16,
}

fn default_port() -> u16 {
    8080
}

4. 命名の不一致を処理する

フィールドが実際にデータから「欠損」しているのではなく、Rustの構造体フィールドとは異なる名前が付いているだけの場合もあります。その場合は #[serde(rename = "...")] を使用してマッピングします。

#[derive(Deserialize, Debug)]
struct User {
    #[serde(rename = "user_id")]
    id: u32,
}

JSONに "user_id": 1 があっても構造体が id になっている場合、このリネーム属性を使用しない限り missing field id`` エラーが発生します。

予防と検証

修正を検証するために、問題のフィールドが欠損しているJSON文字列を渡す小さなユニットテストを常に記述しましょう。これにより、デプロイ前に Option や default のロジックが期待通りに動作することを確認できます。

#[test]
fn test_missing_email() {
    let json = r#"{"id": 1, "username": "dev"}"#;
    let user: User = serde_json::from_str(json).expect("emailがなくてもパースできるはずです");
    assert!(user.email.is_none());
}

このようなエラーをスローする複雑なネスト構造のJSONをデバッグする際、ソースデータの構文ミスであることも少なくありません。私は JSONフォーマッター＆バリデーター を使用して、キーが実際にRustコードで書いたものと一致しているか素早くチェックするようにしています。難読化（minify）されたJSONの塊から不足しているフィールドやタイポを探し出すよりも、ずっと効率的です。

もう一つのよくある罠は、フィールドが 欠損（missing） しているのと、フィールドが null であることの違いです。JSONが {"email": null} の場合、キーは存在しているが値がnullであるため、#[serde(default)] は機能しません。その場合は必ず Option<T> を使用する必要があります。