대형 언어 모델 활용 인터페이스 코드 및 문서 작성
이전 강의에서는 Figma 등의 도구를 사용해 UI 디자인 시안을 완성하고, AI를 활용해 프론트엔드 정적 페이지를 빠르게 생성하며, Supabase를 이용해 데이터베이스를 구축하고 기본적인 사용자 인증을 구현하는 방법을 배웠습니다. 이제 자연스럽게 떠오르는 질문이 있습니다: 프론트엔드 페이지에서 역동적인 버튼을 클릭하면, 데이터는 어떻게 소리 없이 Supabase에 저장되는 걸까요? 더 복잡한 비즈니스 로직(예: 동시 결제, 예약 푸시, 민감 데이터 처리)을 실행해야 할 때, 프론트엔드에서 직접 데이터베이스에 연결하는 것이 안전할까요?
이것이 현대 웹 개발 아키텍처에서 매우 중요한 역할을 하는 백엔드 API 인터페이스로 이어집니다.
과거처럼 수백~수천 줄의 백엔드 라우팅, 컨트롤러, 매개변수 검증 로직을 수동으로 작성하는 대신, 이제는 대형 언어 모델의 강력한 코드 생성 능력을 활용해 복잡한 기반 코드를 AI가 작성하도록 할 수 있습니다. 이번 강의에서는 "AI가 작성한 코드가 겉도는" 문제에서 벗어나, 실제 비즈니스 시나리오를 바탕으로 고품질 프롬프트(Prompt)를 통해 대형 언어 모델이 견고하고 업계 표준에 부합하는 Node.js 백엔드 인터페이스를 작성하도록 안내하고, 인터페이스 문서와 테스트 케이스를 자동으로 생성하는 방법을 보여드리겠습니다.
💡 사전 지식
이번 장을 학습하기 전에 다음 내용을 먼저 확인하는 것을 권장합니다:
- 데이터베이스에서 Supabase까지 - 데이터베이스와 데이터 모델의 개념 이해
- Git과 GitHub 워크플로우 - 프로젝트 개발에서 버전 관리 방법 숙지
- 터미널/명령어 줄이란 - 프로젝트 초기화와 실행에 필요한 기본 명령어
배울 내용
- API 인터페이스란: 프론트엔드와 백엔드 통신의 다리와 RESTful 설계 규범 이해
- 대형 언어 모델로 서비스 구축하기: 구조화된 Prompt를 통해 AI가 Node.js + Express 기반 공정을 구축하도록 하는 방법
- 인터페이스 로직 개발: 대형 언어 모델이 엄격한 비즈니스 검증과 Supabase 데이터베이스 연동이 포함된 CRUD(생성, 조회, 수정, 삭제) 인터페이스를 생성하도록 안내
- 자동화된 인터페이스 문서: 대형 언어 모델이 코드를 기반으로 팀 협업에 필수적인 OpenAPI/Swagger 문서를 역으로 생성
- 테스트 및 통합 디버깅: 대형 언어 모델을 활용해 Postman 테스트 컬렉션과 Jest 단위 테스트 케이스를 생성하여 코드 품질 보장
1. 왜 API 인터페이스가 필요한가?
전통적인 이해에서 프론트엔드는 "보이는 부분", 데이터베이스는 "데이터를 저장하는 창고"입니다. 하지만 그 사이에 조정자가 없습니다. 전체 애플리케이션을 하나의 레스토랑에 비유해 보겠습니다:
- 프론트엔드(클라이언트) 는 레스토랑의 메뉴와 주문 테이블로, 손님이 여기서 메뉴를 보고 요구사항을 제시합니다.
- 데이터베이스(Supabase 등) 는 레스토랑의 주방 창고로, 모든 식재료와 장부가 보관됩니다.
- 백엔드 API 인터페이스 는 레스토랑의 종업원입니다. 손님은 직접 주방에 들어가 식재료를 꺼낼 수 없습니다(혼란스럽고 보안 문제가 발생하기 쉬움). 대신 "주문 요청"(HTTP Request)을 종업원에게 전달합니다. 종업원은 확인(매개변수 검증, 권한 인증)한 후 주방에서 해당 항목을 가져와, "완성된 요리"(HTTP Response, 보통 JSON 형식의 데이터)를 손님에게 서빙합니다.
API 인터페이스를 통해 명확한 프론트엔드-백엔드 분리를 실현합니다: 프론트엔드는 페이지 렌더링에만 집중하고, 백엔드는 비즈니스 로직, 데이터 처리, 보안 방어에만 집중합니다.
2. 프로젝트 아키텍처 설계 및 초기화
구조가 명확한 프로젝트 골격은 대형 언어 모델이 좋은 코드를 작성하기 위한 전제 조건입니다. AI에게 코드를 작성하게 하기 전에, 프로젝트 구조에 대한 기본적인 이해가 있어야 합니다.
2.1 일반적인 API 프로젝트 구조
대형 언어 모델을 사용해 코드를 생성하더라도, 모든 코드를 하나의 server.js 파일에 넣어서는 안 됩니다. 유지보수가 쉬운 Node.js 백엔드 아키텍처는 일반적으로 다음과 같습니다:
my-api-project/
├── .env # 민감한 환경 변수(예: API Keys, 데이터베이스 연결 문자열)
├── server.js # 프로젝트 진입점(서버 시작, 전역 미들웨어 등록)
├── package.json # 의존성 관리 파일
├── src/
│ ├── routes/ # 라우팅 계층: URL 경로 및 요청 메서드 정의
│ ├── controllers/ # 컨트롤러 계층: 비즈니스 요청 매개변수 처리, 서비스 호출 및 응답 반환
│ ├── services/ # 서비스 계층: 데이터베이스 상호작용 및 핵심 비즈니스 로직 캡슐화
│ └── middlewares/ # 미들웨어: 로그인 인증, 전역 오류 캡처
└── docs/ # API 문서 저장 디렉토리2.2 AI를 활용한 프로젝트 초기화
직접 npm init 하고 의존성을 하나씩 설치하는 대신, 위의 규격을 Prompt 형태로 대형 언어 모델에 전달하는 것이 더 효율적입니다:
🗣️ 대형 언어 모델에 대한 프롬프트(Prompt 예시): "Node.js 백엔드 프로젝트를 구축해 줘. Supabase 데이터베이스에 연결할 수 있어야 하고, 구조가 명확해야 하며, 향후 유지보수가 편해야 해."
AI가 반환한 코드를 실행하면 localhost:3000에서 기업급 백엔드 애플리케이션의 초기 형태를 얻을 수 있습니다.
3. 핵심 실전: 대형 언어 모델 활용 인터페이스 개발
이번 장의 가장 핵심적인 부분입니다. 대형 언어 모델이 작성한 코드는 종종 "논리적 허점"이나 "겉만 번지르르한" 문제가 있는데, 이는 개발자가 제공한 컨텍스트가 불충분하기 때문입니다. 대형 언어 모델은 복잡한 요구사항을 두려워하지 않지만, 모호한 요구사항을 가장 두려워합니다.
데이터베이스 장에서 언급한 menu_items(메뉴 테이블)의 생성 인터페이스를 예로, 고품질 Prompt를 작성하는 방법을 살펴보겠습니다.
3.1 대형 언어 모델에 완전한 컨텍스트 제공
AI에게 인터페이스 작성을 요청하기 전에 반드시 데이터베이스 필드 정의(Schema) 와 구체적인 제약 조건을 제공해야 합니다.
🗣️ 고품질 프롬프트(Prompt) 템플릿: "메뉴 추가 인터페이스를 작성해 줘. 메뉴에는 상품명, 가격, 분류(버거, 사이드, 음료), 판매 여부 정보가 포함돼. 상품명과 가격은 필수 항목이고, 가격은 음수일 수 없어. 사용자 입력이 올바르지 않을 때는 오류 메시지를 표시해야 해."
3.2 대형 언어 모델이 생성한 코드 검토
대형 언어 모델이 생성한 코드는 일반적으로 다음과 같이 명확하게 역할이 분리되어 있습니다:
// services/menuService.js
const { createClient } = require('@supabase/supabase-js');
const supabase = createClient(process.env.SUPABASE_URL, process.env.SUPABASE_KEY);
exports.createMenuItem = async (menuData) => {
// Supabase SDK를 호출하여 데이터를 테이블에 삽입
const { data, error } = await supabase
.from('menu_items')
.insert([menuData])
.select();
if (error) throw new Error(`데이터베이스 삽입 실패: ${error.message}`);
return data[0];
};이 방식으로 생성된 코드는 구조가 합리적일 뿐만 아니라, Supabase 초기화, 오류 캡처, 예외 처리까지 고려되어 있어, 단순히 "추가 인터페이스를 작성해 줘"라고 요청해서 얻는 스파게티 코드(Spaghetti Code)와는 비교가 되지 않습니다.
4. 양손 해방: 자동 인터페이스 문서 생성
개발팀에게 문서 없는 API는 블랙박스와 같습니다. 프론트엔드 엔지니어는 어떤 매개변수를 전달해야 하는지, 어떤 구조가 반환되는지 추측할 수 없습니다. 업계에서 가장 널리 사용되는 API 설명 규격은 OpenAPI(이전 명칭 Swagger) 입니다.
과거에는 YAML이나 JSON 형식의 Swagger 문서를 수동으로 작성하는 것이 매우 고통스럽고 오류가 발생하기 쉬웠습니다. 이제 이것은 대형 언어 모델이 가장 잘하는 분야가 되었습니다.
방금 작성한 routes와 controllers 코드를 선택한 후 대형 언어 모델에 전달하면 됩니다:
🗣️ 문서 생성 프롬프트: "위 코드를 기반으로 인터페이스 문서를 생성해 줘. 각 매개변수의 의미와 반환 데이터를 명확히 작성해서 프론트엔드 동료가 연동하기 편하도록 해줘."
이 과정에서 AI에게 필드 설명(Description)과 Mock 데이터(예: price_cents: 1200는 12달러를 의미)까지 보완해 달라고 요청할 수 있어, 소통 비용을 크게 줄일 수 있습니다.
5. 안전장치: 테스트 코드 및 Postman 컬렉션 생성
코드 작성과 문서 생성이 끝났다면, 마지막 단계는 코드가 실제로 정상 작동하는지 확인하는 것입니다.
5.1 Postman / Apifox 테스트 설정 생성
인터페이스 개발에서는 일반적으로 Postman과 같은 시각화 도구를 사용하여 프론트엔드의 HTTP 요청을 시뮬레이션합니다. 대형 언어 모델을 사용하지 않는다면 URL을 수동으로 입력하고, Header(요청 헤더)를 하나씩 추가하며, JSON 요청 본문을 조합해야 합니다.
AI에게 다음과 같이 지시만 하면 됩니다:
"이 인터페이스 문서를 Postman에서 가져올 수 있는 형식으로 변환해 줘. 정상 요청과 오류 요청의 예시를 포함해 줘."
JSON 텍스트를 받아 menu_api.json으로 저장한 후 Postman에 드래그하면, 즉시 사용 가능한 테스트 클릭 패널을 얻을 수 있습니다.
5.2 자동화된 단위 테스트 작성
더 엄격한 엔지니어링 품질을 추구한다면, 대형 언어 모델이 Jest 등의 테스트 프레임워크를 사용해 단위 테스트(Unit Tests)를 작성하도록 하여, 핵심 비즈니스 로직에 대한 경계값 테스트(예: 음수 가격을 전달했을 때 데이터베이스 계층의 검증이 작동하는지)를 수행할 수 있습니다.
6. 백엔드 인터페이스 필수 모범 사례
AI의 지원이 있더라도, 시스템 전체의 "관문 담당자"로서 다음 핵심 원칙을 이해하고 검토해야 합니다:
- RESTful 규격의 경로 명명:
- 좋은 설계:
GET /api/users(사용자 목록 조회),POST /api/users(사용자 생성). URL은 "리소스"를 나타내는 명사여야 합니다. - 나쁜 설계:
POST /api/getUser또는POST /api/createUser. 동사는 HTTP Method(GET/POST/PUT/DELETE)로 표현해야 합니다.
- 좋은 설계:
- 표준 HTTP 상태 코드:
- 200/201: 요청 성공 / 리소스 생성 성공
- 400: Bad Request, 프론트엔드 매개변수 형식 오류 또는 필수 항목 누락
- 401/403: Unauthorized / Forbidden, 사용자 미로그인 또는 권한 없음
- 404: Not Found, 리소스가 존재하지 않음
- 500: Server Error, 백엔드 코드 오류 또는 데이터베이스 장애. 오류 호출 스택을 프론트엔드에 직접 노출하지 마세요(보안 위험 있음)
- 사용자 입력을 절대 신뢰하지 마세요: 프론트엔드의 입력은 위조될 수 있으므로, 모든 핵심 매개변수 검증은 백엔드 인터페이스에서 다시 한번 수행해야 합니다.
7. 요약
이번 장의 학습을 통해 여러분은 개발 관점의 진정한 전환을 이루었습니다: 더 이상 문법과 구두점에 갇힌 "타이피스트"가 아니라, 시스템 설계자이자 아키텍처 지휘관으로 성장했습니다. 이제 다음을 습득했습니다:
- API 인터페이스와 프론트엔드-백엔드 분리의 핵심 시스템 사고
- 컨텍스트 제공과 계층 구조 개념을 통해 대형 언어 모델이 생성하는 서버 측 코드의 품질을 크게 향상시키는 방법
- 번거로운 문서 작성과 테스트 케이스 구축을 AI가 잘하는 자동화 작업으로 전환하는 방법
- 이전에 학습한 Supabase 지식과 결합하여, 클라이언트 요청부터 기본 데이터베이스 업데이트까지의 완전한 데이터 흐름을 구축
💡 다음 단계
데이터 흐름과 백엔드 서비스가 모두 준비되었지만, 현재는 로컬 컴퓨터에서만 실행됩니다. 다음 장에서는 이 서비스를 공개 네트워크 서버에 배포(Deploy) 하여, 전 세계 사용자가 여러분의 제품에 접근할 수 있도록 하는 방법을 배우겠습니다.