Cara Mengelola Lingkungan Dev, Staging, Prod, dan Variabel Rahasia di Apidog

Setiap tim API menghadapi kendala yang sama. Permintaan pertama yang Anda bangun mengarah ke satu server, dengan satu token yang ditempelkan ke dalam header. Lalu muncul staging. Lalu production. Tiba-tiba Anda harus mengedit URL secara manual sebelum setiap eksekusi, dan seseorang menguji endpoint delete terhadap prod karena base URL sudah usang. Variabel lingkungan API ada untuk menghilangkan seluruh kelas kesalahan ini, dan Apidog membangunnya ke dalam inti produk alih-alih memasangnya sebagai tambahan. Panduan ini menunjukkan kepada Anda cara menyiapkan lingkungan dev, staging, dan prod di Apidog, menyimpan token dan kunci API sebagai variabel alih-alih string yang di-hardcode, menjaga rahasia asli tetap off the cloud dengan nilai lokal, dan meneruskan lingkungan ke CI melalui Apidog CLI. Jika Anda ingin gambaran yang lebih luas tentang apa yang seharusnya ditangani oleh klien API dengan manajemen lingkungan dan rahasia, kami telah membahasnya secara terpisah. Di sini kita akan menjadi praktis.

Mengapa URL dan token yang di-hardcode rusak dengan lingkungan kedua

Dengan satu lingkungan, hardcoding berfungsi dengan baik. https://api.acmepay.dev berada di setiap permintaan, token Anda berada di setiap header Otorisasi, dan belum ada yang terasa sakit. Rasa sakit dimulai saat lingkungan kedua muncul:

• Setiap permintaan perlu diedit untuk menarget ulang. Lima puluh endpoint yang mengarah ke dev berarti lima puluh pengeditan URL untuk menguji staging, lalu lima puluh lagi untuk beralih kembali. Anda pasti akan melewatkan satu.
• Token bocor melintasi batas. Kunci API prod yang ditempelkan ke dalam badan permintaan disimpan dengan proyek, dibagikan dengan tim, dan diekspor dengan koleksi. Metodologi Twelve-Factor App sangat lugas tentang hal ini: konfigurasi bervariasi antar deploy, kode tidak, jadi konfigurasi tidak pernah termasuk dalam artefak yang Anda bagikan.
• Eksekusi tidak lagi dapat direproduksi. Ketika URL dan kredensial berada di dalam setiap permintaan, "jalankan smoke test terhadap staging" menjadi ritual pencarian-dan-penggantian manual alih-alih sakelar sekali klik.

Perbaikannya sudah lama dan terbukti: pisahkan definisi permintaan (metode, jalur, badan, pernyataan) dari konteks penyebaran (base URL, kredensial, ID spesifik lingkungan). Permintaan tetap identik di mana-mana. Hanya konteksnya yang berubah.

Bagaimana Apidog memodelkan lingkungan dan variabel

Apidog membagi masalah menjadi dua bagian yang bekerja sama. Sebuah lingkungan adalah konteks bernama, seperti Dev, Staging, atau Prod. Setiap lingkungan membawa base URL-nya sendiri (server tempat permintaan dikirim) dan set nilai variabelnya sendiri. Beralih lingkungan dan setiap permintaan dalam proyek langsung menarget ulang, seperti yang dijelaskan oleh dokumen manajemen lingkungan. Sebuah variabel adalah placeholder bernama yang Anda referensikan sebagai {{variable_name}} di mana pun ada nilai: URL, query params, header, badan permintaan, dan skrip. Saat runtime, Apidog menyelesaikan placeholder terhadap lingkungan aktif dan cakupan lain yang terlibat.

Cakupan variabel dan mana yang menang

Apidog menyelesaikan variabel melalui lima cakupan. Dari prioritas terendah hingga tertinggi: global, modul, lingkungan, data, dan lokal.

