앞 페이지까지에서 우리는 백엔드 골격, 프론트 골격, 공통 API 계약 바닥을 각각 준비했습니다. 이제 이 조각들을 처음으로 같이 붙여 봐야 합니다. 이 단계는 단순히 서버와 프론트를 한 번 켜보는 데서 끝나지 않습니다. 설계가 실제 실행 환경에서 얼마나 일관되게 연결되는지 확인하는 첫 검증 단계입니다.
많은 프로젝트가 이 지점에서 처음으로 현실적인 문제를 만납니다. 개별 앱은 잘 뜨는데 API base URL이 맞지 않거나, 프론트 라우트는 열리는데 헬스체크만 되고 실제 데이터 요청이 실패하거나, 인증 응답 형식이 화면 기대와 다르거나, admin은 열리는데 보호 라우트 구조가 아직 맞지 않는 식입니다. 이 문제들은 이상한 예외가 아니라, 오히려 지금 잡아야 하는 정상적인 초기 통합 이슈입니다.
이번 페이지의 목적은 "이제 뭔가 돌아간다"는 감각으로 넘어가는 것이 아니라, 무엇을 어떤 순서로 띄우고 무엇을 확인해야 다음 장의 카탈로그와 인증 구현으로 안전하게 넘어갈 수 있는지 기준을 세우는 것입니다.
개별 단위에서 잘 되는 것과 전체가 같이 되는 것은 완전히 다른 문제입니다. 이번 프로젝트는 최소한 아래 요소가 동시에 맞아야 합니다.
storefront 실행admin 실행이 여섯 가지가 실제로 한 번에 맞물려야 "이제 기능을 붙일 준비가 됐다"고 말할 수 있습니다. 따라서 이번 단계는 데모용 실행이 아니라, 이후 풀스택 기능 개발의 출발 검증입니다.
이 페이지를 읽고 나면 아래 항목이 정리되어 있어야 합니다.
이번 페이지에서 말하는 통합 실행은 "모든 기능이 완성된 서비스 실행"이 아닙니다. 아직 카탈로그, 인증, 장바구니, 주문 기능은 뒤 장에서 구현됩니다. 여기서의 통합 실행은 아래 정도를 의미합니다.
storefront가 backend를 바라본다admin도 같은 backend를 바라본다즉 골격끼리 서로 인식하고, 이후 기능을 얹을 수 있는지를 확인하는 단계입니다.
전체를 같이 실행할 때는 순서가 중요합니다. 이번 교재에서는 아래 순서가 자연스럽습니다.
storefront 실행admin 실행이 순서가 좋은 이유는 간단합니다. backend가 먼저 떠 있어야 프론트의 API 연결 문제를 바로 분리해서 볼 수 있기 때문입니다. 반대로 프론트를 먼저 띄우면, 화면 문제와 API 연결 문제를 동시에 추적하게 됩니다.
프론트를 붙이기 전에 backend 단독으로 아래 정도를 먼저 확인하는 것이 좋습니다.
GET /health가 200을 준다이 상태가 확인되면 이후 프론트에서 보이는 문제를 "백엔드 자체 부팅 문제"와 분리할 수 있습니다.
storefront를 붙였을 때는 아래 정도가 최소 확인 범위입니다.
중요한 것은 아직 실제 상품 데이터가 없더라도, 화면이 backend와 연결되는 방향은 보여야 한다는 점입니다.
admin도 같은 방식으로 아래 정도를 먼저 봐야 합니다.
이 단계에서는 완전한 운영자 인증이 없어도 괜찮지만, 최소한 "admin은 별도 surface이며 같은 서버를 본다"는 사실은 확인되어야 합니다.
처음 띄웠을 때 눈으로 몇 번 클릭해 보는 것만으로는 충분하지 않습니다. smoke test는 "이제 다음 장으로 넘어가도 될 최소 조건"을 명확히 적어둔 짧은 검증 집합입니다.
이번 교재에서 smoke test는 아래 역할을 합니다.
즉 smoke test는 가벼운 테스트지만, 기준이 없으면 쉽게 빠집니다.
이번 프로젝트의 첫 통합 기준으로는 아래 정도면 충분합니다.
health 응답 확인storefront 첫 화면 렌더링 확인admin 첫 화면 렌더링 확인storefront에서 API 호출용 기본 클라이언트가 에러 없이 초기화되는지 확인admin에서도 같은 backend URL을 보는지 확인이 여섯 가지가 통과하면, 최소한 골격 통합은 됐다고 볼 수 있습니다.
이 단계에서 흔히 발생하는 문제는 대체로 아래 범주에 들어갑니다.
이 문제들은 복잡한 버그가 아니라, 구조가 아직 덜 맞았다는 신호입니다. 따라서 감정적으로 보기보다, 계약과 실행 설정을 다시 대조하는 것이 맞습니다.
첫 통합 단계에서는 모든 것을 완성하려 하면 오히려 범위가 흐려집니다. 따라서 아래 기준으로 나누는 것이 좋습니다.
즉 이번 단계는 "구조와 연결"을 맞추는 장이지, 비즈니스 기능 완성 장이 아닙니다.
짧은 smoke test라도 확인 결과를 남기는 편이 좋습니다. 적어도 아래 정도는 기록할 수 있어야 합니다.
storefront와 admin을 띄웠는가이 기록이 있어야 이후 장에서 문제가 다시 생겼을 때 "원래 골격 통합은 어디까지 됐는가"를 알 수 있습니다.
브라우저 확인은 단순히 화면이 뜨는지만 보는 것이 아닙니다. 최소한 아래를 같이 봐야 합니다.
즉 브라우저는 "시각적 확인 도구"이면서 동시에 "계약 연결 확인 도구"입니다.
이 단계의 성공은 "모든 기능이 동작한다"가 아닙니다. 아래 상태면 충분합니다.
storefront, admin이 모두 뜬다health와 기본 API 연결이 확인된다이 상태가 되면 다음 장부터는 카탈로그와 인증 기능을 구조 위에 얹는 작업으로 넘어갈 수 있습니다.
이번 페이지를 코드와 검증으로 옮기면 아래 정도 결과가 있어야 합니다.
health 확인 결과storefront와 admin의 첫 렌더링 확인이 산출물이 있어야 다음 장의 카탈로그/인증 구현이 "환경 문제 해결"이 아니라 "실제 기능 개발"로 이어집니다.
storefront와 admin이 서로 다른 backend URL을 보는데 놓친다이 여섯 가지 실수는 다음 장에서 기능 개발 속도를 크게 떨어뜨립니다.
이 페이지에서 우리는 백엔드 골격, 프론트 골격, API 계약 바닥을 처음으로 함께 실행하면서 무엇을 어떤 순서로 확인해야 하는지 정리했습니다. 또한 smoke test는 단순 부팅 확인이 아니라, 다음 장으로 넘어갈 수 있는 최소 통합 기준이며, 이 단계에서는 구조와 연결 문제를 우선 잡아야 한다는 점도 확인했습니다.
다음 장에서는 이제 이 통합 바닥 위에서 카탈로그와 인증을 실제 풀스택 기능으로 구현하기 시작합니다.