아름다운 UI와 튼튼한 API는 같은 기술이다: 경계면을 설계하는 사람의 사고법

May 25, 2026

6 min read

2 views

88%

우리가 자꾸 놓치는 진짜 문제는 기능이 아니다

많은 개발자들은 UI를 보이는 부분, API를 연결하는 부분이라고 생각한다. 그래서 UI는 미감의 문제처럼 다루고, API는 통신의 문제처럼 다룬다. 하지만 실제 제품의 품질을 결정하는 것은 기능의 총합이 아니라 경계면의 설계다. 사용자는 화면을 통해 제품을 이해하고, 시스템은 API를 통해 서로를 이해한다. 둘 다 결국 같은 질문에 답한다. 어떻게 하면 복잡한 내부를 단순하고 믿을 만한 외부로 바꿀 것인가?

이 질문을 놓치면 UI는 예쁜데 쓰기 어렵고, API는 잘 동작하는데 통합하기 힘든 형태로 굳어진다. 반대로 이 질문을 제대로 붙잡으면, 디자인과 백엔드 아키텍처는 전혀 다른 분야가 아니라 같은 철학의 두 표현이라는 사실이 보인다. 좋은 UI는 사용자의 인지 부하를 줄이는 인터페이스이고, 좋은 API는 다른 시스템의 인지 부하를 줄이는 인터페이스다.

좋은 인터페이스는 내부를 감추는 것이 아니라, 내부의 복잡성을 다른 주체가 감당 가능한 형태로 재구성하는 일이다.

이 관점에서 보면, UI 디자인 강좌와 포트와 어댑터 패턴이 같은 대화의 다른 장면처럼 보이기 시작한다. 하나는 인간을 위한 경계면, 다른 하나는 기계를 위한 경계면이다. 그러나 둘 다 핵심은 동일하다. 복잡성을 흐리지 않고, 다룰 수 있게 만드는 기술이다.

UI는 그림이 아니라 인지의 아키텍처다

UI를 잘 만든다는 것은 색을 고르고 여백을 맞추는 일만이 아니다. 그것은 사용자의 머릿속에서 일어나는 해석 비용을 줄이는 일이다. 사용자는 제품의 구조를 읽고, 가능성을 추론하고, 다음 행동을 예상해야 한다. UI가 나쁘면 이 추론이 계속 끊긴다. 버튼이 어디에 있는지, 이 값이 무엇을 의미하는지, 지금 상태에서 무엇이 가능한지 매번 다시 해석해야 한다.

그래서 UI 학습에서 그림 그리기, 타이포그래피, 레이아웃, CSS 같은 요소가 중요한 이유는 단순히 예쁘기 때문이 아니다. 이 요소들은 모두 정보를 어떻게 배치하면 사람이 즉시 이해하는가와 연결된다. 마치 지도 제작자가 지형을 축소하는 방식에 따라 사용자의 길찾기 난이도가 바뀌듯, 화면의 구성은 제품의 복잡도를 압축하는 방식이다.

예를 들어, 로그인 폼이 있다고 하자. 필드가 3개뿐인데도 사용자가 혼란스러운 경우가 있다. 왜일까? 입력 순서가 눈에 잘 안 들어오고, 에러 메시지가 어디에 붙는지 불명확하고, 제출 후 어떤 변화가 일어나는지 예측할 수 없기 때문이다. 즉, 문제는 정보량이 아니라 정보의 조직 방식이다. 같은 내용을 다른 구조로 배치하면, 사용자는 훨씬 적은 노력으로 이해한다.

여기서 중요한 통찰은 이것이다. UI는 장식이 아니라 서술 방식이다. 화면은 제품의 기능을 나열하는 캔버스가 아니라, 사용자가 따라갈 수 있는 이야기의 순서다. 좋은 UI는 사용자가 다음 장면을 예측하게 만든다. 나쁜 UI는 매 장면마다 새로 공부하게 만든다.

이것이 “몇 시간 만에 읽을 수 있는 책”이나 “실용적인 UI” 같은 학습 자료들이 사랑받는 이유다. 이들은 미적 취향을 주입하기보다, 반복 가능한 판단 기준을 준다. 어떤 글자 크기가 읽히는지, 어떤 간격이 관계를 드러내는지, 어떤 상태 전환이 자연스러운지. 결국 UI는 감각의 영역처럼 보이지만, 실제로는 매우 구조적인 훈련의 영역이다.

API 통합이 어려운 이유도 결국 같은 문제다

3rd party API를 붙이는 일은 겉으로 보면 기술적인 연결 작업이다. 하지만 실전에서는 대부분 타인의 설계를 내 시스템의 언어로 번역하는 일이다. 외부 API는 내가 통제할 수 없는 속도, 네이밍, 에러 모델, 인증 방식, 데이터 구조를 가진다. 이때 직접 곳곳에 API 호출을 흩뿌리면 코드베이스 전체가 외부 계약에 종속된다.