Urutan prioritas penting dalam praktik. Definisikan {{auth_token}} sebagai fallback global dan itu berfungsi di mana-mana, tetapi saat lingkungan Staging Anda mendefinisikan {{auth_token}}-nya sendiri, nilai lingkungan menang saat Staging aktif. Itulah yang Anda inginkan: default bersama di bawah, override spesifik lingkungan di atas. Untuk panduan yang lebih mendalam tentang setiap cakupan, lihat panduan kami untuk menguasai variabel di Apidog. Satu perilaku yang membingungkan orang: variabel lokal bersifat sementara berdasarkan desain. Setel satu dalam skrip dan itu akan hilang saat eksekusi selesai. Itu adalah fitur untuk nilai-nilai awal dalam skenario uji, dan bug dalam model mental Anda jika Anda berharap itu bertahan. Apa pun yang Anda butuhkan besok termasuk dalam variabel lingkungan atau global.

Siapkan dev, staging, dan prod di Apidog

Berikut adalah alur kerja untuk API pembayaran dengan tiga deployment.

1. Buat ketiga lingkungan

Buka manajemen lingkungan dari kanan atas proyek dan buat lingkungan baru untuk setiap deployment. Beri nama dan base URL pada masing-masing:

• Dev → https://api-dev.acmepay.dev
• Staging → https://api-staging.acmepay.dev
• Prod → https://api.acmepay.com

Jaga agar base URL diawali dengan protokol dan tanpa garis miring di akhir, sehingga jalur dapat digabungkan dengan rapi.

2. Definisikan nama variabel yang sama di setiap lingkungan

Konsistensi adalah seluruh triknya. Setiap lingkungan mendefinisikan nama variabel yang sama dengan nilai yang berbeda:

3. Referensikan variabel dalam permintaan, jangan pernah menggunakan nilai mentah

Permintaan untuk membuat charge sekarang terlihat seperti ini di mana-mana:

POST /v1/charges
Authorization: Bearer {{auth_token}}

{
  "merchant_id": "{{merchant_id}}",
  "amount": 1999,
  "currency": "usd"
}

Base URL tidak muncul sama sekali; Apidog secara otomatis menambahkan base URL lingkungan aktif. Tidak ada dalam definisi permintaan yang menyebutkan lingkungan, inilah yang membuatnya portabel.

4. Beralih dengan selector

Pemilih lingkungan berada di sudut kanan atas jendela Apidog. Pilih Staging dan setiap permintaan, skenario uji, dan skrip dalam proyek akan diselesaikan terhadap base URL staging dan nilai variabel staging. Tidak ada pengeditan, tidak ada pencarian-dan-penggantian. Jika Anda sedang mempertimbangkan apa yang harus berada di setiap tingkatan deployment, perbandingan kami tentang sandbox vs lingkungan uji membahas bagaimana tim biasanya memisahkannya. Berasal dari Postman? Lingkungan Anda yang sudah ada akan terbawa. Panduan migrasi Postman menjelaskan cara mengimpor koleksi dan lingkungan dalam beberapa klik, termasuk nilai variabel.

Jaga rahasia tetap lokal: nilai bersama vs nilai lokal

Ini adalah bagian yang paling sering salah dipahami oleh sebagian besar tim, dan bagian di mana desain Apidog menunjukkan keunggulannya. Setiap variabel lingkungan dan global di Apidog dapat menyimpan dua nilai, seperti yang didokumentasikan dalam referensi variabel:

• Nilai bersama: disinkronkan dengan server Apidog dan terlihat oleh semua orang di proyek.
• Nilai lokal: hanya disimpan dalam cache klien Anda di mesin Anda. Ini tidak pernah disinkronkan ke cloud dan rekan tim tidak pernah melihatnya.

Ketika keduanya ada, klien Anda menggunakan nilai lokal. Jadi, pola aman untuk rahasia sederhana:

1. Buat variabel, misalnya {{auth_token}}, di setiap lingkungan.
2. Biarkan nilai bersama kosong, atau atur ke placeholder seperti SET_LOCALLY.
3. Letakkan token asli di nilai lokal di mesin Anda sendiri.

