버튼 라벨 ≠ 파라미터명, 이관 단계에서 끝내는 통일 규칙
버튼 라벨 ≠ 파라미터명, 이관 단계에서 끝내는 통일 규칙
서론
이름이 다르면 의도가 흐려지고, 이관에서는 시간이 새어 나간다.
개발 이관 단계에서 가장 많이 발생하는 문제가 버튼 라벨과 API 파라미터명이 다른 경우입니다. 이 글은 이관 시점에 네이밍 통일을 확정하고, 문서 간 크로스 링크로 추적성을 확보하는 방법을 정리했습니다. 아래 체크리스트를 적용하면 QA 지연을 줄이고 재작업을 예방할 수 있습니다.
📚 목차
본론
1) 왜 통일 규칙이 필요한가
- 동일 개념을 다른 이름으로 부르면 테스트 케이스 설계와 로그 분석이 어려워집니다.
- 코드 리뷰에서 의미 해석 시간이 증가합니다.
- CS 문구와 사용자 가이드에도 혼선이 생깁니다.
2) 네이밍 원칙: 라벨·파라미터·응답·코드
- 표준 용어: 용어 사전에 한글 명칭/영문 키/설명을 등록합니다.
- UI 라벨: 문장형. 예) “쿠폰 적용”.
- 요청 파라미터:
snake_case또는camelCase로 서비스 표준을 고정. - 응답 필드: 요청과 짝이 되도록 동일 키 사용.
- 에러 코드: 도메인 접두사+숫자. 예)
COUPON_4001.
3) 식별자 규칙: 화면ID·요소ID·이벤트
- 화면ID:
SCR-CART-010형태. - 요소ID:
BTN-APPLY-COUPON등 목적 기반. - 이벤트:
evt_coupon_apply_click등 추적용 키.
4) 매핑 테이블 작성법(예시 포함)
| UI 라벨 | 요소ID | API 엔드포인트 | 요청 파라미터 | 타입 | 정책 코드 | 에러 코드 |
|---|---|---|---|---|---|---|
| 쿠폰 적용 | BTN-APPLY-COUPON | POST /v1/coupons/apply | coupon_code | string(16) | POL-Coupon-001 | COUPON_4001(만료) |
| 포인트 사용 | BTN-USE-POINT | POST /v1/points/use | amount | integer | POL-Point-002 | POINT_4002(잔액부족) |
표는 RD 요구사항ID, 테스트케이스(TC) ID와도 링크합니다.
5) 개발 이관 패키지 구성(8종)
- RD 최종본
- 최신 화면 설계(상태/오류/빈 상태 포함)
- API 명세(요청/응답/에러 코드)
- 플로우차트와 상태 다이어그램
- 에지 케이스 목록
- 샘플 JSON 요청/응답
- 에러 코드 표
- 용어 사전·코드 테이블
참고: 패키지는 프로젝트 루트에서 동일 규칙의 폴더와 파일명으로 관리합니다.
6) 정렬·링크 기준: 화면→플로우→API→정책
- 정렬 기준: 화면ID → 플로우 → API → 정책 순으로 묶습니다.
- 각 문서에는 상호 링크를 삽입합니다(예: 화면 설계 → 관련 API 스펙).
- 이름과 코드, 라벨을 동일하게 사용합니다.
7) 샘플 JSON·에러 코드 표준
{
"coupon_code": "WELCOME10",
"amount": 1000,
"errors": [
{ "code": "COUPON_4001", "message": "쿠폰이 만료되었습니다." }
]
}
- 키 이름은 용어 사전의 영문 키와 일치시킵니다.
- 에러 코드는 도메인별 접두사와 숫자 체계를 유지합니다.
- 메시지는 사용자용과 내부용을 구분합니다.
8) 사례: 라벨≠파라미터 불일치 해결
문제: 화면 라벨 “쿠폰 사용하기”, API 파라미터 voucher_id로 정의되어 QA에서 혼선 발생.
- 용어 사전에 표준 용어를 “쿠폰 / coupon / coupon_code”로 확정.
- UI 라벨 “쿠폰 적용”으로 정리, 파라미터를
coupon_code로 변경. - 매핑 테이블, 샘플 JSON, 테스트케이스를 함께 갱신.
결과: QA 질의 감소, 로그 분석과 CS 응대 문구가 동일해짐.
9) 이관 체크리스트
- UI 라벨 = 파라미터 키 = 응답 필드 = 로그 이벤트 키.
- 화면ID–플로우–API–정책 문서 간 링크가 있다.
- 샘플 JSON과 에러 코드 표가 최신이다.
- 에지 케이스가 테스트케이스와 연결되어 있다.
- 버전과 변경 이력이 문서 상단에 있다.
주의: 화면 설계의 버튼 이름과 API 파라미터명이 다르면 QA에서 지연됩니다. 동일 용어를 유지하세요.
결론
이관의 핵심은 통일입니다. 용어, 라벨, 파라미터, 코드가 하나의 규칙으로 연결되어야 개발과 QA가 같은 기준으로 움직입니다. 위의 매핑 테이블과 패키지 구성을 적용해 문서 간 추적성을 확보하고, 릴리즈 전에 불일치를 사전에 제거하세요.
FAQ
Q UI 라벨과 API 필드가 다를 때 무엇을 기준으로 통일하나요?
A 용어 사전의 표준 용어를 기준으로 합니다. 한글 라벨과 영문 키를 짝지어 등록하고, 모든 문서에서 동일하게 사용합니다.
Qsnake_case와 camelCase 중 무엇을 써야 하나요?
A 백엔드·프런트 표준 가운데 하나를 조직 차원에서 선택해 고정합니다. 혼용은 금지합니다.
Q 레거시 API와 새 규칙이 충돌하면?
A 어댑터 계층에서 매핑을 두고, 외부 계약은 유지하면서 내부 명명 규칙을 통일합니다. 변환 규칙은 문서화합니다.
Q 다국어 라벨은 어떻게 관리하나요?
A 키는 영문으로 고정하고, 라벨은 리소스 파일로 분리합니다. 키는 정책·로그·API와 동일하게 유지합니다.
Q 누가 네이밍 규칙을 소유하나요?
A 기획이 용어 사전을 소유하고, 개발이 API 키를 관리하며, QA가 추적성 검증을 수행합니다. 변경은 버전과 승인 기록을 남깁니다.