nwiizo Persisted Data and Public Interfaces
対象は永続化形式とプロセス外へ公開するデータの構造。 ローカル型、テスト用の中間表現、既存形式のまま設定値だけを変える作業には適用しない。
進め方
- 現在の書き込み側、読み込み側、保存済みデータ、既に決まった要件を確認する。
- 構造の判断が必要なら、違いが分かる具体値の before/after と互換性への影響を示す。 新規形式に架空の旧形式を作る必要はない。
- ユーザーの判断が必要な未決の選択だけ確認する。依頼で指定された形式や合意済みの 方針に沿う可逆的な実装は進める。再承認のために migration や serializer の作成を止めない。
- 本番データの書き換え・削除や公開は、実装作業とは別に、対象と実行権限を確認する。
判断基準
- 導出できる値の重複保存は理由がある場合に限る。時点の事実として保存する値と、 再計算するキャッシュを区別し、後者には更新・不整合の回復方法を持たせる。
- 人が読む形式では意味の分かるキーを使う。短縮キーや
cols+rowsは、 データ量・処理負荷の要件があり、読みにくさと互換性の負担に見合う場合に選ぶ。 - 固定長・固定順序の値は tuple が候補になる。拡張や項目名の意味が重要なら object。 既存形式を小さくする目的だけで変えない。
- 独立した状態の軸は分け、不可能な組み合わせを許す分割は避ける。 永続化する enum の値は並べ替えで意味が変わらない表現にする。
- 追加変更でも安全とは限らない。古い reader の未知フィールド・未知値の扱いと、 新しい reader が古いデータを読めるかを確認する。
- フィールド名を別の意味に再利用しない。移行が必要なら読み書きの切替順序、 既存データの扱い、失敗時の復旧方法を決める。
判断を説明する具体例は samples.md、 null・時刻・数値などの境界を扱うときは pitfalls.md を読む。