Struktur variabel disinkronkan ke tim. Rahasianya tidak. Setiap teknisi memasukkan kredensial mereka sendiri sekali, dan setiap permintaan bersama berfungsi untuk mereka segera. Ini sejalan dengan OWASP Secrets Management Cheat Sheet: batasi cakupan rahasia secara ketat, bagikan melalui saluran yang terkontrol, dan jauhkan dari apa pun yang direplikasi secara luas. Dua peringatan yang perlu diketahui. Nilai lokal berada di cache klien, jadi menghapus cache Apidog akan menghapusnya, dan pindah ke laptop baru berarti memasukkannya kembali. Alokasikan lima menit untuk itu, bukan lima jam tinjauan insiden karena kunci produksi disinkronkan ke dua belas orang. Anda juga dapat menandai seluruh lingkungan sebagai pribadi daripada dibagikan. Lingkungan Prod yang hanya terlihat oleh dua orang yang melakukan deploy adalah pengaturan yang sah, dan itu bertumpuk dengan nilai lokal untuk pertahanan yang mendalam.

Gunakan lingkungan dalam skenario uji dan CI

Lingkungan langsung masuk ke skenario uji Apidog. Buat skenario sekali (buat charge, polling status, verifikasi penyelesaian), lalu pilih lingkungan mana yang akan dijalankan pada waktu eksekusi. Skenario yang sama menjadi smoke test dev Anda dan suite regresi staging Anda. Skrip membaca dan menulis cakupan yang sama. Post-processor yang menangkap token baru dari respons login terlihat seperti ini:

const body = pm.response.json();
pm.environment.set("auth_token", body.access_token);

Permintaan selanjutnya dalam skenario menyelesaikan {{auth_token}} ke nilai yang ditangkap. Untuk pola seperti menarik parameter permintaan ke dalam skrip, lihat mengambil parameter permintaan dalam skrip pra/pasca-permintaan. Untuk CI, Apidog CLI mengambil lingkungan sebagai flag:

apidog run --access-token $APIDOG_ACCESS_TOKEN \
  -t 637132 \
  -e 358171 \
  --env-var "auth_token=$STAGING_API_TOKEN"

-e memilih lingkungan berdasarkan ID. Perhatikan bahwa CLI menyelesaikan nilai bersama, bukan nilai lokal mesin Anda, yang merupakan perilaku yang benar: rahasia pribadi Anda tidak seharusnya dapat dijangkau dari agen build. Suntikkan kredensial asli saat runtime sebagai gantinya, dengan override --env-var dan --global-var dalam bentuk key=value, atau --variables untuk memuat seluruh file. Simpan rahasia sebenarnya di penyimpanan rahasia penyedia CI Anda (rahasia GitHub Actions, variabel GitLab CI) dan teruskan. Pipeline tidak pernah berisi token dalam teks biasa, dan merotasi kredensial berarti memperbarui satu rahasia CI.

Alur kerja tim yang dihasilkan dari ini

Secara bersama-sama, pembagian kerja menjadi bersih:

• Dibagikan, disinkronkan: nama lingkungan, base URL, nama variabel, nilai bersama placeholder, skenario uji.
• Pribadi, lokal: token dan kunci setiap engineer sebagai nilai lokal.
• Dimiliki oleh CI: kredensial pipeline di penyimpanan rahasia CI, disuntikkan melalui flag CLI.

Rekan tim baru bergabung, membuka proyek, dan melihat tiga lingkungan siap pakai dengan setiap variabel diberi nama dan didokumentasikan. Mereka menempelkan token dev mereka sendiri ke satu bidang nilai lokal dan mulai bekerja. Tidak ada yang mengirim kunci produksi melalui DM. Tidak ada yang memelihara halaman wiki "URL staging saat ini" yang menjadi usang.

