Cheondi
개발 · 웹

국가별 기본 설정 파일

국가별 기본 옵션을 나누며 빌드 설정, 서버 정책, 사용자 저장값의 우선순위를 정한 기록입니다.

  • #configuration
  • #web
  • #defaults

지역에 따라 처음 보여줄 상품과 일부 화면 옵션이 달라지는 요구가 생겼다. 국가별 JSON 파일을 하나씩 만들면 빠를 것 같았지만 공통 필드가 복사되고 수정이 빠진 파일이 생겼다. 이미 사용자가 저장한 설정과 새 국가 기본값 중 무엇을 적용할지도 모호했다.

기본값은 첫 실행의 편의를 위한 값이지 서버 권한을 대신하는 규칙이 아니었다.

공통 설정과 국가별 차이의 분리

전체 파일을 국가마다 복사하지 않고 공통 기본값 위에 국가별 override를 적용했다.

{
  "country": "example-country",
  "overrides": {
    "defaultLanguage": "en",
    "defaultProduct": "sample"
  }
}

허용되지 않은 필드는 override할 수 없도록 스키마와 허용 목록을 뒀다. 인증이나 거래 권한은 서버 응답을 기준으로 했다.

국가별 설정 적용 우선순위

사용자가 직접 바꾼 값은 새 기본값보다 우선했다. 앱 업데이트가 개인 설정을 되돌리지 않게 출처를 구분했다.

서버 강제 정책
 > 사용자가 저장한 값
 > 국가별 기본값
 > 공통 기본값

각 값의 우선순위는 성격에 따라 달랐고, 서버 정책과 단순 UI 선호를 같은 규칙으로 섞지 않았다.

국가 판정 실패의 기본 경로

국가 정보가 없거나 새 코드가 들어오면 앱이 시작하지 못하는 대신 공통 기본값을 사용했다. 알 수 없는 국가 코드를 로그에 안전하게 집계하고 설정 파일 업데이트 대상으로 남겼다.

언어와 국가는 같은 값이 아니었다. 사용자가 다른 언어를 선택할 수 있도록 국가 기본 언어는 첫 제안으로만 사용했다.

국가 값 자체도 기기 locale, 가입 정보, 서버 판정 중 출처가 여러 개였다. 기기 설정만으로 중요한 정책을 정하지 않고 서버가 제공한 제품 범위를 기준으로 했다. 출처가 바뀌면 어떤 기본값을 다시 계산하고 어떤 사용자 선택을 그대로 둘지도 정했다.

국가별 설정 조합 테스트

국가별 파일을 전부 파싱하고 필수 필드, 허용 키, 공통 설정과 병합 결과를 검사했다. 기존 사용자, 첫 사용자, 국가 변경, 오프라인 시작을 나눠 확인했다.

설정 파일을 캐시할 때는 국가 코드와 설정 버전을 키에 포함했다. 새 버전 다운로드가 실패해도 마지막으로 검증된 조합을 사용하고, 다른 국가 파일을 임의로 대신 적용하지 않았다. 잘못된 조합보다 공통 기본값이 안전했다.

이 작업 뒤 기본값을 하드코딩된 편의 값으로 보지 않는다. 여러 출처의 설정이 만나는 정책이므로 소유자와 우선순위, 실패 대체 경로가 필요했다. 국가 파일을 나눈 일은 설정 시스템의 경계를 다시 세우는 일이었다.

공식 문서 기반의 추가 정리

이 문제를 고친 뒤 관련 공식 자료를 찾아 읽으면서, 당시 코드에서 우연히 맞았던 부분과 규칙으로 남겨야 할 부분을 나눠 봤다.

Unity의 JsonUtility 문서를 다시 읽어 보니, JSON을 자유로운 key-value 저장소처럼 다루기보다 직렬화 가능한 클래스와 필드에 대응시키는 도구라는 점이 더 분명했다. 모르는 필드는 무시되고 빠진 필드는 생성된 객체의 기본값으로 남을 수 있다. 따라서 파싱에 성공했다는 사실과 지금 화면에서 써도 되는 데이터라는 판단은 같지 않다.

RFC 8259도 객체 멤버의 순서를 상호운용 가능한 계약으로 기대하지 않는다. 배열 순서가 의미를 가져도 객체 필드가 적힌 순서까지 로직에 사용하면 다른 생성기나 마이그레이션에서 쉽게 깨진다.

다음에 국가별 기본 설정 파일 같은 문제를 보면 아래 순서부터 확인하려고 한다.

  • schema version과 마이그레이션 경로
  • 필수 필드·기본값·범위 검증
  • 깨진 항목만 격리하는 단위
  • 이전 버전으로 되돌릴 수 있는지

형식이 올바른 JSON이어도 필수 식별자, 범위, 버전이 맞지 않으면 화면 모델로 넘기지 않는 편이 안전하다.

공식 참고 자료