분산 시스템의 아키텍처 설계에서 API는 단순한 시스템 상호작용의 통로가 아닙니다. 이들은 서로 다른 기술 스택, 조직 문화, 심지어 개발 시대까지 연결하는 '계약'입니다. RESTful API 설계의 세부 사항 중 하나는 겉보기에는 사소하지만 끝없는 논쟁을 불러일으키는 주제입니다. JSON 필드 이름에 camelCase를 사용해야 할까요, 아니면 snake_case를 사용해야 할까요?
이것은 단순히 미학적인 선택이 아닙니다. 백엔드 영속성 계층과 프런트엔드 표현 계층 사이의 "임피던스 불일치"에 영향을 미치며, 직렬화 성능, 네트워크 전송 효율성, 개발자 경험(DX), 그리고 인지 심리학까지 아우릅니다.
프로그래밍 언어의 역사, 근본적인 기술 구현 메커니즘, 그리고 구글 및 스트라이프와 같은 업계 거물들의 아키텍처 결정을 바탕으로, 이 글은 전문가 수준의 의사 결정 가이드를 제공합니다.
1. 역사적 기원: 기호학적 선택
이 논쟁을 이해하려면 컴퓨터 언어의 진화를 추적해야 합니다. 명명 규칙은 아무것도 없는 곳에서 생겨난 것이 아니라, 특정 시대의 하드웨어 제약과 커뮤니티 문화의 산물입니다.
snake_case의 기원: C와 유닉스 철학
snake_case (예: user_id)의 인기는 1970년대 C와 유닉스로 거슬러 올라갑니다. 초기 키보드(예: Teletype Model 33)에 시프트 키가 있었지만, 많은 초기 컴파일러는 대소문자를 구분하지 않았습니다. 저해상도 디스플레이에서 단어를 명확하게 구분하기 위해 프로그래머들은 자연어의 공백을 시뮬레이션하기 위해 밑줄을 도입했습니다. 이 습관은 SQL 데이터베이스 표준에 깊이 뿌리내렸습니다. 오늘날까지 PostgreSQL과 MySQL의 기본 열 명명 스타일은 snake_case로 남아있으며, 이는 API와 데이터베이스 간의 미래 매핑 마찰의 토대를 마련했습니다.
camelCase의 부상: 자바와 자바스크립트의 헤게모니
camelCase (예: userId)는 객체 지향 프로그래밍(Smalltalk, C++, Java)과 함께 부상했습니다. 자바는 "클래스에는 PascalCase, 메서드/변수에는 camelCase"라는 산업 표준을 확립했습니다. 결정적인 전환점은 JavaScript의 탄생이었습니다. JSON은 JS 객체 리터럴에서 유래했지만, JS 표준 라이브러리(예: getElementById)는 전반적으로 camelCase를 채택했습니다. AJAX와 JSON이 XML을 대체하며 지배적인 데이터 교환 형식이 되면서, camelCase는 웹 영역에서 "기본" 지위를 얻게 되었습니다.
2. 핵심 충돌: 기술 스택의 임피던스 불일치
데이터가 다른 언어들 사이를 흐를 때, 필연적으로 "임피던스 불일치"를 겪게 됩니다.
백엔드 관점 (Python/Ruby/SQL)
백엔드에서는 Python (PEP 8)과 Ruby 커뮤니티에서 snake_case를 강력히 권장합니다.
- Python/Django/FastAPI: Pydantic 모델은 일반적으로 데이터베이스 테이블 구조와 직접적으로 대응합니다:
class UserProfile(BaseModel):
first_name: str # Python convention
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. 성능에 대한 오해: 직렬화 및 네트워크 전송
성능과 관련하여 두 가지 흔한 오해가 있습니다: "필드 이름 변환은 너무 느리다" 와 "밑줄은 페이로드 크기를 증가시킨다." 데이터를 통해 명확히 해봅시다.
오해 1: 런타임 변환 오버헤드
- 동적 언어: Python이나 Ruby에서 매 요청마다 정규식 교체를 통해 필드 이름을 변환하는 것은 CPU를 소모합니다. 그러나 최신 프레임워크(예: Rust로 재작성된 Pydantic v2)는 사전 계산된 스키마 매핑을 통해 이러한 오버헤드를 최소화합니다.
- 정적 언어 (Go/Java/Rust): 이것은 사실상 "제로 비용"입니다. Go의 구조체 태그(
json:"firstName")나 Java Jackson의 매핑 캐시는 컴파일 또는 시작 시점에 결정됩니다. 런타임 실행은 동적 계산이 아닌 간단한 바이트 복사를 포함합니다.
참고: 인터셉터(예: Axios)를 사용하여 프런트엔드(브라우저 메인 스레드)에서 전역 재귀 변환을 절대 수행하지 마십시오. 큰 응답의 경우, 이는 페이지 끊김 현상과 메모리 낭비를 유발합니다. 결론: 백엔드에서 변환을 처리해야 합니다.
오해 2: 전송 크기 및 압축
이론적으로 first_name은 firstName보다 한 바이트 더 깁니다. 그러나 Gzip 또는 Brotli 압축이 활성화되면(표준 HTTP 구성), 이 차이는 사실상 사라집니다.
- 원리: 압축 알고리즘은 "중복 문자열 참조"에 의존합니다. JSON 배열에서 키는 매우 반복적입니다. 알고리즘은
first_name을 처음 발견 시 딕셔너리에 저장하고, 이후 발생 시 작은 포인터로 대체합니다. - 벤치마크: Gzip 레벨 6에서 두 스타일 간의 크기 차이는 일반적으로 0.5%에서 1% 사이인 것으로 나타났습니다. 위성 링크를 통해 데이터를 전송하는 경우가 아니라면, 이는 문제가 되지 않습니다.
4. 개발자 경험(DX) 및 인지 심리학
아키텍처는 단순히 기계에 관한 것이 아니라 사람에 관한 것입니다.
- snake_case의 가독성: 인지 심리학은 밑줄이 명확한 시각적 분리를 제공한다고 제안합니다. 특히 연속된 약어(예:
XMLHTTPRequestvsXmlHttpRequest)를 다룰 때,parse_db_xml은parseDbXml보다 뇌에서 더 빠르게 파싱됩니다. 이것이 Stripe의 문서가 매우 읽기 쉽다고 평가받는 이유 중 하나입니다. - camelCase의 일관성: 풀스택 일관성이 가져오는 흐름 상태가 더 중요합니다. 풀스택 JS/TS 팀의 경우, 프런트엔드와 백엔드 모두에서
camelCase를 사용하면 타입 정의(인터페이스/Zod 스키마)를 직접 재사용할 수 있어 "정신적 번역"의 인지 부하를 완전히 제거합니다.
5. 산업 표준 및 근거
| 기관 | 선택 | 핵심 논리 및 배경 |
|---|---|---|
| 구글 | camelCase | 구글 API 가이드(AIP-140)는 JSON에 lowerCamelCase를 의무화합니다. 내부 Protobuf 정의가 snake_case를 사용하더라도, 외부 변환 계층은 웹 생태계에 맞춰 자동으로 camelCase로 전환합니다. |
| 마이크로소프트 | camelCase | .NET Core가 오픈소스를 받아들이고 TypeScript가 발명되면서, 마이크로소프트는 초기 PascalCase를 버리고 웹 표준으로 완전히 전환했습니다. |
| 스트라이프 | snake_case | 전형적인 Ruby 스택 회사입니다. 그들은 매우 강력한 클라이언트 SDK를 제공함으로써 차이점을 가립니다. Node SDK를 사용할 때, snake_case가 전송되더라도 SDK 메서드 시그니처는 일반적으로 JS 규칙을 따릅니다. |
| JSON:API | camelCase | 커뮤니티 주도 명세는 명시적으로 camelCase를 권장하며, 이는 웹 커뮤니티의 합의를 반영합니다. |
6. 심층 아키텍처 조언: 디커플링 및 DTO
흔한 안티 패턴은 "패스스루(Pass-through)"입니다: 데이터베이스 엔티티를 직접 직렬화하여 반환하는 것입니다.
- 이렇게 하면, DB 컬럼이
snake_case인 경우 API도snake_case가 됩니다. - 위험: 이는 정보 은닉 원칙을 위반하고, 테이블 구조를 노출하며, API와 DB 간에 강력한 결합을 생성합니다. DB 이름이 변경되면 API가 손상됩니다.
최고의 실천 방법: DTO(Data Transfer Object) 계층을 도입하십시오. 기본 데이터베이스가 어떻게 명명되었든 상관없이, 독립적인 API 계약(DTO)을 정의해야 합니다. DTO를 정의하는 김에, 웹 표준을 준수하기 위해 camelCase로 정의하는 것이 어떻습니까? 최신 매핑 도구(MapStruct, AutoMapper, Pydantic)는 이 변환을 손쉽게 처리합니다.
7. 미래 전망: GraphQL 및 gRPC
GraphQL: 커뮤니티는 거의 100% camelCase를 수용합니다. 팀이 향후 GraphQL 도입을 계획하고 있다면, 지금 REST API를 camelCase로 설계하는 것이 현명한 "하위 호환성" 전략입니다.
gRPC: Protobuf 표준은 필드 정의에 .proto 파일이 snake_case를 사용하도록 규정하지만, JSON에 매핑될 때는 반드시 camelCase로 변환되어야 합니다. 이는 다국어 환경에 대한 Google의 표준 솔루션입니다.
8. 요약 및 의사 결정 매트릭스
절대적으로 옳거나 그른 것은 없으며, 오직 트레이드오프만 존재합니다. 다음은 최종 의사 결정 프레임워크입니다:
권장: 기본적으로 camelCase 사용
웹/앱 클라이언트를 대상으로 하는 대부분의 새로운 범용 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를 사용하여 데이터베이스 모델을 직접 통과시키는 경우.
의사 결정표
| 측면 | 권장 스타일 |
|---|---|
| 웹 프런트엔드 / 모바일 앱 | camelCase (제로 임피던스, 타입 안전성) |
| 데이터 분석 / 과학 계산 | snake_case (Python/R 습관에 맞음) |
| Node.js / Go / Java 백엔드 | camelCase (네이티브 또는 완벽한 라이브러리 지원) |
| Python / Ruby 백엔드 | camelCase (변환기 권장) 또는 snake_case (내부 도구만 해당) |
| 풀스택 팀 | 풀스택 정도가 높을수록 camelCase를 더 권장합니다 |
API 설계의 본질은 공감입니다. 웹 API의 맥락에서, 백엔드에서 복잡성을 캡슐화하고(매핑 처리), 사용자에게 편의를 제공하는 것(JS 습관을 따르는 것)이 더 큰 전문성을 반영하는 선택입니다.