포트와 어댑터 패턴이 유용한 이유는 단지 “좋은 아키텍처”라서가 아니다. 그것은 외부 세계의 불안정성을 한 곳에 가두고, 내부에는 일관된 의미를 유지하게 해주기 때문이다. 다시 말해, 외부 시스템의 언어와 내부 시스템의 언어를 분리하는 번역 계층을 만든다.

이것은 UI에서 디자인 시스템을 만드는 일과 매우 닮아 있다. 개별 화면마다 버튼 색과 에러 표현을 다르게 하면 사용자는 매번 새 규칙을 배우게 된다. 반대로 일관된 컴포넌트 규칙을 두면 사용자는 한 번 배운 의미를 여러 곳에 재사용한다. API도 똑같다. 외부 공급자의 응답 형식을 서비스 곳곳에 직접 퍼뜨리면, 변화 하나가 시스템 전체에 전염된다. 그러나 어댑터를 통해 우리 서비스의 도메인 언어로 재해석하면, 외부 변경을 흡수하는 완충층이 생긴다.

예를 들어 결제 API를 붙인다고 하자. 외부 응답에는 approved, requires_action, pending_review, declined 같은 상태가 있을 수 있다. 이 상태를 그대로 비즈니스 로직에 배치하면, 로직은 결제 공급자의 세계관에 종속된다. 하지만 내부에서 PaymentOutcome.Success, PaymentOutcome.NeedsUserAction, PaymentOutcome.Review, PaymentOutcome.Failed처럼 정리하면, 서비스는 결제사의 표현이 아니라 우리 제품의 경험을 기준으로 움직일 수 있다.

좋은 어댑터는 단순히 데이터를 변환하지 않는다. 의미를 변환한다.

이 차이가 중요하다. 포맷 변환은 기계적이다. 의미 변환은 설계다. UI에서도 같은 일이 일어난다. 픽셀을 맞추는 것은 형식의 문제지만, 사용자가 “이 화면에서 무엇을 해야 하는지” 즉시 알게 만드는 것은 의미의 문제다.

인간과 시스템은 같은 방식으로 혼란을 싫어한다

UI와 API를 함께 생각하면 한 가지 더 깊은 패턴이 보인다. 좋은 인터페이스는 예측 가능성을 높인다. 사람은 예측 가능한 화면을 신뢰하고, 시스템은 예측 가능한 계약을 신뢰한다. 인간은 다음 클릭을, 시스템은 다음 응답을 예상할 수 있어야 한다.

이 예측 가능성은 단순히 친절함의 문제가 아니다. 그것은 확장성의 조건이다. 화면의 상호작용이 예측 가능해야 사용자는 기능을 학습할 수 있고, API의 계약이 예측 가능해야 개발자는 통합을 확장할 수 있다. 불확실성이 커질수록 팀은 문서와 회의와 예외 처리에 더 많은 시간을 쏟는다. 결국 제품이 커질수록 인터페이스의 질은 생산성의 질이 된다.

여기서 흥미로운 비유를 하나 들어보자. 좋은 도시를 생각해보자. 도시는 모든 건물을 하나의 규칙으로 통일하지 않는다. 그러나 길, 표지판, 구역, 신호 체계는 일관되게 설계한다. 그래서 처음 온 사람도 어느 정도 움직일 수 있다. UI도 같고 API도 같다. 모든 상황을 동일하게 만들 필요는 없지만, 규칙이 어디까지 적용되는지 분명해야 한다.

이 관점에서 “디자인”은 미학적 장식이 아니라 인지 인프라다. “아키텍처”도 추상적 구조가 아니라 협업 인프라다. 둘 다 복잡한 세계를 다루기 쉽게 만드는 공공재에 가깝다. 팀이 커질수록 이 공공재의 중요성은 더 커진다. 개인의 기억으로 유지되는 규칙은 금방 무너지고, 제품의 형태가 암묵지에 기대기 시작하면 온보딩 비용은 폭증한다.

좋은 UI와 좋은 API는 공통적으로 이런 질문을 던진다.

무엇이 기본값인가?
무엇이 예외인가?
무엇이 사용자나 호출자에게 숨겨져야 하는가?
무엇은 반드시 드러나야 하는가?
한 번 배운 규칙을 어디까지 재사용할 수 있는가?

이 질문들에 답하는 과정이 곧 설계다. 그리고 이 질문들은 버튼과 엔드포인트 모두에 똑같이 적용된다.

실전에서 써먹는 통합 프레임워크: 표면은 다르지만 원리는 하나다

이제 둘을 하나의 프레임워크로 묶어보자. 훌륭한 인터페이스 설계는 다음 4단계를 거친다.

1. 내부 복잡성을 인정한다

