2026년 9월 6일 일요일

[바이브 코딩] fawazahmed0 Currency API - 키 등록 없이 200+ 통화 환율로 만드는 환율 계산기



무료 환율 API 한 장으로 만드는 환율 계산기 — fawazahmed0 Currency API 완전 정복

🔑 API 키 발급도, 신용카드 등록도 필요 없는 무료 환율 API입니다. URL 한 줄이면 달러·유로·엔은 물론 비트코인과 금(온스)까지 200여 개 통화의 매일 갱신되는 환율을 JSON 한 장으로 받아올 수 있습니다.

환율 계산기는 수학(비율·비례식)과 사회(국제 경제)를 한 화면에 묶는 최고의 융합 소재입니다. 이 글에는 교실에서 자주 막히는 두 관문까지 미리 해결해 담았습니다 — ① CDN 장애에 흔들리지 않는 폴백 주소, ② 학내망 '외부 호출 0' 원칙에 맞춘 데이터 심기(오프라인) 모드.

📖 한 줄 정의

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

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

1. 3대 핵심 분석 비교표

무엇이 바뀌었나요? / 영역 초보자를 위한 쉬운 설명 이렇게 한번 써보세요!
무료·키 없는 첫 API "회원가입 없이 파일로 팔지 않는 환율 창고." 매일 자동 갱신되고, 달러·유로 같은 실제 화폐 외에 비트코인·금(온스)·은까지 200여 종목이 한 JSON 파일에 담겨 있습니다. 브라우저 주소창에 usd.json 주소를 붙여넣기 → 1달러 기준 전 세계 환율표가 그대로 눈앞에!
URL 구조 주소는 4덩어리 = 창고(cdn.jsdelivr.net) + 상자(@fawazahmed0/currency-api) + 날짜(@latest 또는 @YYYY-MM-DD) + 파일(v1/currencies/코드.json). 날짜를 'latest' 대신 특정 날짜로 바꾸면 그날의 환율로 시간 여행이 가능합니다. usd.min.json처럼 끝에 .min을 붙이면 줄바꿈·띄어쓰기 없는 압축판이라 다운로드가 더 빠릅니다.
데이터 모양(해부) usd.json을 열면 딱 두 칸: 'date'(기준 날짜)와 'usd'(1달러가 각 통화로 얼마인지 목록). 예) krw: 1355.65 = "1달러가 1,355.65원". 자바스크립트로 json.usd.krw를 꺼내 "1달러 = ○○○원" 화면에 띄워보기.
학내망 배포 대응 학교 네트워크 원칙상 웹앱은 외부 호출 금지. 해결법은 데이터 심기: 미리 내려받은 환율 JSON을 HTML 파일 안의 상수로 심으면, 인터넷 없이도 돌아가는 오프라인 환율 계산기가 됩니다. 외부 호출 0, 단일 파일 원칙 그대로 지켜집니다. 심기 모드 파일 → 학내망 배포용. fetch 실시간 모드 → 교사 개인 연습·시연용으로 두 벌 운영.
안전장치(폴백) 공식 저장소가 "CDN이 흔들릴 수 있으니 폴백 주소를 코드에 넣어라"고 경고합니다. 같은 데이터가 Cloudflare 페이지에도 복제되어 있어, 첫 주소가 실패하면 두 번째 주소로 자동 재시도하면 됩니다. fetch 첫 주소 → 실패하면 pages.dev 재시도 → 그마저 실패하면 '오프라인 안내' 문구 표시(5줄 코드).

2. 핵심 아키텍처 해설 — 환율 창고는 이렇게 생겼다

① URL 해부: 네 덩어리만 알면 끝

https://cdn.jsdelivr.net/npm/@fawazahmed0/currency-api@latest/v1/currencies/usd.min.json

  • cdn.jsdelivr.net — 파일을 전 세계에 빠르게 나르는 무료 CDN 창고
  • @fawazahmed0/currency-api — npm에 올라온 데이터 패키지 이름(프로젝트 본진 저장소는 exchange-api로 이전했지만, 데이터 배포는 이 패키지 경로로 계속됩니다)
  • @latest 또는 @2026-09-04 — 최신판 또는 날짜 고정판. "작년 이날 환율과 비교하기" 같은 수업 활동은 날짜 고정판으로 구현합니다.
  • /v1/currencies/코드.json — 실제 데이터 파일. 전체 통화 목록(코드·이름 지도)은 /v1/currencies.json 하나로 제공되어, 계산기의 '통화 선택 목록'을 만들 때 그대로 씁니다.

참고: 폴더 주소까지(.../currencies/) 브라우저로 열면 파일 목록 페이지가 보일 뿐이고, 앱이 읽을 것은 파일 주소입니다.

② 데이터 모양: 딱 두 칸

{
  "date": "2026-09-04",
  "usd": {
    "krw": 1355.6508182,
    "eur": 0.86032423,
    "jpy": 156.37984362,
    "btc": 0.000012363144,
    "xau": 0.0002238111
  }
}

모든 값은 "1달러 = 몇"이라는 뜻입니다. 금(xau) 0.0002238111은 "1달러가 금 0.0002238111온스" → 뒤집어 금 1온스 ≈ 4,468달러(약 606만 원). 은(xag), 백금(xpt)도 같은 방식으로 들어 있어 '무게당 가격 비교' 과제 소재로도 훌륭합니다.

