병렬 멀티소스 호출
여러 API를 한 번에 호출해 하나의 응답으로 합치는 Pro 기능의 구조와 파라미터 전달 방식.
화면 하나를 그리는 데 API 두세 개가 필요한 경우가 많습니다. 날씨와 미세먼지를 함께 보여주거나, 정류장 정보와 도착 예정을 같이 띄우는 식입니다. 멀티소스 엔드포인트는 이런 호출을 하나의 slug로 묶어 병렬로 처리합니다.
무엇이 달라지는가
소스를 여러 개 붙이면 fetch() 한 번이 여러 API를 동시에 부르고, 결과를 소스 라벨로 구분해 하나의 객체로 돌려줍니다.
const data = await cook.fetch('dashboard', {
weather: { city: '서울' },
air: { sidoName: '서울' },
});
{
"weather": { "temperature": 23 },
"air": { "pm10": 45 },
"_meta": { "partial": false, "errors": [] }
}
호출은 순차가 아니라 병렬입니다. 소스가 세 개여도 가장 느린 하나만큼만 기다립니다.
파라미터는 라벨로 감쌉니다
단일 소스는 파라미터를 평평하게 넘기지만, 멀티소스는 어느 소스로 보낼지 라벨로 지정해야 합니다.
// 단일 소스
await cook.fetch('air-quality', { sidoName: '서울' });
// 멀티소스
await cook.fetch('dashboard', {
weather: { city: '서울' },
air: { sidoName: '서울' },
});
존재하지 않는 라벨을 쓰면 조용히 무시됩니다. 예외가 나지 않고 콘솔에 경고만 남습니다.
[ApiCook] 알 수 없는 소스 label 'wether' — 무시됩니다. 사용 가능: weather, air
이 경우 해당 소스는 파라미터 없이 호출되어, 원본 API가 필수 값 누락으로 오류를 내거나 빈 결과를 돌려줍니다. 결과가 이상하면 브라우저 콘솔부터 확인하세요.
소스마다 다른 인증 키를 쓰는 방법은 인증 파라미터 관리에 있습니다.
_meta — 무슨 일이 있었는지 알려주는 필드
멀티소스 응답에는 항상 _meta가 붙습니다. 소스가 하나뿐인 엔드포인트에는 붙지 않습니다.
{
"weather": { "temperature": 23 },
"air": null,
"_meta": {
"partial": true,
"errors": [
{ "source": "air", "kind": "http", "message": "500 Internal Server Error", "status": 500 }
]
}
}
kind는 네 가지입니다.
| kind | 의미 |
|---|---|
http |
원본이 4xx·5xx를 반환 (status에 코드가 들어옵니다) |
timeout |
제한 시간 초과 |
fetch |
네트워크 실패, JSON 파싱 실패, 응답 형식 불일치 |
transform |
가공 규칙 적용 중 오류 |
개별 소스의 HTTP 상태 코드를 얻을 수 있는 통로는 _meta.errors[].status뿐입니다. 던져진 에러 객체에는 상태 코드가 실리지 않으므로, 상태별 분기가 필요하면 여기를 보세요.
_meta는 예약어입니다. 소스 라벨을 _로 시작하게 지을 수 없습니다.
일부만 실패했을 때
기본적으로 일부 소스가 실패해도 예외가 나지 않습니다. 실패한 소스는 null이 되고 나머지는 정상적으로 돌아옵니다.
const data = await cook.fetch('dashboard', { weather: {...}, air: {...} });
if (data._meta.partial) {
console.warn('일부 데이터를 가져오지 못했습니다', data._meta.errors);
}
// 실패한 소스는 null이므로 반드시 확인하고 씁니다
if (data.air) {
render(data.air.pm10);
}
날씨는 나오는데 미세먼지만 비는 화면이, 아무것도 안 나오는 화면보다 낫다는 판단입니다.
required — 없으면 안 되는 소스
콘솔에서 소스를 필수로 지정하면 그 소스가 실패했을 때 전체 호출이 예외로 끝납니다.
ApiCookError: 'dashboard' 필수 소스 호출 실패 — air: 503 Service Unavailable
모든 소스가 실패하면 required 여부와 관계없이 예외가 납니다.
ApiCookError: 'dashboard' 모든 소스 호출 실패 — weather: 500 ...; air: 503 ...
기본값은 필수가 아닙니다. 화면의 뼈대가 되는 데이터에만 필수를 켜고, 곁들이는 정보는 선택으로 두는 편이 안정적입니다.
제한과 기본값
| 항목 | 값 |
|---|---|
| 소스 개수 | 1~5개 |
| 라벨 형식 | 소문자·숫자·하이픈(^[a-z0-9-]+$), _로 시작 불가, 중복 불가 |
| 소스별 제한 시간 | 100~30,000ms (direct 기본 5,000 / proxy 기본 15,000) |
| 병합 전략 | namespace만 지원 |
concat·join 전략은 아직 구현되지 않았습니다. 설정에 넣으면 호출 시점에 오류가 납니다.
알아 둘 것 세 가지
1. Free 플랜에서는 멀티소스 엔드포인트가 배포되지 않습니다. 설정에서 제외되므로 호출하면 "엔드포인트를 찾을 수 없습니다"가 납니다. Pro에서 Free로 내려가면 기존 엔드포인트는 비활성 상태가 되어 프록시가 503을 돌려줍니다.
2. 부분 실패 응답은 캐시되지 않습니다. proxy 모드에서 일부 소스가 실패한 결과는 서버 캐시에 저장되지 않으므로, 다음 호출은 원본을 다시 시도합니다.
3. 커뮤니티에 공개할 수 없습니다. 멀티소스로 만든 가공 설정은 공유 목록에 올라가지 않습니다.