2026년 9월 6일 일요일

[바이브 코딩] 심기 모드(데이터 임베딩) 완전 정복 - 외부 호출 0으로 API 데이터를 쓰는 기술



외부 호출 0으로 API 데이터를 쓰는 기술 — '심기 모드(데이터 임베딩)' 완전 정복

🌱 수업용 웹앱에서 환율·노벨상 같은 API 데이터를 쓰되, 학생 단말에서 외부 통신이 단 한 번도 일어나지 않게 하는 방법 — 데이터를 미리 받아 HTML 파일 안에 심는 '심기 모드'입니다.

이유는 두 가지입니다. 학생 데이터가 학교 밖으로 나가지 않게(개인정보), 그리고 수업이 외부 서비스의 사정에 끌려다니지 않게(안정성). 실제로 무료 API의 대명사였던 CountAPI는 서비스 종료로 하루아침에 사라졌습니다 — 외부 의존의 리스크는 이론이 아니라 실제 사건입니다.

이 글 하나로 받기 → 뽑기 → 심기 3단계와 '갱신 주기로 모드 고르기' 판단 기준까지 정리됩니다.

📖 한 줄 정의

심기 모드(데이터 임베딩): API 데이터를 미리 받아 HTML 파일 안 상수로 박아두는 방식(앱 실행 중 외부 통신 0).

학내망 원칙: 학교 배포 웹앱은 개인정보 수집·저장·전송 없음(외부 CDN·API 호출 0, 단일 파일) — 학생은 학내망에서 교사 PC 서버에 접속.

1. 3대 핵심 분석 비교표

무엇이 바뀌었나요? / 영역 초보자를 위한 쉬운 설명 이렇게 한번 써보세요!
왜 심는가 웹앱이 실행되는 내내 외부와 통신하면, 학생 단말의 기록이 밖으로 흘러가고(개인정보) 외부 장애에 수업이 끌려갑니다. 심기 모드는 통신 시점을 '제작할 때 단 한 번'으로 옮겨 두 문제를 동시에 끊습니다. 점심시간에 데이터 한 번 받아 심기 → 오후 수업은 인터넷 없이 완결.
두 모드 비교 fetch 실시간 모드는 항상 최신이지만 통신이 있습니다. 심기 모드는 심은 시점의 데이터지만 통신이 0입니다. 학교 배포용은 심기, 교사 개인 연습·시연은 fetch가 기본값입니다. EMBED_DATA 상수 하나로 두 모드를 스위치처럼 전환(아래 3단계 참고).
갱신 주기로 고르기 데이터가 바뀌는 주기가 길수록 심기에 유리합니다. 노벨상 수상자(1년 1회)는 완벽, 환율(매일)은 '심기 + 기준 날짜 표시'로 타협, 학생 입력·답안 같은 실시간 정보는 심기 개념과 무관합니다. 판단 규칙: 바뀌는 주기가 학기보다 길면 무조건 심기.
어떻게 만드나 3단계입니다: ① 받기(브라우저에서 json 내려받기) ② 뽑기(필요한 필드만 골라 용량 줄이기) ③ 심기(EMBED_DATA 상수로 파일 안에 박기). 앱 코드는 상수가 있으면 fetch를 아예 건너뜁니다. 모드 스위치 코드 5줄이면 끝(아래 ③ 참고).
주의점 심은 데이터는 기준 날짜를 화면에 반드시 표시 — 학생이 '오늘 환율'이라 착각하지 않게 합니다. 용량은 슬림화로 줄이고, 학생 개인정보는 애초에 API로 보내는 것이 없으니 수집·전송 모두 0으로 유지됩니다. 화면 하단 '기준 날짜: 2026-09-04' 문구 필수.

2. 핵심 아키텍처 해설 — 심기 3단계

① 받기: 브라우저가 곧 다운로더

API 키도, 프로그램 설치도 필요 없습니다. 브라우저 주소창에 데이터 주소를 넣고 열린 내용을 파일로 저장하면 끝입니다.

  • 환율: usd.min.json (1달러 기준 전 세계 환율, 하루 갱신)
  • 노벨상: laureates?limit=1000 (1901년부터 수상자 전체, 약 3.8MB)

② 뽑기: 필요한 필드만 골라 10분의 1로

전체 JSON을 심을 수도 있지만, 수업에 필요한 필드만 골라내면 파일도 가볍고 코드도 단순해집니다.

const slim = json.laureates.flatMap(function (l) {
  return l.nobelPrizes.map(function (p) {
    return {
      name: (l.knownName || l.orgName).en,          // 사람: knownName, 단체: orgName
      year: p.awardYear,
      category: p.category.en,
      motivation: p.motivation ? p.motivation.en : ""
    };
  });
});

환율 데이터라면 json.date와 필요한 통화 몇 개만 { date, krw, eur }처럼 골라 담으면 충분합니다.

③ 심기: EMBED_DATA 모드 스위치

const CDN1 = "https://cdn.jsdelivr.net/npm/@fawazahmed0/currency-api@latest/v1/currencies/";
const EMBED_DATA = null;   // null이면 실시간(fetch) 모드 — 심기 모드는 여기에 데이터를 붙여넣는다

