null かフィールド省略か

要点：消費者が「クリア」と「未変更」を区別しなければならないときは null を送りましょう。PATCH ボディでは、欠落はフィールドをそのままにし、明示的な null はクリアします。フィールドごとに一つの取り決めを保ち、レスポンスと設定マージを安定させます。

違い

复制{ "nickname": null }

存在し、空です。消費者はフィールドが明示的にクリアされたことを知ります。

复制{ }

欠落。消費者は「一度も設定されていない」と「対応していない」を区別できません。

JavaScript では区別が具体的です。

复制'nickname' in obj          // false — 欠落
obj.nickname === null      // true  — 存在し null
obj.nickname === undefined // true  — 両方のケース

どこで重要か

PATCH ボディ。 {"nickname": null} はニックネームをクリアします。{} は何も変えません。ハンドラが「null」と「欠落」を同じに扱うと、ユーザーはフィールドを決してクリアできず、空文字列に設定するしかなくなります。それは別物です。

キーの存在で実装し、値では判断しません。

复制if (Object.hasOwn(patch, 'nickname')) {
  target.nickname = patch.nickname;   // null を許す
}

設定マージ。 省略は既定値を継承し、null は明示的に無効化します。これは Helm と Kubernetes の values がまさにそう振る舞う方法です。

フォームの初期表示。 null は空として描画され、欠落フィールドも同様ですが、送信が異なります。値があり、今クリアされた → null を送る。一度も入力されていない → 省略。区別がなければ、クリアは触っていないのと同じに見えます。

取り決め

レスポンスの形を安定させる。 一部の項目が avatar を運び他が運ばないリストは、すべての呼び出し箇所で 'avatar' in item のチェックを強います。avatar: null の方が消費しやすいです。

やってはいけない三つ

null に "" を使わない。 空のニックネームと未設定のニックネームは、ほとんどの領域で異なる状態です。

番兵に 0 や -1 を使わない。 ゼロは正当な数値で、番兵は計算するすべての平均を壊します。

エンドポイントごとに取り決めを混ぜない。 二つの取り決めは、すべてのクライアントに二つのコード経路を意味します。

FAQ

null とフィールド省略は何で決まりますか？

消費者が「明示的にクリア」と「一度も設定されていない」を区別する必要があるかを問います。PATCH ボディでは必要なので、null はクリアし、欠落は保持します。レスポンスでは null を保つことで形が安定し、クライアントの型が単純になります。

PATCH エンドポイントはクリアとそのままをどう区別しますか？

値ではなくキーの存在を確認します。Object.hasOwn(patch, 'nickname') はフィールドが送られたことを示し、そのときだけ代入します。null も含みます。ハンドラが null と欠落を同じに扱うと、ユーザーはフィールドを決してクリアできず、空文字列に頼るしかありません。

レスポンスボディが null を保つべきなのはなぜですか？

安定した形なら、クライアントは任意のキーごとに 'avatar' in item をチェックする必要がありません。一部のリスト項目が avatar を運び他が省略すると、そのチェックがすべての呼び出し箇所で重複し、誤りやすくなります。

さらに読む

• API レスポンスはどんな構造にすべきか
• JSON Pointer、Patch、Merge Patch