手作りJSONが破綻する理由

最初は、モデルの各フィールドを dict にコピーして、JSON を手作業で構築します。単純に感じますし、エンドポイントが1つだけなら実際に単純です。

カラムをいくつか追加すると、dict は行ごとに大きくなります。やがて1つのモデルが、同期を保たなければならないキーと値の長大で壊れやすいブロックになってしまいます。

一覧エンドポイントと詳細エンドポイントは、どちらも同じ dict を作り直します。この重複により、名前を1つ変更するだけで、同じ形を多くの場所で編集しなければなりません。

生の datetime は JSON と相性が悪いため、jsonify がエラーになったり、推測で処理したりします。手作業のコードでは、アプリ全体で日付の形式を毎回同じにするのが難しくなります。

モデル全体を出力すると、password_hash や内部フラグまで送信してしまう可能性があります。手作業で JSON を構築すると、非公開フィールドを簡単に公開してしまいます。

投稿を複数持つユーザー1人を扱うだけで、dict の中にループがあり、その中にリストがあります。ネストした構造によってシリアライズコードは複雑に絡み合い、誰にとっても読みにくくなります。

手作業で構築した JSON は出力のことしか考えません。入力されたペイロードはチェックされないまま届くため、バリデーションも手作業で大量の if 文を書くことになります。

スキーマは、存在するフィールド、その型、ルールを一度に記述します。出力と入力の両方が、この1つの定義を通るようになります。

Marshmallow は Flask で広く使われているライブラリです。Schemaクラスを宣言するだけで、出力のシリアライズと入力のバリデーションを処理してくれます。

スキーマを使うと、フィールド一覧を1か所で管理できます。そこでフィールド名を変更または削除すれば、すべてのエンドポイントが自動的に一貫した状態になります。

壊れやすい dict の行を何十行も書く代わりに、すっきりしたクラスを使えます。その結果、コードが減り、出力が安全になり、API の明確な契約を定義できます。

手作業で構築した JSON は作業を重複させ、日付を適切に扱えず、秘密情報を漏らします。Marshmallow のようなスキーマ層はデータの形を一元管理し、すっきりと安全な出力を実現します。