async function getUsdRates() {
  if (EMBED_DATA) return EMBED_DATA.usd;            // 심기 모드: 통신 0, 즉시 반환
  const res = await fetch(CDN1 + "usd.min.json");   // 실시간 모드: 외부 통신 1회
  const json = await res.json();
  return json.usd;
}

EMBED_DATA가 null이면 실시간 모드, 데이터를 심으면 심기 모드 — 한 파일로 두 세계를 다 살아갑니다. 교사 PC에서 실시간 모드로 시연해보고, 배포 직전에 데이터를 심어 외부 호출 0 파일로 확정하는 흐름이 실무적입니다.

④ 모드 판단 기준: 갱신 주기가 답을 준다

데이터 종류 바뀌는 주기 추천 모드
노벨상 수상자 등 역사 데이터 1년 (10월 발표) 심기 모드 — 완벽
환율 매일 심기 모드 + 기준 날짜 표시(타협), 개인용은 실시간 fetch
학생 입력·답안·기록 실시간 심기 개념과 무관 — 앱 안에서만 처리(외부 전송 자체가 원칙 위반)

3. 초보자를 위한 바이브 코딩 실전 사용 예시

  1. 프롬프트 복사 — 아래 '제미나이 전용 에러 제로 프롬프트' 전체를 복사해 Gemini에 붙여넣습니다.
  2. 역질문 답변 — Gemini가 던지는 질문 3가지(다룰 데이터, 갱신 주기, 화면 톤)에 답하면 모드 추천까지 받아 설계가 확정됩니다.
  3. HTML 파일 실행 — 완성 코드를 메모장에 붙여 .html로 저장 후 더블클릭. EMBED_DATA가 null인 채로 실시간 모드를 시험해보고, 배포 직전 심기 모드로 확정합니다.

제미나이 전용 에러 제로 프롬프트

[🚨 에러 방지 기본 안전장치]
1. 결과물은 외부 라이브러리·프레임워크·웹폰트 없이 단일 HTML 파일로 완성한다. (외부 통신은 EMBED_DATA가 null일 때의 데이터 fetch만 허용)
2. 사운드는 Web Audio API로 직접 합성한다: 데이터 준비 완료 시 부드러운 '똑' 소리, 불러오기 실패 시 '삑' 경고음. 오디오 파일·CDN 사운드 사용 금지.
3. 모바일 터치 대응: 뷰포트 메타 태그 필수, 버튼 최소 44×44px, 입력 필드 font-size 16px 이상, 360px 화면에서 가로 스크롤 금지.
4. 파일 상단에 EMBED_DATA = null 상수를 반드시 두고, 값이 null이면 fetch로 데이터를 받고 값이 있으면 fetch를 완전히 생략한다(학내망 배포용 외부 호출 0 모드).
5. 두 모드 모두 데이터의 기준 날짜를 화면 하단에 표시한다: 심기 모드는 심은 데이터의 date 값, fetch 모드는 받아온 json의 date 값.
6. fetch 실패 시 화면에 '오프라인: 데이터를 불러올 수 없습니다'를 친절히 안내하고 '삑' 경고음을 낸다.
7. // TODO, /* 생략 */ 같은 미완성 코드는 절대 넣지 말고 끝까지 완성한다.

[❓ 역질문 유도]
코드를 바로 만들지 말고, 아래 3가지를 먼저 나에게 질문한 뒤 내 답변으로 설계를 확정한다.
Q1. 어떤 데이터를 다루는 앱인가? (환율 / 노벨상 수상자 / 그 밖의 공개 데이터)
Q2. 데이터의 갱신 주기는? (실시간 / 매일 / 연 1회 — 주기에 맞는 모드를 먼저 추천해 줄 것)
Q3. 화면 톤은? (큰 숫자 전광판 스타일 / 심플 카드 스타일)

🎯 에디터 한줄평

심기 모드는 '외부를 안 쓰는 기술'이 아니라 '외부를 미리 내 것으로 만드는 기술'입니다. 데이터를 한 번 받아 내 파일 안에 심는 순간, 수업은 학교 안에서 완결되고 학생 데이터는 학교 밖으로 한 걸음도 나가지 않습니다. CountAPI처럼 하루아침에 사라진 서비스의 교훈까지 얹으면, 갱신 주기 한 줄만 판단하면 두려울 게 없는 — 교사용 API 입문의 안전벨트입니다.

📚 기술·교육 참고 링크

  • MDN — Fetch API 문서 : 실시간 모드의 데이터 가져오기 기초
  • jsDelivr CDN : 무료 데이터 파일을 내려받는 '받기' 단계의 창고
  • 노벨 공식 Developer Zone : 심기 모드와 가장 잘 맞는 연 1회 갱신 데이터의 예
  • 교육과정 연계: 정보·실과(데이터와 개인정보, 네트워크의 기초), 사회(국제 경제), 영어(원문 데이터 읽기) 단원과 함께 활용
By 시간: