변수명과 API 필드명을 바꿀 때: 표기 규칙·이름 충돌·호환성 확인 순서

이름의 사용 범위부터 구분하세요

user_id를 userId로 바꾸는 작업은 화면에서 두 글자를 고치는 것처럼 보입니다. 그러나 그 이름이 함수 안에서만 쓰이는지, 저장된 JSON이나 외부 API 응답에 쓰이는지에 따라 변경 범위가 달라집니다. 먼저 이름을 읽는 곳과 쓰는 곳을 목록으로 적어야 합니다.

내부 변수라면 해당 언어의 참조를 함께 바꾸면 될 수 있습니다. 외부에 보낸 필드라면 이전 이름을 읽는 앱·자동화·분석 작업이 남아 있을 수 있습니다. 공개한 이름을 바꾸면서 소비자까지 동시에 수정할 수 있다고 가정하면 누락이 생기기 쉽습니다.

이름이 있는 곳	확인할 소비자	변경 전 남길 기록
함수 안의 변수	같은 범위의 코드	새 이름과 충돌하는 선언
여러 파일에서 쓰는 함수	import·호출·테스트	참조 위치와 공개 여부
API의 JSON 키	앱·서버·외부 연동	기존 응답 예시와 계약
저장 데이터의 키	과거 자료를 읽는 코드	이전 형식의 복원·호환 방법
파일 이름	import·문서 링크·배포 경로	대소문자까지 포함한 원래 경로

이름을 바꾸는 이유도 한 문장으로 적으세요. “팀의 내부 변수 규칙에 맞춘다”는 목적과 “외부 API 응답 형식을 바꾼다”는 목적은 작업 범위가 다릅니다. 목적이 내부 가독성이라면 경계에서 값을 옮겨 담는 방법으로 외부 계약을 유지할 수 있습니다.

표기 규칙과 유효한 이름은 별개입니다

camelCase·snake_case·kebab-case는 단어를 연결하는 관례입니다. 어느 관례를 골랐다는 사실만으로 모든 언어와 저장소에서 유효한 이름이 되지는 않습니다. JavaScript 변수는 숫자로 시작할 수 없고, 예약어 제한도 있습니다. 반면 객체의 속성 이름이나 JSON의 문자열 키에는 다른 규칙이 적용됩니다. 정확한 언어 규칙은 MDN의 어휘 문법에서 확인할 수 있습니다.

예를 들어 order-total은 문자열 키로 쓸 수 있지만 그 모양 그대로 변수 선언의 이름으로 쓸 수는 없습니다. 숫자로 시작하는 2nd item을 camelCase로 바꿨다고 변수 이름의 첫 문자가 자동으로 고쳐지는 것도 아닙니다. 팀에서 약어를 Id로 쓸지 ID로 쓸지도 미리 정해야 합니다.

Tooliv는 소문자 다음의 대문자, 공백·밑줄·하이픈 등을 기준으로 텍스트를 나눕니다. 사전이나 코드 구문 분석으로 의미를 찾지 않습니다. 약어 경계에 대한 구체적인 예시는 camelCase·snake_case 변환 결과 확인법에서 따로 다룹니다. 이 글에서는 그 후보를 실제 프로젝트에 적용하기 전에 무엇을 확인할지에 집중합니다.

서로 다른 이름이 하나로 합쳐질 수 있습니다

아래는 현재 도구와 같은 분리·소문자 결합 연산을 직접 실행한 결과입니다. 변환 전에 서로 달랐던 문자열 세 개가 모두 같은 결과가 됩니다.

원래 이름	snake_case 결과	의미
userID	user_id	소문자 다음 대문자에서 분리
user_id	user_id	기존 구분을 유지
User Id	user_id	공백 분리 후 소문자로 통일

실제 데이터에 이 세 키가 함께 존재한다면 일괄 변환해서 같은 객체에 넣는 순간 어느 값을 보존할지 결정해야 합니다. 단순한 변환 스크립트는 나중 값을 앞선 값 위에 덮어쓸 수 있습니다. 표기가 같아졌다는 이유로 원래 값도 같은 의미라고 판단하면 안 됩니다.