좋은 설계는 복잡성을 부정하지 않는다. 오히려 어디에 복잡성이 존재하는지 정확히 본다. UI에서는 상태, 예외, 전환, 우선순위가 복잡성의 핵심이고, API에서는 인증, 실패 모드, 데이터 정합성, 버전 변화가 복잡성의 핵심이다. 복잡성을 숨기려 하지 말고, 어떤 복잡성은 내부에 가두고 어떤 복잡성은 외부에 드러낼지 결정해야 한다.

2. 번역 계층을 만든다

UI에서는 디자인 시스템, 컴포넌트, 스타일 토큰이 번역 계층 역할을 한다. API에서는 포트와 어댑터, 서비스 레이어, DTO 변환이 번역 계층 역할을 한다. 핵심은 외부 언어를 내부 언어로, 내부 언어를 외부 언어로 바꾸는 지점을 분리하는 것이다. 이 지점이 없으면 시스템은 즉시 취약해진다.

3. 예측 가능성을 우선한다

사용자는 놀라움보다 일관성을 좋아한다. 통합하는 개발자도 마찬가지다. UI에서 같은 문제는 같은 방식으로 보이게 해야 하고, API에서 같은 종류의 에러는 같은 형태로 반환해야 한다. 예측 가능성은 평범해 보이지만, 대규모 제품에서는 최고의 생산성 장치다.

4. 의미를 보존한다

형식만 맞추면 충분하지 않다. UI의 빨간색은 단지 색상이 아니라 경고의 의미다. API의 404는 단지 숫자가 아니라 리소스 부재의 의미다. 설계는 항상 형식보다 의미를 먼저 다뤄야 한다. 의미가 보존되면 시스템은 바뀌어도 경험은 유지된다.

이 프레임워크를 한 문장으로 압축하면 이렇다.

인터페이스 설계의 목표는 내부를 단순화하는 것이 아니라, 외부가 받아들일 수 있는 형태로 복잡성을 재배열하는 것이다.

이 문장을 UI에 적용하면 “보는 사람의 인지 비용을 줄여라”가 된다. API에 적용하면 “연결하는 시스템의 통합 비용을 줄여라”가 된다. 같은 문장, 같은 철학, 다른 대상일 뿐이다.

Key Takeaways

UI와 API는 둘 다 인터페이스다. 하나는 인간을 위한 인터페이스이고, 다른 하나는 시스템을 위한 인터페이스다. 핵심은 미감이나 연결 그 자체가 아니라, 복잡성을 다루기 쉬운 형태로 바꾸는 일이다.
좋은 설계는 예측 가능성을 만든다. 사용자는 화면에서 다음 행동을 예측하고, 개발자는 API에서 다음 결과를 예측해야 한다. 일관성은 장식이 아니라 생산성의 기반이다.
번역 계층을 분리하라. UI에서는 컴포넌트와 디자인 시스템을, API에서는 어댑터와 포트 구조를 사용해 외부 변화가 내부를 오염시키지 않게 하라.
의미를 먼저 설계하라. 색, 라벨, 상태 코드, 에러 메시지는 모두 의미를 전달하는 도구다. 형식을 맞추는 것보다 의미를 보존하는 것이 더 중요하다.
한 번 배운 규칙을 재사용 가능하게 만들어라. 사용자가 화면을 학습하듯, 개발자도 통합 방식을 학습한다. 규칙이 재사용될수록 제품은 더 빨리 커진다.

마무리: 우리는 기능이 아니라 경계면을 기억한다

사람들은 종종 제품의 우수성을 기능 목록으로 기억하지만, 실제로 오래 남는 것은 만나는 방식이다. 첫 화면이 얼마나 명확했는지, 에러가 얼마나 이해하기 쉬웠는지, 외부 API가 얼마나 안정적으로 흡수되었는지, 시스템이 얼마나 예측 가능했는지. 결국 제품의 품질은 내부 엔진보다 외부와 접촉하는 표면에서 체감된다.

이 때문에 UI 디자인과 API 통합은 서로 다른 전문 영역처럼 보여도, 더 깊은 수준에서는 같은 문제를 푼다. 둘 다 혼란을 질서로 바꾸고, 복잡성을 신뢰 가능한 형태로 압축하며, 사용자가 세계를 이해하는 비용을 줄인다. 좋은 제품은 내부가 단순한 제품이 아니라, 외부에 단순하게 드러나는 제품이다.

그러니 다음에 화면을 다듬거나 외부 서비스를 붙일 때, 이렇게 물어보자. 이것은 예쁜가, 잘 연결되는가를 넘어서, 이 경계면이 복잡성을 이해 가능한 언어로 번역하고 있는가? 이 질문을 습관으로 만들면, 디자인과 아키텍처는 더 이상 별개의 실무가 아니다. 그것들은 같은 기술의 두 얼굴이 된다.