Pembangun memeriksa konfigurasi aplikasi

Aplikasi berjalan lancar di laptop, semua unit test hijau, tetapi sebaik sahaja di-deploy ke server, halaman terus memaparkan ralat 500. Selalunya puncanya bukan logik perniagaan yang rosak, melainkan tetapan persekitaran yang bercampur: connection string masih menunjuk ke pangkalan data lokal, URL payment gateway masih menggunakan endpoint sandbox, atau kunci API belum dimasukkan ke dalam persekitaran sasaran.

Dalam projek ASP.NET Core, pemisahan antara Development, Staging, dan Production tidak boleh sekadar wujud pada nama cabang Git. Ia perlu jelas pada cara aplikasi membaca konfigurasi, cara rahsia disimpan, dan cara kegagalan dikesan sebelum pengguna sebenar terkesan.

Fahami susunan override konfigurasi ASP.NET Core

Apabila kita memulakan aplikasi dengan WebApplication.CreateBuilder(args), rangka kerja ini memuatkan sumber konfigurasi mengikut susunan tertentu. Nilai yang dimuatkan kemudian akan menindih nilai sebelumnya:

  1. appsettings.json
  2. appsettings.{Environment}.json (contohnya appsettings.Production.json)
  3. User Secrets (hanya apabila ASPNETCORE_ENVIRONMENT=Development)
  4. Environment Variables
  5. Command-line arguments

Dokumentasi konfigurasi ASP.NET Core menerangkan perincian ini dengan jelas, tetapi ramai pembangun masih terkeliru apabila deploy ke Linux atau kontena Docker. Dalam fail JSON, kita menulis struktur bertingkat seperti ConnectionStrings:Default atau PaymentGateway:ApiKey. Di persekitaran Linux pula, tanda titik bertindih (:) tidak mesra dengan shell bash atau unit systemd. Oleh itu, gantikan pemisah dengan dua garis bawah (__):

export ASPNETCORE_ENVIRONMENT=Staging
export ConnectionStrings__Default="Host=10.0.1.15;Database=app_staging;Username=app_user;Password=..."
export PaymentGateway__CallbackUrl="https://staging.contoh.my/api/fpx/callback"

Jika menggunakan systemd di pelayan Ubuntu atau Debian, elakkan meletakkan secret terus di dalam fail unit utama yang boleh dibaca oleh pengguna lain. Gunakan fail persekitaran berasingan dengan kebenaran 600 yang hanya boleh dibaca oleh pengguna servis tersebut, atau EnvironmentFile=/etc/myapp/env.conf.

Jangan commit rahsia, tetapi sediakan templat yang jelas

Kesilapan klasik yang masih kerap berlaku ialah memasukkan kunci API atau kata laluan SMTP ke dalam appsettings.Development.json lalu di-commit ke repositori. Walaupun ia hanya untuk persekitaran ujian, tabiat ini berbahaya apabila repositori dikongsi dengan kontraktor luar atau menjadi awam suatu hari nanti.

Untuk pembangunan lokal, gunakan User Secrets yang terbina dalam .NET CLI:

dotnet user-secrets init
dotnet user-secrets set "ConnectionStrings:Default" "Host=localhost;Database=app_dev;Username=postgres;Password=devpass"
dotnet user-secrets set "PaymentGateway:SecretKey" "sk_test_123456"

Fail secrets.json ini disimpan di luar folder projek (~/.microsoft/usersecrets/ di Linux/macOS atau %APPDATA%\Microsoft\UserSecrets\ di Windows), jadi tiada risiko terlepas ke Git. Pada masa yang sama, sediakan fail appsettings.Example.json di dalam repositori yang menyenaraikan semua kekunci yang diperlukan tanpa nilai sebenar. Apabila ada tetapan baharu ditambah dalam kod, kemas kini fail contoh tersebut dalam pull request yang sama supaya pembangun lain tidak perlu meneka nama pembolehubah daripada perbualan Slack atau WhatsApp lama.

Gagalkan aplikasi awal jika tetapan tiada

Situasi paling menyakitkan ialah aplikasi berjaya dimulakan, melepasi health check, tetapi hanya meletup pada jam 2 pagi apabila pelanggan cuba membuat bayaran kerana satu nilai konfigurasi tertinggal. Untuk mengelakkan perkara ini, gunakan corak IOptions<T> bersama pengesahan semasa startup:

builder.Services
    .AddOptions<PaymentGatewayOptions>()
    .BindConfiguration("PaymentGateway")
    .ValidateDataAnnotations()
    .ValidateOnStart();

Dengan .ValidateOnStart(), sekiranya SecretKey atau MerchantId kosong atau tidak sah, aplikasi akan terus gagal dimulakan semasa deploy. Pipeline CI/CD atau skrip deployment akan mengesan kegagalan serta-merta dan mengekalkan versi lama yang stabil, berbanding membiarkan versi rosak menerima trafik produksi.

Staging bukan salinan data produksi

Staging wujud untuk menguji proses deployment, migrasi pangkalan data, konfigurasi Nginx atau reverse proxy, dan integrasi pihak ketiga dalam suasana yang hampir sama dengan produksi. Namun, “hampir sama” tidak bermaksud anda patut menyalin pangkalan data produksi beserta data peribadi pengguna ke staging.

Selain melanggar prinsip keselamatan dan privasi data (seperti PDPA di Malaysia), menyalin data produksi ke staging membuka risiko tidak dijangka—contohnya skrip peringatan automatik atau cron job di staging menghantar emel dan mesej WhatsApp ujian kepada pelanggan sebenar.

Untuk mengelakkan bencana sebegini:

  • Gunakan pelayan SMTP ujian seperti Mailpit atau MailHog di persekitaran Development dan Staging supaya semua emel keluar terperangkap secara lokal.
  • Gunakan data contoh (seed data) yang dijana secara teratur untuk menguji aliran kerja dan prestasi carian.
  • Pastikan kunci API untuk gerbang pembayaran, storan objek (S3/R2), dan perkhidmatan SMS di staging menggunakan akaun sandbox yang terasing sepenuhnya daripada akaun produksi.

Konfigurasi yang kemas membuatkan perbezaan antara persekitaran dapat dilihat dengan jelas dalam satu pandangan. Apabila proses onboarding pembangun baharu mengambil masa kurang daripada setengah jam tanpa perlu bertanya kata laluan di ruang sembang, itu tanda asas kejuruteraan projek sudah berada di landasan yang betul.