JSONフィールド名：camelCaseとsnake_case、どちらを使うべきか

分散システムのアーキテクチャ設計において、API はシステム間の連携のための単なる経路ではありません。異なる技術スタック、組織文化、さらには開発時代を結びつける「契約」です。RESTful API の設計詳細において、一見些細な議題でありながら終わりのない議論を巻き起こすものがあります。それは、JSON フィールド名に camelCase と snake_case のどちらを使用すべきか？という問題です。

これは単なる見た目の選択ではありません。バックエンドの永続化層とフロントエンドのプレゼンテーション層間の「インピーダンスミスマッチ」に触れる問題であり、シリアライズ性能、ネットワーク転送効率、開発者体験（DX）、そして認知心理学にも関わります。

プログラミング言語の歴史、基盤となる技術的な実装メカニズム、そして Google や Stripe といった業界の巨人のアーキテクチャ上の決定に基づき、この記事では専門家レベルの意思決定ガイドを提供します。

1. 歴史的起源：記号論的選択

この議論を理解するためには、コンピュータ言語の進化をたどる必要があります。命名規則は突然現れたものではなく、特定の時代のハードウェアの制約とコミュニティ文化の産物です。

snake_case の起源：C と Unix の哲学

snake_case (例: user_id) の人気は、1970年代の C 言語と Unix に遡ります。初期のキーボード（Teletype Model 33 など）にはシフトキーがありましたが、多くの初期コンパイラは大文字と小文字を区別しませんでした。低解像度のディスプレイ上で単語を明確に区別するため、プログラマーは自然言語のスペースを模倣するためにアンダースコアを導入しました。この習慣は SQL データベースの標準に深く根付きました。今日に至るまで、PostgreSQL および MySQL のデフォルトのカラム命名スタイルは snake_case のままであり、API とデータベース間の将来のマッピングにおける摩擦の土台を築いています。

camelCase の台頭：Java と JavaScript の覇権

camelCase (例: userId) は、オブジェクト指向プログラミング (Smalltalk, C++, Java) とともに台頭しました。Java は「クラスには PascalCase、メソッド/変数には camelCase」という業界標準を確立しました。決定的な転換点は、JavaScript の誕生でした。JSON は JS のオブジェクトリテラルから派生したものですが、JS の標準ライブラリ（例: getElementById）は全面的に camelCase を採用しました。AJAX と JSON が XML に代わって主要なデータ交換形式となるにつれて、camelCase は Web ドメインで「ネイティブ」な地位を獲得しました。

2. 核となる対立：技術スタックのインピーダンスミスマッチ

データが異なる言語間を流れる際、必然的に「インピーダンスミスマッチ」に遭遇します。

バックエンドの視点 (Python/Ruby/SQL)

バックエンドでは、Python (PEP 8) および Ruby コミュニティは snake_case を強く推奨しています。

• Python/Django/FastAPI: Pydantic モデルは通常、データベースのテーブル構造に直接対応します。

class UserProfile(BaseModel):
    first_name: str  # Python の慣習
    last_name: str

API が camelCase を義務付けている場合、シリアライズ層でエイリアスまたはコンバーターを設定する必要があります。これは実行可能ですが、マッピングロジックの層を追加することになります。

• SQL データベース: ほとんどのデータベースのカラム名は snake_case を使用します。API が camelCase を使用する場合、ORM 層が一貫して変換を処理する必要があります。
• Stripe の選択: Stripe と GitHub が snake_case を固く選んだ理由は、その初期アーキテクチャが Ruby スタック上に構築されていたことが大きく影響しています。内部モデルを直接公開することで、バックエンドの一貫性が保たれました。

フロントエンドの視点 (JavaScript/TypeScript)

ブラウザでは、camelCase が絶対的な支配者です。

• コードスタイルの断片化: API が snake_case を返す場合、フロントエンドのコードは一貫性を失います。

const user = await fetchUser();
console.log(user.first_name); // ESLint の camelcase ルールに違反
render(user.email_address);

ESLint はこれを警告としてフラグ付けし、開発者にルールの無効化またはデータ受信時の即時変換を強制します。

• 分割代入の苦痛: 現代の JS/TS 開発では、オブジェクトの分割代入が普及しています。フィールドが snake_case の場合、ローカルスコープを汚染しないように、分割代入時に名前を変更する必要があります。

// 冗長な名前変更
const { first_name: firstName, last_name: lastName } = response.data;

これはボイラープレートコードを増加させ、エラーの可能性を高めます。

3. パフォーマンスの誤解：シリアライズとネットワーク転送

パフォーマンスに関して、2つの一般的な誤解があります。それは「フィールド名変換は遅すぎる」と「アンダースコアがペイロードサイズを増大させる」です。データに基づいてこれらを明らかにしましょう。

誤解 1: ランタイム変換のオーバーヘッド

