goldprice.dev가 금 가격을 현지 통화로 책정하는 방법

goldprice.dev와 exchangerate.dev는 같은 회사가 운영하는 자매 제품입니다. 프로덕션에서 goldprice.dev는 금속 가격 계약을 책임지고, exchangerate.dev는 지원되는 변동환율 통화에 대한 FX 요소를 공급합니다. 이 경계는 중요합니다. 현지 통화 기준 금 가격에는 두 개의 시장 관측값이 포함되며, 한쪽이 신선하다고 해서 다른 한쪽도 신선해지는 것은 아닙니다.

프로덕션 경계

goldprice.dev는 USD 금속 관측값에서 시작합니다. exchangerate.dev는 지원되는 변동환율 통화에 대해 그에 대응하는 USD-현지통화 FX 관측값을 제공합니다. 이후 goldprice.dev는 단위, 지원 심볼, 검증, 최종 응답을 포함한 금속 특화 변환 계약을 책임집니다.

이는 공개된 자매 제품 간 연동이지, 독립적인 고객의 보증이 아닙니다. 이 사례 연구로서의 가치는 운영적인 데이터입니다. FX API가 실제 프로덕션 데이터 요소를 공급하고, 이를 소비하는 제품이 자신의 도메인에 대한 책임을 그대로 유지한다는 점입니다.

변환 공식

금은 보통 트로이온스당 USD로 고시됩니다. 현지 통화로 표시하려면 대개 그램당 통화 금액이 필요합니다. 먼저 무게를 변환한 다음 USD 환율을 적용하세요.

const GRAMS_PER_TROY_OZ = 31.1035;

function localGoldPerGram(usdPerTroyOz, usdToLocalRate) {
  return (usdPerTroyOz / GRAMS_PER_TROY_OZ) * usdToLocalRate;
}

무게 상수는 고정되어 있습니다. 하지만 두 시장 입력값은 그렇지 않습니다. 금 시세와 FX 환율 모두 각자의 관측 시각과 신선도 규칙을 갖고 있습니다.

한 번의 호출로 끝나는 프로덕션 경로

호출자 입장에서 프로덕션 경계는 goldprice.dev `/v1/convert`입니다. 이 엔드포인트는 금속 요소와 FX 요소를 하나의 금속 인식 엔드포인트 뒤로 결합하며, API 키가 필요하지 않습니다. 아래 예제는 금 1그램의 인도네시아 루피아 가치를 요청합니다.

const params = new URLSearchParams({
  from: "XAU",
  to: "IDR",
  amount: "1",
  unit: "gram",
});

const response = await fetch(
  `https://api.goldprice.dev/v1/convert?${params}`,
);

if (!response.ok) {
  throw new Error(`goldprice.dev returned ${response.status}`);
}

const conversion = await response.json();
console.log(conversion.result, conversion.to, conversion.timestamp);

이 경로는 호출자 계약을 작게 유지합니다. 요청 하나, 금액 하나, 금속 단위 하나, 대상 통화 하나입니다. 단일 timestamp는 두 시장 요소를 독립적으로 증명해 주지는 않으므로, FX 신선도를 감사해야 하는 소비자는 아래의 2요소 경로를 사용해야 합니다.

감사 가능한 2요소 연동

각 출처의 타임스탬프를 보존하거나, 입력값을 독립적으로 캐시하거나, 어느 요소가 오래됐는지 설명해야 할 때는 두 API를 모두 호출하세요. goldprice.dev spot은 트로이온스당 USD 금 가격을 제공하고, exchangerate.dev는 USD-현지통화 환율을 제공합니다.

const GRAMS_PER_TROY_OZ = 31.1035;