Jebakan umum yang harus dihindari

• Melakukan commit token asli ke nilai bersama. Kesalahan paling umum sejauh ini. Jika sebuah rahasia perlu mencapai rekan tim, itu melalui pengelola kata sandi atau brankas, bukan melalui variabel yang disinkronkan. Audit nilai bersama Anda sekali; apa pun yang terlihat seperti kredensial aktif harus dipindahkan ke nilai lokal dan dirotasi.
• Melupakan lingkungan mana yang aktif. Memori otot mengirim permintaan sebelum mata memeriksa pemilih. Buat operasi destruktif lebih sulit untuk salah ketik: jaga agar Prod tetap pribadi bagi lebih sedikit orang, dan berikan variabel khusus prod nama yang berbeda atau nilai bersama placeholder sehingga eksekusi lingkungan yang salah gagal dengan keras pada otentikasi daripada berhasil secara diam-diam.
• Mengharapkan variabel sementara untuk bertahan. Variabel cakupan lokal yang ditetapkan selama eksekusi akan hilang ketika berakhir. Promosikan apa pun yang tahan lama ke cakupan lingkungan secara eksplisit dalam skrip Anda.
• Nama variabel yang berbeda di seluruh lingkungan. Jika dev menyebutnya {{token}} dan staging menyebutnya {{auth_token}}, beralih lingkungan akan merusak setengah dari permintaan Anda. Nama yang sama di mana-mana, hanya nilai yang berbeda.
• Satu lingkungan raksasa untuk semuanya. Jika Anda memasukkan dev_base_url dan prod_base_url ke dalam satu lingkungan, Anda telah membangun kembali masalah hardcoding dengan langkah-langkah tambahan. Satu lingkungan per konteks deployment.

Siap untuk mengaturnya? Unduh Apidog secara gratis, buat tiga lingkungan Anda, dan pindahkan token pertama Anda ke nilai lokal. Dibutuhkan sekitar sepuluh menit untuk proyek yang sudah ada.

FAQ

Bagaimana cara menjaga rahasia agar tidak masuk ke proyek Apidog yang dibagikan?

Simpan sebagai nilai lokal. Setiap variabel memiliki nilai bersama (disinkronkan ke tim) dan nilai lokal (hanya di-cache di mesin Anda). Biarkan nilai bersama sebagai placeholder dan simpan token asli secara lokal. Untuk isolasi tambahan, tandai lingkungan sensitif seperti Prod sebagai pribadi sehingga hanya orang-orang tertentu yang melihatnya sama sekali.

Apa perbedaan antara variabel global dan variabel lingkungan?

Variabel global berlaku di seluruh proyek terlepas dari lingkungan mana yang aktif; gunakan untuk nilai-nilai yang tidak pernah berubah antar deployment, seperti string versi API. Variabel lingkungan milik satu lingkungan dan menang atas global ketika keduanya mendefinisikan nama yang sama. Panduan variabel kami menguraikan kelima cakupan, termasuk modul, data, dan lokal.

Mengapa uji saya lulus di klien Apidog tetapi gagal di CI?

Biasanya karena klien menyelesaikan nilai lokal sementara CLI menyelesaikan nilai bersama. Jika token Anda hanya berada dalam nilai lokal, CLI melihat variabel yang kosong atau placeholder. Teruskan kredensial secara eksplisit dalam pipeline dengan --env-var "auth_token=$YOUR_CI_SECRET" sehingga CI menyediakan rahasianya sendiri saat runtime.

Bisakah saya memindahkan lingkungan Postman saya ke Apidog?

Ya. Apidog mengimpor koleksi dan lingkungan Postman secara langsung, menjaga nama dan nilai variabel tetap utuh, sehingga referensi {{base_url}} Anda terus berfungsi setelah migrasi. Tinjau nilai yang diimpor setelahnya dan pindahkan kredensial asli ke nilai lokal, karena ekspor Postman dapat membawa rahasia dalam teks biasa.