• 動的言語: Python や Ruby では、リクエストごとに正規表現置換でフィールド名を変換すると CPU を消費します。しかし、Pydantic v2 (Rust で書き換えられた) のような最新のフレームワークは、事前に計算されたスキーママッピングを通じてこのオーバーヘッドを最小限に抑えます。
• 静的言語 (Go/Java/Rust): これは実質的に「ゼロコスト」です。Go の構造体タグ (json:"firstName") や Java Jackson のマッピングキャッシュは、コンパイル時または起動時に決定されます。ランタイム実行は、動的な計算ではなく、単純なバイトコピーを伴います。

注: フロントエンド（ブラウザのメインスレッド）でインターセプター（例: Axios）を使用してグローバルな再帰的変換を絶対に行わないでください。大量のレスポンスの場合、これはページのガタつきやメモリの頻繁な割り当て/解放を引き起こします。結論：バックエンドが変換を処理すべきです。

誤解 2: 転送サイズと圧縮

理論的には、first_name は firstName よりも1バイト長いです。しかし、Gzip または Brotli 圧縮が有効になっている場合（標準的な HTTP 設定）、この違いは実質的に消滅します。

• 原則: 圧縮アルゴリズムは「重複文字列参照」に依存します。JSON 配列では、キーは非常に繰り返し出現します。アルゴリズムは最初に first_name を辞書に格納し、その後の出現を小さなポインタで置き換えます。
• ベンチマーク: テストによると、Gzip レベル 6 の下では、両スタイルのサイズの違いは通常0.5% から 1% の間です。衛星回線でデータを転送しているのでない限り、これは問題になりません。

4. 開発者体験 (DX) と認知心理学

アーキテクチャは機械だけのものではありません。人間のためのものです。

• snake_case の可読性: 認知心理学では、アンダースコアが明確な視覚的分離を提供すると示唆されています。特に連続する頭字語（例: XMLHTTPRequest と XmlHttpRequest）を扱う場合、parse_db_xml は parseDbXml よりも脳によって速く解析されます。これが Stripe のドキュメントが非常に読みやすいとされている理由の一つです。
• camelCase の一貫性: フルスタックの一貫性によってもたらされるフロー状態は、より重要です。フルスタックの JS/TS チームにとって、フロントエンドとバックエンドの両方で camelCase を使用することで、型定義（Interface/Zod Schema）を直接再利用でき、「精神的な変換」という認知負荷を完全に排除できます。

5. 業界標準とその根拠

6. 詳細なアーキテクチャアドバイス：デカップリングと DTO

一般的なアンチパターンは「パススルー」です。これは、データベースエンティティを直接シリアライズして返すことです。

• これを行うと、DB カラムが snake_case であれば、API も snake_case になります。
• リスク: これは情報隠蔽の原則に違反し、テーブル構造を公開し、API と DB 間に強い結合を作り出します。DB の名前が変更されると、API は壊れます。

ベストプラクティス: DTO (Data Transfer Object) 層を導入します。基盤となるデータベースがどのように命名されていても、独立した API 契約 (DTO) を定義すべきです。DTO を定義するのですから、Web 標準に準拠するために camelCase で定義してみてはいかがでしょうか？最新のマッピングツール（MapStruct, AutoMapper, Pydantic）は、この変換を容易に処理します。

7. 将来の展望：GraphQL と gRPC

GraphQL: コミュニティはほぼ100% camelCase を採用しています。もしチームが将来的に GraphQL の導入を計画しているなら、今 REST API を camelCase で設計することは賢明な「将来互換性」戦略となります。

gRPC: Protobuf 標準では、.proto ファイルはフィールド定義に snake_case を使用しますが、JSON にマッピングされる際には必ず camelCase に変換されなければなりません。これは Google が多言語環境のために採用している標準的な解決策です。

8. まとめと意思決定マトリックス

絶対的な正解や間違いはなく、トレードオフがあるだけです。以下に最終的な意思決定フレームワークを示します。

推奨：デフォルトは camelCase

Web/アプリクライアント向けの新しい汎用 RESTful API の大部分においては、camelCase が強く推奨されます。

理由: JSON/JavaScript/TypeScript の優位性に合わせ、90% の利用者の習慣に適応するためです。

ツール: OpenAPI コードジェネレーター、Swagger UI、最新の IDE から最高のサポートが得られます。

snake_case を使用すべき時とは？

1. 特定の利用者: API の主な利用者が Python のデータサイエンティストやシステム運用担当者（Curl/Bash）である場合。

2. レガシーシステム: 既存の API がすでに snake_case である場合。一貫性 ＞ ベストプラクティス。同じシステム内でスタイルを混在させないでください。

3. バックエンドの速度重視: DTO 層を維持するリソースがない Python/Ruby を使用しており、データベースモデルを直接パススルーする場合。

意思決定表

API 設計の本質は共感です。Web API の文脈では、バックエンドで複雑さをカプセル化し（マッピング処理）、ユーザーには利便性（JS の慣習に準拠）を提供する選択が、よりプロフェッショナリズムを反映していると言えます。