Cheondi
개발 · Unity

JSON 우선 화면 데이터 설계

새 화면을 붙이면서 프리팹보다 JSON 정의와 이를 읽는 로더부터 확인해야 했던 과정을 기록했습니다.

  • #unity
  • #json
  • #data-driven

새로운 자금 관련 화면을 붙일 때 예전처럼 Hierarchy부터 열었다. 비슷한 패널을 복사하고 이름을 바꾸면 시작할 수 있을 줄 알았다. 그런데 실행하면 내가 만든 프리팹이 아니라 전혀 다른 오브젝트가 나타났다. 첫 글에서 본 JSON 기반 생성 구조가 이번에도 화면의 시작점이었다.

몇 달 전에는 JSON이 오브젝트를 만든다는 사실 자체가 충격적이었다. 이번에는 조금 달랐다. 어느 JSON이 어떤 로더를 거쳐 어떤 프리팹을 선택하는지 순서를 정해서 볼 수 있었다.

파일명 기반 연결 규칙

JSON 파일 안에는 화면과 요소의 타입, 리소스 키와 기본값이 들어 있었다. 중요한 건 내용뿐 아니라 파일 이름과 경로도 로더의 규칙에 포함된다는 점이었다. 이름을 임의로 바꾸면 파일이 있어도 읽히지 않았다.

{
  "screen": "funds",
  "layout": "mobile",
  "elements": [
    { "type": "label", "id": "availableAmount" },
    { "type": "button", "id": "history" }
  ]
}

예시는 구조를 설명하기 위해 다시 만든 것이다. 실제로는 더 많은 속성과 환경별 분기가 있었다.

오브젝트 생성과 데이터 연결의 분리

JSON을 고쳐 오브젝트가 나타나도 값은 비어 있었다. 화면 요소를 만드는 로더와 서버에서 받은 값을 연결하는 스크립트가 따로 있었기 때문이다.

레이아웃 JSON -> 오브젝트 생성
응답 데이터   -> 화면 모델 생성
바인더        -> 오브젝트와 화면 모델 연결

처음에는 한 파일에서 모두 일어날 거라고 생각했다. 단계를 나눠 보니 오브젝트가 없는 문제와 값만 없는 문제를 다른 곳에서 찾아야 한다는 게 보였다.

키 불일치의 무음 실패

JSON의 id와 C#에서 찾는 키가 다르면 화면은 생성되지만 연결되지 않았다. 오류가 크게 나지 않고 빈 값만 보여서 더 찾기 어려웠다. 키를 문자열로 관리하는 구조에서는 오타가 컴파일 단계에 잡히지 않는다는 단점도 체감했다.

그래서 새 요소를 추가할 때는 다음을 한 줄씩 확인했다.

  1. JSON 파일이 실제로 로드됐는가
  2. 필요한 타입의 오브젝트가 만들어졌는가
  3. id가 바인더가 찾는 값과 같은가
  4. 데이터가 도착한 뒤 바인딩이 실행됐는가

구조 이해에 따른 검색 범위 축소

예전에는 화면이 안 보이면 프리팹, 스크립트, Scene을 넓게 검색했다. 이제는 JSON 정의에서 시작해 로더, 생성 결과, 바인더 순서로 좁혀 갔다. 처음 접했을 때 낯설었던 구조가 오히려 길잡이가 된 셈이다.

데이터 중심 UI가 항상 더 좋다는 결론을 내린 건 아니다. 문자열 키와 복잡한 로더 때문에 디버깅이 어려운 부분도 있었다. 다만 프로젝트가 왜 이 방식을 쓰는지, 어느 경계에서 문제가 생기는지는 이전보다 훨씬 빠르게 이해할 수 있게 됐다.

기술 문서 기반의 책임 경계

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

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

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

다음에 JSON 우선 화면 데이터 설계 같은 문제를 보면 아래 순서부터 확인하려고 한다.

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

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

공식 참고 자료