개요

백엔드 서비스 원칙은 데이터베이스, 파일 저장소, 메시징, 메일, 외부 API 같은 리소스를 애플리케이션에 붙였다 떼는 자원으로 취급하라는 뜻입니다. 코드가 특정 서버나 특정 외부 서비스에 강하게 묶이면 환경 전환과 장애 대응이 어려워집니다.

HandStack은 dbclient, graphclient, repository, logger, function, command, prompter, forwarder, transact 같은 모듈을 통해 백엔드 리소스를 다룹니다. 화면이나 업무 로직이 직접 모든 리소스에 접근하기보다 계약과 모듈을 통해 접근하도록 설계되어 있습니다.

HandStack에서의 백엔드 서비스

HandStack에서 백엔드 서비스는 다음처럼 분류할 수 있습니다.

• 데이터베이스: dbclient를 통한 SQL 실행
• 그래프 데이터베이스: graphclient를 통한 Cypher 실행
• 거래 라우팅: transact를 통한 계약 기반 요청 처리
• 서버 기능: function을 통한 Node.js, C#, Python 기능 실행
• 명령 실행과 Web 요청: command를 통한 계약 기반 CLI 및 URL 호출
• LLM 프롬프트 실행: prompter를 통한 프롬프트 계약 처리
• 세션 유지 프록시: forwarder를 통한 외부 사이트 요청 대행
• 파일 저장소: repository와 모듈별 저장소 경로
• 로그: logger와 파일/콘솔/운영 로그
• 외부 API: 메시징, 메일, 결제, 사내 시스템 등

핵심은 화면이 특정 DB나 API를 직접 알고 있지 않게 만드는 것입니다. 화면은 거래 계약을 호출하고, 계약은 HandStack 모듈의 라우팅 규칙에 따라 실제 서비스를 사용합니다.

신규 개발자가 알아야 할 점

백엔드 서비스를 추가할 때는 다음을 먼저 결정합니다.

• 이 서비스는 어떤 모듈의 책임인가?
• 연결 정보는 어디에 설정할 것인가?
• 장애가 발생하면 사용자에게 어떤 메시지를 줄 것인가?
• 재시도하거나 큐에 넣어야 하는 작업인가?
• 로그에는 어떤 식별자를 남겨야 추적 가능한가?

서비스 연결은 가능하면 설정으로 교체 가능해야 합니다. 개발 환경에서는 로컬 DB를 쓰고, 운영 환경에서는 운영 DB를 쓰더라도 코드는 같아야 합니다.

마치며

HandStack에서 백엔드 서비스는 모듈과 계약 뒤에 숨겨진 교체 가능한 리소스입니다. 신규 개발자는 외부 서비스를 바로 호출하기보다 HandStack의 모듈 경계와 설정 방식을 먼저 확인해야 합니다.