保存した形と外へ出す形は違う

一言でいうと

保存した形と外へ出す形は別物です。 この1行を守らなかったために起きる 事故が、バックエンドの事故の大きな部分を占めます。

なぜ必要なのか: 事故は静かに起きます

注文テーブルにinternal_memoカラムを1つ追加したとします。ハンドラーはそのままです。 return orderの1行がそのまま残っていて、テストもすべて通ります。ところがその瞬間から、 APIレスポンスに内部メモが載って出ていきます。

誰もエラーを見ません。ログも正常です。カラムを1つ追加したことがそのままAPIの変更だった という事実に、誰も気づきません。

1か所で決める

直すべき場所はハンドラーではありません。出力するフィールドを1か所にまとめ、それだけを通します。

const publicItem = ({ id, name, qty }) => ({ id, name, qty });

許可リストである点が重要です。delete item.secretのように除く方式で書くと、 次にカラムが増えたときにまた漏れます。除くものを数えるのではなく、 出すものを数える必要があります。

現場では

NestのClassSerializerInterceptorや、FastAPIのresponse_modelがしていることは、 まさにこれです。名前は違っても判断は同じで、ハンドラーのコードを直さなくても フィールドが絞られるようにします。

コードレビューで見るべきことも1つです。新しいカラムが追加されたPRで、出力の形も 一緒に変わったのか、それとも自動的に流れ出るままにしていたのか。後者なら、そのPRは APIの変更なのに、誰もそう呼んでいないということです。