모든 API 팀은 같은 벽에 부딪힙니다. 처음에 구축하는 요청들은 하나의 토큰을 헤더에 붙여넣은 채 하나의 서버를 가리킵니다. 그러다 스테이징 환경이 나타나고, 다음으로 프로덕션 환경이 나타납니다. 갑자기 실행할 때마다 수동으로 URL을 편집하게 되고, 기본 URL이 오래되어 누군가가 프로덕션 환경에 대해 삭제 엔드포인트를 테스트하는 일이 발생합니다. API 환경 변수는 이러한 종류의 실수를 완전히 없애기 위해 존재하며, Apidog는 이를 나중에 추가하는 대신 제품의 핵심 기능으로 구축합니다.
이 가이드는 Apidog에서 개발, 스테이징, 프로덕션 환경을 설정하는 방법, 토큰과 API 키를 하드코딩된 문자열 대신 변수로 저장하는 방법, 로컬 값을 사용하여 실제 비밀 정보를 클라우드에 두지 않는 방법, 그리고 Apidog CLI를 통해 환경을 CI로 전달하는 방법을 보여줍니다. 환경 및 비밀 정보 관리 기능을 갖춘 API 클라이언트가 무엇을 다루어야 하는지에 대한 더 넓은 그림을 원한다면, 해당 내용은 별도로 다루었습니다. 여기서는 실용적인 내용을 다룹니다.
두 번째 환경에서 하드코딩된 URL과 토큰이 문제를 일으키는 이유
하나의 환경에서는 하드코딩이 잘 작동합니다. https://api.acmepay.dev는 모든 요청에 존재하고, 토큰은 모든 Authorization 헤더에 존재하며, 아직은 문제가 없습니다.
두 번째 환경이 나타나는 순간부터 문제가 시작됩니다:
- 모든 요청은 재지정을 위해 편집해야 합니다. 개발 환경을 가리키는 50개의 엔드포인트는 스테이징을 테스트하기 위해 50번의 URL 편집을 의미하며, 다시 되돌리기 위해 50번 더 편집해야 합니다. 하나쯤은 놓칠 것입니다.
- 토큰이 경계를 넘어 유출됩니다. 요청 본문에 붙여넣은 프로덕션 API 키는 프로젝트와 함께 저장되고, 팀과 공유되며, 컬렉션과 함께 내보내집니다. Twelve-Factor App 방법론은 이에 대해 명확하게 말합니다: 구성은 배포마다 다르지만 코드는 그렇지 않으므로, 구성은 공유하는 아티팩트에 절대 속해서는 안 됩니다.
- 실행이 재현 불가능해집니다. URL과 자격 증명이 각 요청 내부에 있을 때, '스테이징 환경에 대해 스모크 테스트 실행'은 한 번의 클릭 스위치 대신 수동으로 찾아서 바꾸는 의식이 됩니다.
해결책은 오래되었고 검증되었습니다: 요청 정의(메서드, 경로, 본문, 어설션)를 배포 컨텍스트(기본 URL, 자격 증명, 환경별 ID)와 분리합니다. 요청은 모든 곳에서 동일하게 유지됩니다. 컨텍스트만 변경됩니다.
Apidog가 환경과 변수를 모델링하는 방법
Apidog는 이 문제를 함께 작동하는 두 부분으로 나눕니다.
환경은 Dev, Staging, Prod와 같이 이름이 지정된 컨텍스트입니다. 각 환경은 고유한 기본 URL(요청이 전송되는 서버)과 자체 변수 값 세트를 가집니다. 환경을 전환하면 프로젝트의 모든 요청이 한 번에 재지정되며, 이는 환경 관리 문서에 설명되어 있습니다.
변수는 값이 들어가는 모든 곳(URL, 쿼리 매개변수, 헤더, 요청 본문, 스크립트)에서 {{variable_name}}과 같이 참조하는 이름 지정된 플레이스홀더입니다. 런타임 시 Apidog는 활성 환경 및 작동 중인 다른 범위에 대해 플레이스홀더를 해결합니다.
변수 범위와 우선순위
Apidog는 다섯 가지 범위로 변수를 해결합니다. 우선순위가 낮은 순서부터 높은 순서까지: 전역(global), 모듈(module), 환경(environment), 데이터(data), 로컬(local)입니다.
| 범위 | 위치 | 일반적인 사용 |
|---|---|---|
| 전역 | 전체 프로젝트, 모든 환경 | {{api_version}}과 같은 상수 |
| 모듈 | 프로젝트의 한 모듈 | 마이크로서비스 프로젝트의 서비스별 설정 |
| 환경 | 활성 환경만 | {{base_url}}, {{auth_token}}, {{merchant_id}} |
| 데이터 | 테스트 실행 시 외부 CSV/JSON 파일 | 행별 테스트 입력 |
| 로컬 (임시) | 하나의 요청 또는 테스트 실행 후 사라짐 | 시나리오 중간에 추출된 토큰 |
실제로 우선순위가 중요합니다. {{auth_token}}을 전역 대체값으로 정의하면 모든 곳에서 작동하지만, Staging 환경이 자체 {{auth_token}}을 정의하는 순간, Staging이 활성 상태인 동안 환경 값이 우선합니다. 이것이 바로 당신이 원하는 것입니다: 아래에는 공유 기본값, 위에는 환경별 재정의입니다. 각 범위에 대한 더 자세한 내용은 Apidog에서 변수 마스터하기 가이드를 참조하십시오.
사람들을 혼란스럽게 하는 한 가지 행동은 로컬 변수가 설계상 임시적이라는 것입니다. 스크립트에서 하나를 설정하면 실행이 완료될 때 사라집니다. 이는 테스트 시나리오 내에서 임시 값을 위한 기능이며, 영구적으로 유지될 것이라고 예상했다면 당신의 정신 모델에 버그가 있는 것입니다. 내일 필요한 모든 것은 환경 또는 전역 변수에 속합니다.
Apidog에서 개발, 스테이징, 프로덕션 환경 설정하기
다음은 세 가지 배포를 가진 결제 API의 워크플로입니다.
1. 세 가지 환경 생성
프로젝트 오른쪽 상단에서 환경 관리를 열고 각 배포에 대한 새 환경을 만드세요. 각 환경에 이름과 기본 URL을 지정합니다:
Dev→https://api-dev.acmepay.devStaging→https://api-staging.acmepay.devProd→https://api.acmepay.com
기본 URL은 프로토콜 접두사를 포함하고 후행 슬래시 없이 유지하여 경로가 깔끔하게 연결되도록 하세요.
2. 각 환경에서 동일한 변수 이름 정의
일관성이 핵심입니다. 모든 환경은 다른 값으로 동일한 변수 이름을 정의합니다:
| 변수 | 개발 | 스테이징 | 프로덕션 |
|---|---|---|---|
{{auth_token}} |
개발 토큰 | 스테이징 토큰 | 프로덕션 토큰 |
{{merchant_id}} |
mrc_test_449 |
mrc_stg_449 |
mrc_live_8821 |
{{webhook_secret}} |
개발 비밀 | 스테이징 비밀 | 프로덕션 비밀 |
3. 요청에서 변수 참조, 원시 값 사용 금지
이제 청구 생성 요청은 모든 곳에서 다음과 같습니다:
POST /v1/charges
Authorization: Bearer {{auth_token}}
{
"merchant_id": "{{merchant_id}}",
"amount": 1999,
"currency": "usd"
}
기본 URL은 전혀 나타나지 않습니다. Apidog는 활성 환경의 기본 URL을 자동으로 앞에 붙입니다. 요청 정의에는 환경을 명시하는 내용이 없으므로 이식성이 뛰어납니다.
4. 선택기로 전환
환경 선택기는 Apidog 창의 오른쪽 상단 모서리에 있습니다. Staging을 선택하면 프로젝트의 모든 요청, 테스트 시나리오 및 스크립트가 스테이징의 기본 URL 및 스테이징의 변수 값을 기반으로 해결됩니다. 편집이나 찾기-바꾸기가 필요 없습니다. 어떤 배포 계층에 무엇을 두어야 할지 고려 중이라면, 샌드박스 vs 테스트 환경 비교가 팀들이 일반적으로 이를 어떻게 나누는지 다룹니다.
Postman에서 넘어오셨나요? 기존 환경이 그대로 이전됩니다. Postman 마이그레이션 가이드는 컬렉션과 환경을 몇 번의 클릭으로 가져오는 방법을 안내하며, 변수 값도 포함됩니다.
비밀 정보는 로컬에 보관: 공유 값 vs 로컬 값
이것은 대부분의 팀이 잘못하는 부분이며, Apidog의 설계가 그 가치를 증명하는 부분입니다.
Apidog의 모든 환경 및 전역 변수는 변수 참조에 설명된 대로 두 가지 값을 가질 수 있습니다:
- 공유 값: Apidog 서버와 동기화되며 프로젝트의 모든 사람에게 보입니다.
- 로컬 값: 클라이언트 캐시에만 기기에 저장됩니다. 클라우드에 동기화되지 않으며 팀원은 절대로 볼 수 없습니다.
둘 다 존재할 경우, 클라이언트는 로컬 값을 사용합니다. 따라서 비밀 정보를 위한 안전한 패턴은 간단합니다:
- 예를 들어
{{auth_token}}과 같은 변수를 각 환경에 생성합니다. - 공유 값을 비워두거나
SET_LOCALLY와 같은 플레이스홀더로 설정합니다. - 실제 토큰을 자신의 기기에 있는 로컬 값에 넣습니다.
변수 구조는 팀과 동기화되지만 비밀 정보는 그렇지 않습니다. 각 엔지니어는 자신의 자격 증명을 한 번 입력하면 모든 공유 요청이 즉시 작동합니다. 이는 OWASP 비밀 관리 치트 시트와 일치합니다: 비밀 정보를 엄격하게 범위 지정하고, 통제된 채널을 통해 공유하며, 광범위하게 복제되는 모든 것에서 멀리 떨어뜨려 놓으세요.
알아두면 좋을 두 가지 주의사항이 있습니다. 로컬 값은 클라이언트 캐시에 저장되므로 Apidog의 캐시를 지우면 삭제되며, 새 노트북으로 이동하면 다시 입력해야 합니다. 이를 위해 5분 정도 시간을 할애하세요. 12명에게 프로덕션 키가 동기화되어 5시간 동안 인시던트 검토를 하는 대신 말이죠.
또한 전체 환경을 공유 대신 비공개로 표시할 수 있습니다. 배포하는 두 사람에게만 보이는 Prod 환경은 합법적인 설정이며, 이는 심층 방어를 위해 로컬 값과 함께 사용될 수 있습니다.
테스트 시나리오 및 CI에서 환경 사용
환경은 Apidog의 테스트 시나리오에 직접 연결됩니다. 시나리오를 한 번 구축한 다음(청구 생성, 상태 폴링, 결제 확인), 실행 시점에 어떤 환경에 대해 실행할지 선택합니다. 동일한 시나리오가 개발 스모크 테스트와 스테이징 회귀 테스트 스위트가 됩니다.
스크립트는 동일한 범위를 읽고 씁니다. 로그인 응답에서 새 토큰을 캡처하는 후처리기는 다음과 같습니다:
const body = pm.response.json();
pm.environment.set("auth_token", body.access_token);
시나리오의 이후 요청은 {{auth_token}}을 캡처된 값으로 해결합니다. 요청 매개변수를 스크립트로 가져오는 패턴에 대해서는 사전/사후 요청 스크립트에서 요청 매개변수 검색을 참조하십시오.
CI의 경우, Apidog CLI는 환경을 플래그로 받습니다:
apidog run --access-token $APIDOG_ACCESS_TOKEN \
-t 637132 \
-e 358171 \
--env-var "auth_token=$STAGING_API_TOKEN"
-e는 ID로 환경을 선택합니다. CLI는 머신의 로컬 값이 아닌 공유 값을 해결한다는 점에 유의하세요. 이는 올바른 동작입니다. 개인 비밀 정보는 빌드 에이전트에서 어쨌든 접근할 수 없어야 합니다. 대신 런타임에 실제 자격 증명을 주입하세요. key=value 형태의 --env-var 및 --global-var 재정의를 사용하거나, --variables를 사용하여 전체 파일을 로드합니다. 실제 비밀 정보는 CI 공급자의 비밀 저장소(GitHub Actions secrets, GitLab CI variables)에 저장하고 이를 통해 전달하세요. 파이프라인에는 절대로 토큰이 일반 텍스트로 포함되지 않으며, 자격 증명을 교체하는 것은 하나의 CI 비밀을 업데이트하는 것을 의미합니다.
이것으로부터 파생되는 팀 워크플로
종합하면, 작업 분할은 명확합니다:
- 공유, 동기화: 환경 이름, 기본 URL, 변수 이름, 플레이스홀더 공유 값, 테스트 시나리오.
- 개인, 로컬: 각 엔지니어의 토큰 및 키를 로컬 값으로.
- CI 소유: CI 비밀 저장소의 파이프라인 자격 증명, CLI 플래그를 통해 주입.
새로운 팀원이 합류하여 프로젝트를 열면, 모든 변수가 이름 지정되고 문서화된 세 가지 준비된 환경을 보게 됩니다. 그들은 자신의 개발 토큰을 로컬 값 필드에 붙여넣고 작업을 시작합니다. 누구도 프로덕션 키를 DM으로 보내지 않습니다. 누구도 최신 상태를 벗어나는 "현재 스테이징 URL" 위키 페이지를 관리하지 않습니다.
피해야 할 일반적인 함정
- 실제 토큰을 공유 값에 커밋하는 것. 단연코 가장 흔한 실수입니다. 비밀 정보가 팀원에게 전달되어야 한다면, 동기화된 변수를 통하는 것이 아니라 비밀번호 관리자나 볼트(vault)를 통해야 합니다. 공유 값을 한 번 감사하세요. 실제 자격 증명처럼 보이는 모든 것은 로컬 값으로 이동하고 교체되어야 합니다.
- 어떤 환경이 활성 상태인지 잊는 것. 눈으로 선택기를 확인하기 전에 몸이 요청을 보냅니다. 파괴적인 작업을 실수하기 어렵게 만드세요:
Prod환경은 더 적은 사람들에게 비공개로 유지하고, 프로덕션 전용 변수에는 고유한 이름을 부여하거나 플레이스홀더 공유 값을 사용하여 잘못된 환경 실행이 조용히 성공하는 대신 인증에서 크게 실패하도록 하세요. - 임시 변수가 영구적으로 유지될 것으로 기대하는 것. 실행 중에 설정된 로컬 범위 변수는 실행이 끝나면 사라집니다. 스크립트에서 영구적인 모든 것을 명시적으로 환경 범위로 승격시키세요.
- 환경마다 다른 변수 이름. 개발 환경에서
{{token}}이라고 부르고 스테이징 환경에서{{auth_token}}이라고 부른다면, 환경을 전환할 때 요청의 절반이 깨집니다. 모든 곳에서 동일한 이름, 다른 값만 사용하세요. - 모든 것을 위한 하나의 거대한 환경.
dev_base_url과prod_base_url을 하나의 환경에 몰아넣는다면, 추가 단계를 거쳐 하드코딩 문제를 재현한 것입니다. 배포 컨텍스트당 하나의 환경을 사용하세요.
이것을 설정할 준비가 되셨나요? 무료로 Apidog를 다운로드하고, 세 가지 환경을 생성한 다음, 첫 번째 토큰을 로컬 값으로 옮겨보세요. 기존 프로젝트의 경우 약 10분 정도 소요됩니다.
자주 묻는 질문
공유 Apidog 프로젝트에서 비밀 정보를 어떻게 제외하나요?
로컬 값으로 저장하세요. 모든 변수에는 공유 값(팀과 동기화됨)과 로컬 값(자신의 기기에만 캐시됨)이 있습니다. 공유 값은 플레이스홀더로 남겨두고 실제 토큰은 로컬에 보관하세요. 추가적인 격리를 위해 Prod와 같은 민감한 환경은 비공개로 표시하여 특정 사람만 볼 수 있도록 합니다.
전역 변수와 환경 변수의 차이점은 무엇인가요?
전역 변수는 어떤 환경이 활성 상태인지에 관계없이 전체 프로젝트에 적용됩니다. API 버전 문자열과 같이 배포 간에 변경되지 않는 값에 사용하세요. 환경 변수는 하나의 환경에 속하며, 둘 다 동일한 이름을 정의할 경우 전역 변수보다 우선합니다. 저희의 변수 가이드는 모듈, 데이터, 로컬을 포함한 다섯 가지 모든 범위를 자세히 설명합니다.
Apidog 클라이언트에서는 테스트가 통과하는데 CI에서는 실패하는 이유는 무엇인가요?
일반적으로 클라이언트는 로컬 값을 해결하는 반면 CLI는 공유 값을 해결하기 때문입니다. 토큰이 로컬 값에만 있다면 CLI는 비어 있거나 플레이스홀더 변수를 보게 됩니다. --env-var "auth_token=$YOUR_CI_SECRET"을 사용하여 파이프라인에서 자격 증명을 명시적으로 전달하여 CI가 런타임에 자체 비밀 정보를 제공하도록 하세요.
Postman 환경을 Apidog로 옮길 수 있나요?
네, 가능합니다. Apidog는 Postman 컬렉션과 환경을 직접 가져오며, 변수 이름과 값을 그대로 유지하므로 마이그레이션 후에도 {{base_url}} 참조가 계속 작동합니다. 가져온 값을 검토한 후 Postman 내보내기에는 일반 텍스트로 비밀 정보가 포함될 수 있으므로 실제 자격 증명은 로컬 값으로 옮기세요.