async function getGoldInCurrencies(currencies) {
  const symbols = currencies.join(",");
  const [spotResponse, fxResponse] = await Promise.all([
    fetch("https://api.goldprice.dev/v1/spot/XAU-USD-SPOT"),
    fetch(`https://api.exchangerate.dev/v1/latest/USD?symbols=${symbols}`),
  ]);

  if (!spotResponse.ok || !fxResponse.ok) {
    throw new Error("A market-data request failed");
  }

  const spot = await spotResponse.json();
  const fx = await fxResponse.json();
  const usdPerGram = Number(spot.price) / GRAMS_PER_TROY_OZ;

  return {
    goldComputedAt: spot.computed_at,
    fxDataUpdatedAt: fx.data_updated_at,
    fxResponseTimestamp: fx.timestamp,
    fxSource: fx.source,
    fxMarketSession: fx.market_session,
    prices: Object.fromEntries(
      currencies.map((currency) => [
        currency,
        usdPerGram * Number(fx.rates[currency]),
      ]),
    ),
  };
}

const result = await getGoldInCurrencies(["EUR", "IDR", "JPY"]);

서비스가 분리된 상태를 유지하는 이유

이 연동이 exchangerate.dev를 금 가격 책정 엔진 전체로 만들지는 않습니다. exchangerate.dev는 여전히 FX 계층으로 남습니다. 이 경계를 명시적으로 유지하면 통화 신선도, 금속 신선도, 제품별 변환 규칙이 하나의 모호한 값으로 뭉개지는 것을 막을 수 있습니다.

• goldprice.dev는 호출자가 공통 경로를 직접 조립하게 하지 않으면서도 작고 금속에 특화된 인터페이스를 노출할 수 있습니다.
• exchangerate.dev는 금속 도메인 밖에서도 유용한 범용 FX 계약을 유지합니다.
• 감사에 민감한 소비자는 두 관측값을 각각 독립적으로 가져와 저장할 수 있습니다.
• 각 서비스는 자신의 시장 데이터 용어로 장애와 신선도를 보고할 수 있습니다.

오래되거나 누락된 요소를 명시적으로 처리하기

입력값 중 하나라도 누락되었거나, 0이거나, 숫자가 아니거나, 제품이 허용하는 신선도 범위를 벗어났다면 결합된 가격은 그대로 살아남아서는 안 됩니다. 마지막 유효한 값을 유지하려면 인터페이스가 원래의 관측 시각을 함께 표시할 때만 그렇게 하세요.

• 연산을 수행하기 전에 두 HTTP 응답을 모두 확인하세요.
• 유한하지 않거나 양수가 아닌 가격과 환율은 거부하세요.
• 금과 FX에 대해 서로 다른 신선도 임계값을 설정하세요.
• market_session: weekend는 이월된 환율이 최신이라는 증거가 아니라 맥락 정보로 취급하세요.
• 변환 오류와 함께 통화쌍과 두 관측 시각을 모두 로그로 남기세요.

계산이 아니라 표시 단계에서 반올림하기

곱셈 전 과정에서 전체 정밀도를 유지하고, 최종 소수점 자릿수는 표시 로케일이 결정하도록 두세요. Intl.NumberFormat은 값 자체를 바꾸지 않으면서 통화 기호와 자릿수 구분을 처리합니다.

function formatPrice(amount, currency, locale) {
  return new Intl.NumberFormat(locale, {
    style: "currency",
    currency,
  }).format(amount);
}

console.log(formatPrice(result.prices.IDR, "IDR", "id-ID"));
console.log(formatPrice(result.prices.JPY, "JPY", "ja-JP"));

결과를 인디케이티브 값으로 취급하기

계산된 시장 가치는 코인이나 바의 소매 가격이 아닙니다. 딜러 프리미엄, 세금, 가공비, 결제 수수료, 체결 가능한 FX 스프레드는 이 공식 밖에 있습니다. 애플리케이션이 실제 딜러 견적과 그 상업적 조건을 더하지 않는 한, 결과값은 인디케이티브로 표시하세요.

이 사례 연구가 증명하는 것

goldprice.dev는 exchangerate.dev가 프로덕션 가격 책정 워크플로의 FX 요소를 공급할 수 있다는 1자 증거입니다. 독립적인 사회적 증거는 아닙니다. 유용한 증거는 더 좁고 재현 가능합니다. 개발자는 동일한 공개 제품을 호출하고, 두 관측 시각을 보존하고, 연산을 직접 검증할 수 있습니다.