먼저 원래 이름·새 이름·사용 범위·예외 처리를 표로 만들고, 새 이름의 중복을 변경 전에 확인하세요. 중복이 있으면 의미에 맞게 customerId, operatorId처럼 이름 자체를 다시 정하거나 기존 계약을 유지합니다. 밑줄을 임의로 추가하는 방식은 기술적으로 충돌을 피하더라도 뜻이 불분명한 이름을 남길 수 있습니다.

내부 표기 통일은 경계에서 처리할 수 있습니다

외부 API가 user_id를 보내고 내부 코드가 userId를 사용해야 한다면, 수신 직후 명시적으로 매핑하는 방법이 있습니다. 아래는 직접 실행한 작은 예시입니다.

const response = { user_id: '0072', display_name: '민수' };
const viewModel = {
  userId: response.user_id,
  displayName: response.display_name,
};

이 경우 response의 키는 그대로이고 viewModel.userId는 문자열 '0072'입니다. 앞자리 0을 가진 식별자를 숫자로 바꾸지 않았습니다. 이는 두 필드만 매핑하는 예시이며, 실제 API에서는 필수 키 누락·자료형·예외 응답을 별도 검증해야 합니다. 모든 객체의 모든 키를 자동으로 바꾸는 범용 해결책으로 쓰면 안 됩니다.

외부 계약 자체를 바꿔야 한다면 이전 형식과 새 형식이 함께 존재하는 기간, 소비자 전환 확인, 이전 필드 제거 시점을 정합니다. 두 이름을 동시에 허용할 때 값이 서로 다르면 무엇을 할지도 명시해야 합니다. Semantic Versioning을 채택한 안정된 공개 API는 호환되지 않는 변경을 주 버전 변경으로 표현합니다. 다만 실제 서비스의 버전 정책은 그 서비스 계약과 운영 규칙을 따라야 합니다.

코드 참조 수정과 문자열 검색을 함께 사용하세요

코드의 심볼 이름은 언어를 이해하는 편집기의 이름 변경 기능이 도움이 됩니다. VS Code의 Rename Symbol은 지원되는 언어에서 여러 파일의 참조를 바꿀 수 있습니다. 언어 지원 범위가 다르므로 변경 미리보기에서 의도한 참조가 포함됐는지 확인하세요.

그 기능만으로 외부 API, 데이터베이스의 과거 값, 문자열로 동적으로 조립한 키까지 모두 수정됐다고 판단하면 안 됩니다. 예를 들어 record['user_' + suffix] 같은 접근이나 설정 파일의 문자열은 별도 검색이 필요합니다. 문서·예시 JSON·테스트 데이터·분석 쿼리도 소비자에 포함될 수 있습니다.

반대로 텍스트 전체 찾기·바꾸기는 같은 글자가 들어간 설명이나 다른 범위의 이름까지 바꿀 수 있습니다. 먼저 코드의 참조를 고친 뒤 남은 원래 문자열을 검색해 의미를 확인하는 방식으로 두 작업을 보완하세요. 변경 범위가 큰 경우에는 도구가 보여 준 수정 목록을 검토하고 작은 단위로 적용해야 되돌리기도 쉽습니다.

검수는 문법·계약·실제 읽기 순서로 진행하세요

1. 새 이름이 해당 언어에서 유효하고 같은 범위에서 중복되지 않는지 확인합니다.
2. 변경 전후 데이터의 필드 수, 값, 자료형을 비교합니다.
3. 이전 형식으로 저장된 샘플을 새 코드가 읽는지 확인합니다.
4. 실제 소비자의 요청·응답 흐름을 확인하고 필요한 문서와 예시를 갱신합니다.
5. 이전 이름의 남은 참조를 찾아 의도적으로 유지한 것과 누락된 것을 구분합니다.

JSON 포매터에서 오류가 없다는 것은 JSON 문법이 맞는다는 뜻입니다. 기대한 키가 존재하거나 외부 앱이 계속 작동한다는 뜻은 아닙니다. 표기 변환과 제출 규격을 함께 맞추는 작업은 텍스트를 옮기기 전 확인할 기준으로 이어서 확인하세요.