③ 교차 환율 공식: usd.json 하나로 전 세계 통화쌍 계산

받을 금액 = 줄 금액 × rates[받을 통화] ÷ rates[줄 통화]. 달러를 거치지 않고도 모든 쌍이 바로 계산됩니다.

예) 10,000원 → 유로: 10,000 × 0.86032 ÷ 1,355.65 = 약 6.34유로 (10,000원은 약 7.38달러)

const CDN1 = "https://cdn.jsdelivr.net/npm/@fawazahmed0/currency-api@latest/v1/currencies/";
const CDN2 = "https://latest.currency-api.pages.dev/v1/currencies/";

async function loadRates(code) {
  let res = await fetch(CDN1 + code + ".min.json");
  if (!res.ok) res = await fetch(CDN2 + code + ".min.json");
  const json = await res.json();
  return json[code];   // 예: rates.krw === 1355.65 (1달러당 원화)
}

④ 이중 안전장치: 폴백 + 데이터 심기

폴백은 위 코드 5번째 줄처럼 첫 주소 실패 시 Cloudflare 주소로 재시도하는 구조입니다. 학내망 배포용은 아예 통신을 지웁니다 — 파일 상단에 오늘 날짜 데이터를 상수로 심기만 하면 됩니다.

const EMBED_DATA = { date: "2026-09-04", usd: { krw: 1355.65, eur: 0.86032, jpy: 156.38 } };
// EMBED_DATA가 채워져 있으면 fetch를 완전히 생략 → 외부 호출 0 모드

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

  1. 프롬프트 복사 — 아래 '제미나이 전용 에러 제로 프롬프트' 전체를 복사해 Gemini에 붙여넣습니다.
  2. 역질문 답변 — Gemini가 코드를 짜기 전에 던지는 질문 3가지(통화 쌍, 데이터 모드, 화면 톤)에 자기 상황을 답변하면 설계가 확정됩니다.
  3. HTML 파일 실행 — 완성 코드를 메모장에 붙여 '환율계산기.html'로 저장 후 더블클릭. 심기 모드라면 그 파일을 그대로 학내망에 배포합니다.

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

[🚨 에러 방지 기본 안전장치]
1. 결과물은 외부 라이브러리·프레임워크·웹폰트 없이 단일 HTML 파일로 완성한다. (환율 데이터 fetch는 유일한 외부 통신 예외)
2. 사운드는 Web Audio API로 직접 합성한다: 환율 변환 성공 시 부드러운 '똑' 소리, 빈 칸·없는 통화 코드 입력 시 '삑' 경고음. 오디오 파일·CDN 사운드 사용 금지.
3. 모바일 터치 대응: 뷰포트 메타 태그 필수, 버튼 최소 44×44px, 입력 필드 font-size 16px 이상, 360px 화면에서 가로 스크롤 금지.
4. 환율 데이터는 아래 두 주소를 순서대로 시도하고, 둘 다 실패하면 화면에 '오프라인: 환율 데이터를 불러올 수 없습니다'를 표시한다.
   1순위 https://cdn.jsdelivr.net/npm/@fawazahmed0/currency-api@latest/v1/currencies/{통화코드}.min.json
   2순위 https://latest.currency-api.pages.dev/v1/currencies/{통화코드}.min.json
5. 파일 상단 EMBED_DATA 상수에 환율 데이터가 심어져 있으면 fetch를 완전히 생략한다(학내망 배포용 외부 호출 0 모드). fetch 성공 시 데이터 기준 날짜(json.date)를 화면 하단에 표시한다.
6. 통화 코드는 대문자로 입력해도 소문자로 자동 변환하고, currencies.json 목록에 없는 코드는 친절한 안내와 함께 '삑' 경고음을 낸다.
7. 결과 표시는 천 단위 콤마 + 소수점 둘째 자리까지. // TODO, /* 생략 */ 같은 미완성 코드는 절대 넣지 말고 끝까지 완성한다.

[❓ 역질문 유도]
코드를 바로 만들지 말고, 아래 3가지를 먼저 나에게 질문한 뒤 내 답변으로 설계를 확정한다.
Q1. 기본 통화 쌍은 무엇인가? (예: 원화 ↔ 달러) 즐겨찾기 통화 3개는 무엇으로 할까?
Q2. 데이터 모드는 무엇으로 할까? (A: 실시간 fetch 모드 / B: 학내망용 데이터 심기 모드)
Q3. 화면 톤은? (큰 숫자 전광판 스타일 / 심플 계산기 스타일)

🎯 에디터 한줄평

API 키 없이 열리는 무료 데이터 창고는 '인생 첫 API'로 삼기 최적입니다. 어제 1,355.65원이던 숫자가 오늘은 조금 다르게 떠오르는 경험 — '인터넷에 살아 움직이는 데이터가 있다'는 사실 하나가 비율·비례식 수학 시간의 태도를 바꿉니다. 학내망 원칙을 '데이터 심기'로 우아하게 넘기는 설계도 마음에 듭니다. 오늘은 계산기, 다음 단계는 '여행 국가별 필요 경비 비교표 앱'으로 확장해보세요.

📚 기술·교육 참고 링크

By 시간: