文字のケース変換 snake_case、camelCase、およびAPIにおけるその重要性

掲載日 2026年4月29日

文字のケースは、開発者が意識しないまま、生産環境で静かに何かを壊してしまうことの一つです。JavaScriptのフロントエンドが送信する userId しかし、Pythonのバックエンドは user_idを期待しています。ORMがSQLのカラムを静かに名前を変更します。CIジョブが失敗するのは、環境変数のスペルが間違っていたためです。

ケース規則は、異なる言語、フレームワーク、システムがそれぞれ進化してきたため、それぞれに独自の慣習があるから存在しています。どのフォーマットがどこに適しているかを理解し、それらの間で変換できる知識は、デバッグ時間を節約する実用的なスキルです。

主なケースフォーマット

以下は、実際の現場で見かけるものと、それぞれが適切な場面を一覧にまとめています。

コンテクスト	大会	例	注記
JavaScriptの変数／JSONキー	キャメルケース	`userId`, `firstName`	ほとんどのREST APIがこのフォーマットを採用しています
Pythonの変数／JSONキー	スネークケース	`user_id`, `first_name`	Django、FastAPI、SQLAlchemyのデフォルト
クラス名（ほとんどの言語）	パスカルケース	`UserProfile`, `ApiResponse`	また、UpperCamelCaseと呼ばれます
URLパス	kebab-case	`/user-profile`, `/api-docs`	アンダースコアよりも、SEOが優れています
環境変数	SCREAMING_SNAKE	`DATABASE_URL`, `API_KEY`	シェルやCIプラットフォームで普遍的に使用されています
HTTPヘッダー	Train-Case	`Content-Type`, `X-Api-Key`	HTTP/1.1の標準
SQLカラム／テーブル	スネークケース	`user_id`, `created_at`	PostgreSQL、MySQLの慣例

ケースの不一致がAPI統合を壊す理由

最もよく見られる問題は、JavaScriptとPythonの境界です。JavaScriptエコシステム（React、Node、ブラウザAPI）はcamelCaseを生成し、Pythonエコシステム（FastAPI、Django REST Framework、SQLAlchemy）はsnake_caseを期待しています。

JavaScriptクライアントがこのペイロードを送信するとき：

{
  "firstName": "Alice",
  "userId": 42
}

Pythonサーバーがアクセスするとき： request.json["first_name"] を取得します。 KeyError警告もなく、フォールバックもなく、ただクラッシュします。FastAPIはPydanticモデルで alias_generator = to_camel を用いてこの問題を解決できますが、これはほとんどのチームが問題に遭遇するまで設定しないオプション設定です。

同じ問題は、JavaScriptとGraphQLの境界、異なる言語で書かれたマイクロサービスの間、およびJSONをデシリアライズする際に、明示的なフィールドマッピングがない場所で現れます。

プログラム的に変換する

ほとんどの言語でこの問題は解決されていますが、アプローチは異なります。

JavaScript： 最もきれいなオプションは change-case (軽量)または lodash (_.camelCase, _.snakeCase)です。もしデプロイメントをスキップしたい場合は：

// camelCase → snake_case
const toSnakeCase = str =>
  str.replace(/[A-Z]/g, letter => `_${letter.toLowerCase()}`);

toSnakeCase('userName');   // 'user_name'
toSnakeCase('createdAt');  // 'created_at'

Python： の re モジュールが処理しますが、単一ステップのバージョンは HTTPSProxyのような略語に対して破綻します。二段階アプローチを使用してください：

import re

def to_snake_case(name):
    s1 = re.sub(r'(.)([A-Z][a-z]+)', r'\1_\2', name)
    return re.sub(r'([a-z0-9])([A-Z])', r'\1_\2', s1).lower()

to_snake_case('userName')    # 'user_name'
to_snake_case('HTTPSProxy')  # 'https_proxy'

Ruby： 標準ライブラリにはケース変換機能が含まれていません。 github.com/iancoleman/strcase は一般的な選択肢です：

import "github.com/iancoleman/strcase"

strcase.ToSnake("UserName")  // "user_name"
strcase.ToCamel("user_name") // "UserName"
strcase.ToKebab("UserName")  // "user-name"

コードを書かずにすぐに変換が必要な場合は、 IO Tools String Case Converter はcamelCase、PascalCase、snake_case、kebab-case、SCREAMING_SNAKE、その他すべてを処理し、インストール不要です。

データベースの慣例とORMの課題

SQLデータベース（PostgreSQL、MySQL、SQLite）は、カラムとテーブル名に通常snake_caseを使用します。 user_id, created_at, payment_methodこれは期待されるフォーマットであり、raw SQLクエリもそのフォーマットを反映します。

ORMは、あなたの言語の命名規則とデータベースの間を自動的に変換することが多く、これは便利ですが、その便利さが失われる場合があります。Sequelizeは、一部の設定でJavaScriptのcamelCaseをsnake_caseに自動変換しますが、モデルオプション、ドライバー、またはバージョンによってはその動作が異なります。PrismaはcamelCaseのフィールド名をsnake_caseのカラムにマッピングし、ActiveRecordはテーブル名を複数形にし、すべてをsnake_caseに変換します。

実用的なアプローチは、明示的に設定することです。モデル定義でカラム名を明示的に定義し、自動変換に頼らないようにします。これはコードレビューでマッピングを可視化し、rawクエリを実行したり、別のORMに移行する際に驚きを回避します。

URLパス：kebab-caseを使用し、アンダースコアは使わない

URLパスに関しては、kebab-caseが明確な推奨です。Googleのドキュメントは歴史的にハイフンを単語分離子とし、アンダースコアを単語結合子として扱っています。URLのように /string-case-converter は二つの異なる単語を示します。 /string_case_converter は一つの長いトークンとして読みます。

実用的な影響は、kebab-caseのURLが複数単語キーワードターゲティングにおいて、検索でのパフォーマンスを向上させることです。これは大きなランキング要因ではありませんが、最初から正しいようにすることはコストを一切かかりません。

主要なAPIはすべてkebab-caseを使用しています。GitHub、Stripe、TwilioはすべてURLパスでkebab-caseを使用しています。セグメントのように /api/v1/user-profiles は読みやすく、タイピングしやすく、ウェブ標準と一致しています。

設定ファイル：環境変数はSCREAMING_SNAKE、YAMLはcamelCase

環境変数は普遍的にSCREAMING_SNAKE_CASEを使用しています。 DATABASE_URL, AWS_SECRET_ACCESS_KEY, REDIS_HOST — これはLinux、Docker、Kubernetes、そしてすべてのCI/CDプラットフォームで共通しています。シェルはこのフォーマットで変数をエクスポートします。これを無視しないでください。

YAML設定ファイルは別の話です。Kubernetesマニフェスト、Docker Compose、GitHub Actionsワークフローはキーに対してcamelCaseを使用しています。 apiVersion, containerPort, imagePullPolicy。Ansibleは、タスク定義のすべてでsnake_caseを使用しています。

ここでのルールはシンプルです：ツールが期待するフォーマットに合わせてください。すべての設定ファイルを一貫性を保つために正規化しようとしないでください。それは労力を節約せず、むしろ不一致を生み出します。