更新APIで省略フィールドを文脈デフォルトで補完する設計は既存の関連を黙って上書きする
設計判断
API設計
判断
原則
更新(PUT/PATCH 相当)やツール呼び出しで、関連やコレクションのフィールドを「省略」したとき、実装が「既存維持」ではなく「セッションや接続スコープのデフォルト値で補完」して保存すると、既存の関連が黙って上書きされる。呼び出し側は「触っていない=変わらない」と期待するため症状に気づきにくい。
何が起きるか
- フィールドを渡さない(undefined)と、サーバやツールが ambient な文脈(テナント、接続スコープ、ログイン中のプロジェクト等)から既定値を解決して埋め、その値で全置換する。
- 同じ更新でも、フィールドを明示的に空(空配列など)で渡すと「クリア」になり、省略すると「デフォルト補完」になる、という非対称が生まれる。
- 作成(create)経路は保存済みの値や空をそのまま使い、更新(update)経路だけが文脈デフォルトに落ちる、という経路差も起きやすく、保存と更新で結果が変わる。
判断基準
- 部分更新フィールドの欠落セマンティクスを設計時に明示する。「省略=変更しない」のか「省略=既定値を適用」なのかを曖昧にしない。
- 「省略」と「明示的な空」を区別する。クリアしたいときは空値を明示的に渡す契約にし、省略そのものに破壊的な意味を持たせない。
- ambient な文脈(テナント/接続スコープ/セッション)からの既定値補完は、作成時の利便と更新時の破壊が表裏一体になる。更新経路では既存値の保持を優先し、上書きは明示指定があるときだけにする。
検証
- 当該フィールドを渡さずに他項目だけ更新し、既存の関連が保持されることを確認する。保持されず文脈デフォルトに置き換わるなら、欠落セマンティクスがバグになっている。
- 作成経路と更新経路に同じ省略入力を与え、結果が一致するか(意図的に違えているか)を突き合わせる。