🔫왜 당신은 데이터 구조화에 서툴러요 그리고 어떻게 하면 결국 더 나아질 수 있을까 💪

Source: Dev.to

1. UI 관점으로 사고하고 도메인 관점은 무시한다

대부분의 개발자는 실제 비즈니스 로직보다 Figma 화면이나 간단한 화이트보드 스케치에서 시작한다.

그들은 이렇게 묻는다:

“이 응답에 필요한 JSON은 뭐지?”

대신에 이렇게 물어야 한다:

“기본 도메인은 실제로 어떻게 생겼을까?”

그래서 API가 UI의 반영이 되고, 비즈니스의 반영이 아니다.

테이블, 모델, 라우트가 다음과 같이 냄새가 난다:

• subtitle
• isCollapsed
• displayOrder
• object.with.20.levels.of.depth

이건 데이터 모델링이 아니다. 컴포넌트 트리를 직렬화하고 있는 것이다.

2. “쉽게” 라는 이유로 무관한 개념을 합친다

다음 예는 익숙할 것이다:

{
  "user": { /* ... */ },
  "orders": [ /* ... */ ],
  "permissions": [ /* ... */ ],
  "stats": { /* ... */ }
}

축하한다. Blob API—JSON 스무디를 만들었다. 한 화면에서는 동작하지만, 다른 곳에서는 죽는다.

3. 안정적인 구조와 불안정한 구조를 구분하지 않는다

UI는 매주 바뀐다. 비즈니스 규칙은 매년 바뀐다.

만약 누군가가 Figma에서 카드를 옮기거나 고객이 “작은 변경”을 요청할 때마다 API가 깨진다면, 당신은 API를 만든 것이 아니다. UI 전송 레이어를 만든 것이다.

좋은 데이터 모델은 다음을 견뎌야 한다:

• 디자인 재구성
• 모바일 앱
• 파트너 연동
• 분석
• AI
• 새로운 기능
• 새로운 시장

이것들을 견디지 못한다면, 진짜 데이터 모델이 아니었다.

4. 여러 요청을 만드는 것이 두려워 과도하게 집계한다

일부 개발자는 이렇게 믿는다:

“전체 페이지를 위해 하나의 엔드포인트가 필요해.”

아니야, 필요 없어.

여러 비동기 호출을 하는 것이:

• 더 깔끔하고
• 예측 가능하며
• 캐시하기 쉽고
• 무효화하기 쉬우며
• 훨씬 유연하다

집계는 도구일 뿐, 기본값이 아니다.

5. 엔티티와 프로젝션을 구분하지 못한다

엔티티 = 비즈니스의 진실
프로젝션 = 특정 사용 사례를 위한 재구성된 편리한 데이터

이 둘을 섞으면 다음과 같은 문제가 생긴다:

• UI 필드가 영속성에 새어 나감
• 도메인 규칙이 컴포넌트 안에 코딩됨
• 디자인이 바뀔 때마다 API가 깨짐
• 모델을 아무도 이해하지 못함

좋은 개발자는 이 두 세계를 분리한다. 뛰어난 개발자는 프로젝션 경계를 문서화한다.

6. 어려운 질문을 하지 않는다

최고의 데이터 아키텍트는 다음을 묻는다:

• 진실의 출처는 어디인가?
• 실제로 존재하는 엔티티는 무엇인가?
• 절대 깨져서는 안 되는 불변식은?
• 모바일 앱이 이것을 사용할까?
• UI가 완전히 바뀐다면 어떻게 될까?

이 질문들을 하지 않으면 모델링이 아니라 스케치에 불과하다.

🔥 그럼… 어떻게 하면 나아질까?

✔️ 1. API보다 도메인을 먼저 모델링한다

화이트보드에 비즈니스를 박스로 설명하지 못한다면 → 엔드포인트를 만들지 마라.

✔️ 2. 엔티티를 순수하게 유지한다

UI 필드, 레이아웃 정보, Figma‑기반 명명은 금지.
데이터베이스 테이블이 React 컴포넌트처럼 보인다면, 모든 작업을 멈추고 리팩터링하라.
UI를 그대로 반영한다는 이유로 문서형 DB를 선택했다면 스스로에게 물어라:

“UI가 전혀 없었다면 어떻게 될까?”

✔️ 3. 더 많은 세분화된 엔드포인트를 선호한다

프론트엔드 프레임워크는 조합을 위해 만들어졌다. 이를 활용하라. UI가 데이터를 조합하게 하고, 데이터가 UI를 지배하지 않게 하라.

✔️ 4. 프로젝션은 절제해서 사용하고, 이름을 명확히 하라

• /orders → 엔티티
• /orders/overview → 프로젝션
• /dashboard → 프로젝션
• /users/:id/profile-view → 프로젝션

좋은 네이밍만으로도 혼란의 80 %를 없앨 수 있다.

✔️ 5. 여러 프론트엔드를 고려해 설계한다

스스로에게 물어라:

• 모바일 앱을 만든다면 이 구조가 여전히 타당할까?
• 파트너가 API를 소비한다면?
• 분석 파이프라인에 넣는다면?
• 내일 React를 교체한다면?

답이 아니오라면, 처음부터 다시 시작하라.

✔️ 6. 관계와 제약조건을 생각한다

진짜 데이터 모델은 “안에 뭔가가 들어있는 객체”가 아니다. 그것은:

• 엔티티
• 레퍼런스
• 불변식
• 제약조건
• 타임라인
• 상태 머신

여기서 개발자는 건축가가 된다.

✔️ 7. 단순함이 최고

여러 개의 작고 의미 있는 엔티티가 거대한 “신 객체” 하나보다 유지보수가 쉽다.

✔️ 8. 깊은 중첩을 피하고 평탄한 구조를 선호한다

API는 평탄하고 정규화된 데이터를 제공해야 한다. 그룹화·필터링·중첩·집계는 UI가 담당한다. 평탄한 데이터 = 예측 가능한 데이터.

✔️ 9. 올바른 이름을 사용하고 일관성을 유지한다

명확한 네이밍은 생명을 구한다. UserGroupsResponse는 즉시 이해된다. 이름 때문에 사람들이 추측해야 한다면 → 잘못된 것이다.

✔️ 10. 변화를 예상한다

모델은 성장하고, 진화하고, 복잡해진다. 유연성을 염두에 두고 설계하라. 미래의 당신이 고마워할 것이다.

🎯 최종 메시지

당신이 데이터를 구조화하는 데 서투른 이유는 실력이 부족해서가 아니다. 아무도 스크린을 넘어 생각하도록 가르쳐 주지 않았기 때문이다.

다음만 구분하면 모든 것이 쉬워진다:

• 도메인 vs. 프로젝션
• 엔티티 vs. 레이아웃
• 진실 vs. 편의

…스크린은 매주 바뀐다. 좋은 데이터 구조는 수십 년 동안 지속된다.