API di TypeScript Cara Membangun API yang Siap Digunakan

API TypeScript Anda mungkin terlihat kuat pada hari peluncuran. Rute yang dikompilasi, frontend yang mengimpor tipe yang dibagikan, dan editor memberikan perasaan hijau yang bersih kepada semua orang yang biasanya berarti “aman untuk dikirim.”

Kemudian backend berubah satu bidang respons, satu nilai yang dapat diabaikan muncul di mana orang tidak mengharapkannya, atau satu klien mobile terus-menerus memanggil bentuk payload yang lebih tua. Itulah di mana kebanyakan API di TypeScript pekerjaan terganggu. Bukan dalam sintaks. Di arus.

Isi Kandungan

Mengapa API Tipe Tidak Berhasil Setelah Peluncuran dan Bagaimana Mencegahnya
Scaffolding Your TypeScript API Project the Right Way
Kuatkan kompiler sebelum menambahkan fitur baru
Menghasilkan dan Mengonsumsi Klien yang Tipe Penuh API
Pengelolaan Kesalahan, Pengujian, dan Observabilitas yang Benar-Benar Bantu
Menyampaikan ke Produksi dengan Percaya Diri dan Kontrol
- Lingkaran Rilis yang Menahan
- Kontrol berperan sebesar besarnya seperti kebenaran

Mengapa API Tipe Gagal Setelah Diluncurkan dan Bagaimana Mencegahnya

Sebuah API yang tipe biasanya gagal selama rilis yang biasa. Satu tim mengubah nama bidang respons. Tim lain menambahkan cabang nullable untuk migrasi parsial. Klien yang lebih tua terus mengirimkan payload sebelumnya karena pembaruan mobile tertinggal di belakang web. TypeScript masih mengompilasi di setiap repo yang memperbarui tipe lokalnya. Kontrak di produksi sudah salah.

Kegagalan itu memiliki nama: kontrak drift.

Diagram yang menjelaskan tiga alasan utama mengapa API tipe gagal di lingkungan produksi setelah peluncuran awal.

TypeScript membuat API lebih menyenangkan, tapi juga membuat kontrak yang lemah lebih mudah dipercaya. Interface bersama, generics rute, dan API fetch Membantu pengembang selama pengembangan. Mereka tidak membuktikan bahwa JSON yang melintas melalui jaringan masih sesuai dengan jenis-jenis tersebut setelah rilis kedua atau kesepuluh.

Aturan yang berlaku di produksi sangat sederhana.

Jika JSON yang tidak divalidasi dapat mengalir langsung ke logika aplikasi, jenis TypeScript Anda menggambarkan niat, bukan kenyataan.

Solusi ini kurang tentang trik tipe yang cerdas dan lebih tentang di mana kebenaran berada:

Validasi di batas. Parse tubuh permintaan, parameter, header, dan bahkan respons layanan downstream sebelum bagian lain dari code menyentuhnya.
Petakan DTO ke model domain. Tetapkan bentuk transportasi terpisah dari objek bisnis sehingga API churn tidak menyebar ke seluruh basis kode.
Buat tipe dari kontrak. OpenAPI, JSON Schema, atau kerangka kerja skema pertama memberikan klien dan server sumber kebenaran yang sama.
Tangani perubahan yang memecah sebagai acara publik. Jika bidang berubah bentuk, versiinya secara sengaja dan komunikasikan seperti perubahan kontrak eksternal lainnya.

DTO mapping is the piece teams skip most often. It feels redundant at first. After a few releases, it becomes the layer that saves you from spreading string | null dan alias lapangan tradisi melalui setiap layanan dan layar depan. Langkah penerjemahan kecil di perbatasan lebih murah daripada refactor luas kemudian.

Versi membutuhkan disiplin yang sama. Tim jarang memecahkan klien dengan satu perubahan besar. Mereka memecahkan mereka dengan serangkaian perubahan lokal yang masuk akal yang menambahkan kompatibilitas. Strategi versi yang jelas untuk mengembangkan kontrak

Versioning deserves the same discipline. Teams rarely break clients with one dramatic rewrite. They break them with a series of reasonable local changes that add up to incompatibility. A clear Strategi versi API untuk mengembangkan kontrak Membangun Proyek TypeScript Anda dengan Benar

Proyek yang ditipekan biasanya terlihat bersih pada hari pertama. Enam bulan kemudian, satu jalur menerima input yang tidak terverifikasi, jalur lain membaca data mentah

Membangun Proyek API Anda dengan Benar

Sebuah API yang ditipekan biasanya terlihat rapi pada hari pertama. Enam bulan kemudian, satu route menerima input yang tidak terverifikasi, yang lain membaca data mentah process.envdan sebuah ketiga kembali membentuk sebuah bentuk yang tidak ada klien yang dikodekan. Bangunan itu jarang hancur semua sekaligus. Ia menciptakan cukup ruang untuk pergeseran kontrak untuk masuk ke dalam pekerjaan fitur normal.

Mulai dengan bentuk proyek yang membuat kontrak sulit untuk dilewati.

Foto seorang pengembang mengetik code di layar laptop menampilkan kesalahan TypeScript di terminal IDE.

Pilih kerangka kerja yang sesuai dengan bentuk tim

Untuk sebuah API di TypeScript, keputusan kerangka kerja pertama kurang tentang sintaks dan lebih tentang di mana disiplin kontrak akan berada.

Express cocok untuk tim yang ingin minimalisasi abstraksi dan sudah mengetahui model middleware. Ia tidak mengganggu, yang berguna sampai setiap jalur menciptakan konvensi validasi, bentuk kesalahan, dan konvensi respons sendiri.
Fastify adalah pilihan default yang kuat untuk tim backend kecil dan menengah. Sistem pluginnya bersih, dan ia memindahkan pekerjaan skema lebih dekat ke lapisan jalur, yang membantu menjaga perilaku waktu eksekusi sejalan dengan jenis.
Nest berfungsi baik untuk kodebase besar dengan banyak kontributor, modul bersama, dan batasan kepemilikan eksplisit. Biaya adalah upacara, dan biaya itu nyata jika layanan itu sendiri kecil.

Saya biasanya menghindari membeli kerangka kerja lebih dari yang tim akan gunakan. Layanan kecil dengan Fastify, library validasi, dan jenis kontrak yang dihasilkan sering bertahan dari refaktor lebih baik daripada stack yang lebih berat dengan konvensi yang tidak konsisten yang di atasnya.

Gunakan tata letak folder yang melindungi batasan

Tidaklah penting nama folder, tetapi tekanan import yang lebih penting. Jika rute dapat mencapai model database, atau layanan dapat mengembalikan entitas ORM langsung ke klien, maka kerangka sudah mengundang pergeseran.

Tata letak yang dapat bertahan di produksi biasanya memisahkan kekhawatiran transportasi dari kekhawatiran aplikasi:

src/routes untuk pengaturan kabel HTTP saja
src/schemas untuk skema permintaan dan respons
src/dto untuk jenis transportasi dan pemetaan code
src/services untuk kasus penggunaan dan koordinasi
src/domain untuk model bisnis yang harus bertahan lebih lama dari endpoint tunggal
src/clients untuk integrasi ke bawah
src/errors untuk jenis kesalahan bersama dan bantuan penyempitan
src/config untuk parsing konfigurasi waktu startup

itu src/dto layer bukanlah pekerjaan sampingan. Ini memberikan API tempat untuk menyerap perubahan eksternal tanpa membuatnya bocor ke logika domain atau keluar melalui endpoint yang tidak terkait.

Konfigurasi layak mendapatkan perlakuan yang sama. Parse variabel lingkungan sekali pada startup, gagal cepat pada nilai yang tidak valid, dan ekspor objek konfigurasi yang tipe-nya telah ditetapkan ke bagian aplikasi lainnya. Tim yang terus membaca process.env biasanya akan mengalami perilaku runtime yang bercabang yang tidak dapat membantu TypeScript. Panduan ini pada konfigurasi lingkungan merupakan referensi yang baik jika Anda perlu menetapkan pola tersebut.

Kompilator harus diperketat sebelum menambahkan fitur

A production API should make unsafe code annoying to write.

Default yang berguna termasuk:

strict aktif
useUnknownInCatchVariables aktif
noUncheckedIndexedAccess aktif jika tim dapat menangani disiplin ekstra
Tidak ada alias jalur kecuali Node, tes, pengompilan, dan tooling semua menyelesaikan mereka dengan cara yang sama
Mengisolasi build, typecheck, dan menscript lint di CI

Lebih lemah tsconfig biarkan mengumpulkan tidak terlihat. Satu yang ketat mengubah kesalahan menjadi pekerjaan yang terlihat sebelum mereka menjadi perilaku produksi.

Pedoman lint membantu juga, terutama pedoman terhadap any, janji-janji yang mengapung, dan ekspor tidak sengaja dari modul kontrak publik. Tidak ada yang menggantikan validasi waktu eksekusi, tetapi itu mengurangi jumlah tempat di mana kesalahan kontrak dapat disembunyikan.

Pilihan lain scaffolding yang penting adalah awal. Putuskan di mana spesifikasi OpenAPI akan datang dan jaga keputusan itu dekat dengan layer jalur. Beberapa tim menghasilkannya dari code-skema pertama. Lainnya menghasilkan stub server dan jenis dari spesifikasi pertama. Pendekatan mana pun dapat berfungsi. Yang gagal adalah menganggap spesifikasi sebagai hasil sampingan yang tidak pernah diperiksa setelah rilis pertama.

Setelah kerangka awal, membantu untuk membandingkan bagaimana kontrak yang ditipekan berperilaku di luar layanan permintaan-balasan biasa. Guida TypeScript Streamkap Flink bermanfaat untuk tim yang bekerja dengan stream atau sistem yang beratnya event, di mana pergeseran kontrak muncul di sepanjang pipa yang lebih panjang, bukan hanya di pengolah HTTP.

Mengatur DTO dan Mengvalidasi Input di Batas

Sebuah API yang ditipekan biasanya terlihat benar pada hari pertama. Enam bulan kemudian, bug muncul di batas. Klien mobile masih mengirimkan bidang yang lama. Seorang mitra mengabaikan properti yang frontend Anda asumsikan selalu ada. Refactor mengungkapkan kolom ORM internal di respons publik. TypeScript telah melakukan pekerjaannya di dalam kodebase. Kontrak masih berdrift.

Alasan itu, desain DTO sangat penting. Ini bukan tentang membuat tubuh permintaan terlihat rapi. Ini tentang menjaga jenis publik jujur setelah rilis pertama.

Kontrak publik dan model internal tidak boleh sama.

A DTO describes apa yang melewati kabel. A model domain Menggambarkan apa yang perlu dilakukan aplikasi untuk melakukan pekerjaan nyata. Menggabungkan kekhawatiran tersebut menyelamatkan beberapa baris kode awal dan menciptakan koneksi mahal kemudian.

Diagram yang menggambarkan desain dan validasi DTO untuk menjaga batasan sistem yang aman dan kontrak API.

Jika rute Anda menerima ini:

type CreateOrderRequestDto = {
  customerId: string
  items: Array<{ sku: string; quantity: number }>
  note?: string | null
}

Dengan string yang diperiksa, kuantitas yang diverifikasi, dan nilai default yang diterapkan dalam satu tempat. OrderDraft with normalized strings, validated quantities, and defaults applied in one place.

Biasanya batasan memerlukan langkah-langkah ini:

Mengurai isi pesan masuk
Mengvalidasi bentuk dan konstrain bidang
Mengubah DTO ke objek domain
Menggunakan logika bisnis pada objek domain
Mengubah hasil ke DTO respons
Mengvalidasi respons keluaran sebelum mengirimnya

Langkah keenam seringkali dilewati. Langkah ini juga menangkap bidang pribadi, nilai nullable yang terlewat ke dalam respons stabil, dan perubahan skema tidak sengaja selama refactor.

Mengvalidasi sebelum logika bisnis menyentuh data

Jenis tipe kompilasi tidak mengvalidasi JSON dari jaringan. Mereka juga tidak melindungi Anda dari layanan lain yang mengembalikan bentuk yang masih memenuhi unknown dan menghancurkan asumsi Anda pada waktu eksekusi.

Untuk API bekerja di TypeScript, Zod adalah pilihan umum karena mengurai pada waktu eksekusi dan menginfers jenis untuk bagian code lainnya. Valibot, io-ts, dan perpustakaan serupa juga dapat berfungsi. Perpustakaan yang lebih penting daripada aturan. Data tidak terpercaya diurai sebelum digunakan oleh bagian lain.

Polanya yang bertahan selama refactor seperti ini:

Ini adalah skema masuk Mengabaikan data permintaan yang rusak
Ini adalah skema dependensi Mengvalidasi respons dari API dan layanan internal ketiga
Ini adalah skema keluar Mengverifikasi respons yang akan diterbitkan oleh API

Layer tengah inilah di mana banyak API yang telah ditipekan gagal setelah diluncurkan. Tim mengvalidasi permintaan, mengabaikan validasi pada respons hilir, dan kemudian bertanya-tanya mengapa perubahan nama field vendor menjadi insiden produksi.

Ini adalah aturan praktis yang saya gunakan. JSON mentah berhenti di layer rute.

Peta code bukanlah sia-sia. Itu adalah tempat di mana pergeseran menjadi terlihat

Tim sering menolak pemetaan DTO karena terasa berulang. Saya telah melihat lawan di produksi. Layer pemetaan tipis adalah tempat perubahan kontrak menjadi jelas, dapat dilihat, dan lokal.

Misalnya:

transport memungkinkan note?: string | null
model domain mungkin menyimpan note: string dengan "" sebagai model default
DTO respons mungkin melewatkan note seluruhnya ketika kosong

Ada tiga kebenaran yang berbeda untuk tiga audiens yang berbeda. Menganggapnya sebagai satu interface yang sama menyembunyikan perbedaan sampai klien mengalami kesalahan.

Webhook membuat hal ini lebih jelas karena konsumen mungkin menjaga bentuk payload Anda selama bertahun-tahun. Jika tim Anda sedang bekerja melalui masalah tersebut, contoh desain payload webhook ini adalah mitra yang berguna. sebuah teman yang berguna.

Jenis tipe yang dibagikan hanya berguna ketika sumber kebenaran yang eksplisit

Menggandakan antarmuka backend ke frontend adalah proses yang membutuhkan waktu. Paket yang dibagikan dapat membantu, tetapi hanya untuk jenis yang sengaja dibuat publik.

Konfigurasi yang lebih baik dalam kodebase yang lebih besar terlihat seperti ini:

definisikan skema permintaan dan tanggapan publik secara terpisah dari model penyimpanan
generate OpenAPI dari skema publik tersebut, atau generate jenis server dari OpenAPI terlebih dahulu
tetapkan jenis kontrak yang dihasilkan dekat dengan handler dan klien
tetapkan jenis domain dan model ORM internal
versi DTO publik secara sengaja ketika kompatibilitas penting

Pemisahan itu juga konsisten dengan Pedoman Desain TypeScript dari tim Azure SDK,yang menekankan permukaan publik yang stabil dan menjaga detail implementasi internal tidak termasuk dalam kontrak.

Batasan yang dapat dipertahankan terlihat membosankan secara sengaja

Sebelumnya, frontend percaya

Sebelumnya, frontend mengandalkan fetch().json() as if it were truth, the backend returns ORM objects directly, and one shared interface tries to represent every layer. After, each boundary parses data, DTOs stay narrow, domain models stay internal, generated types cover the public contract, and mapping code makes changes explicit.

Menghadirkan upacara. Ini juga memberikan Anda satu tempat untuk memeriksa pergeseran sebelum pemanggil menemukannya untuk Anda.

Menghasilkan dan Mengonsumsi Klien Tipe Penuh API

Klien yang ditipekan sering terlihat selesai pada hari rilis. Tiga bulan kemudian, satu endpoint mulai mengembalikan bidang nullable, endpoint lainnya menambahkan cursor pagination, dan aplikasi mobile memasang versi kontrak yang lebih tua. Tipe TypeScript masih dapat dikompilasi. Pemanggil masih dapat gagal.

Itu adalah tugas lapisan klien. Lapisan klien harus menjaga kontrak yang diterbitkan menjadi benar setelah rilis pertama, bukan hanya membuat editor autocomplete terlihat baik.

Memilih strategi klien yang ditipekan

Bentuk klien harus sesuai dengan kompleksitas sebenarnya API, bukan preferensi tim.

Pilihan Terbaik	Kompromi	Perdagangan Off
Wrapper Pengambilan Data Tangan	Aplikasi kecil, alur autentikasi unik, iterasi cepat	Cepat untuk memulai. Mudah untuk memecah ke berbagai tempat panggilan selama waktu.
API code pembangunan	API REST yang sederhana dengan skema stabil	Basis yang kuat. Memerlukan bantuan untuk autentikasi kustom, streaming, atau pengaturan halaman yang tidak biasa
SDK-style klien yang ditetapkan	Platform multi tim, API publik, integrasi yang berlangsung lama	Biaya perawatan yang paling tinggi. Pengalaman konsumen terbaik ketika API adalah produk

Klien yang dibuat tangan bekerja untuk permukaan kecil

A custom plugin fetch wrapper is a reasonable choice when the API is internal, the surface area is small, or transport behavior matters more than schema generation. I still use this approach for admin tools and early-stage services.

The failure mode is drift. One team adds a retry rule in the wrapper. Another bypasses it. A third copies a response type into the frontend and widens it to any Setelah kesalahan pertama. Anda akhirnya memiliki panggilan "tipe" yang tidak lagi mewakili apa yang dikembalikan server.

Gunakan klien yang dibuat tangan ketika kondisi-kondisi berikut benar:

API adalah kecil dan internal
perubahan kontrak cukup sering sehingga menghasilkan ulang code menjadi kebisingan
pengaturan transportasi kustom menguasai pekerjaan
kamu siap untuk menjaga parsing waktu eksekusi di klien, bukan hanya annotasi TypeScript

Titik terakhir itu penting. response.json() mengembalikan data tidak diketahui pada waktu eksekusi, bahkan jika tanda tangan fungsi mengatakan sebaliknya.

Penghasilan OpenAPI adalah default yang praktis

Untuk REST API stabil, jenis yang dihasilkan memberikan rasio perawatan-keamanan yang terbaik. Mereka menghilangkan banyak jenis penulisan yang sama dan membuat perubahan kontrak terlihat dalam permintaan pull.

Polanya yang bertahan dari refaktor adalah sederhana. Buat dari kontrak publik, jaga lapisan yang dihasilkan tipis, dan tambahkan wrapper kecil di mana konsumen membutuhkan ergonomika yang lebih baik. Alur kerja penghasilan TypeScript OpenAPI cocok dengan model itu.

Penyebutan yang berguna terlihat seperti ini:

menghasilkan code menguasai bentuk permintaan dan respons
selubung tipis SDK menguasai injeksi autentikasi, ulang coba, dan bantuan halaman
validasi waktu eksekusi masih terjadi di batas server dan di mana saja input tidak terpercaya kembali ke sistem
pemetaan DTO tetap eksplisit sehingga perubahan model internal tidak menyebar ke kontrak klien

pendekatan hybrid itu menjaga code yang dihasilkan menjadi membosankan, yang baik. code membosankan lebih mudah untuk menghasilkan ulang, memeriksa, dan menggantinya.

Selubungi klien yang dihasilkan sebelum aplikasi code menyentuhnya

fungsi-fungsi yang dihasilkan biasanya terlalu kasar untuk digunakan secara luas di seluruh basis kode. Mereka mengungkapkan detail transportasi yang setiap pemanggil harus belajar kembali.

Selubung tipis memberikan Anda satu tempat untuk menjaga kebijakan konsisten:

menambahkan header default dan ID permintaan
menormalisir bentuk kesalahan
menampilkan halaman navigasi sebagai iterator atau metode bantuan
menggunakan autentikasi per-permintaan untuk kasus multi-tenant
Jaga jenis permintaan dan respons yang dihasilkan secara otomatis, bukan menulisnya secara manual

Contoh, aplikasi code harus memanggil client.orders.listAll() atau client.orders.list({ cursor })Tidak perlu membangun query string secara manual dan memproses metadata halaman per halaman.

Klien-klien dengan gaya SDK memiliki arti ketika produk API

Public APIs and shared platform services need more than generated endpoint functions. Consumers expect naming consistency, predictable errors, and transport details hidden behind methods that match the domain.

Klien yang baik biasanya memiliki ergonomi yang baik seperti ini:

client.orders.list() Ergonomika klien yang baik biasanya terlihat seperti ini:
client.files.stream() mengembalikan halaman yang tipe atau iterator async
auth can be set globally and overridden per request
autentikasi dapat diatur secara global dan diatasi per permintaan

Mengurangi biaya perawatan. Ini juga mencegah setiap tim konsumen merekonstruksi aturan batas yang sama dengan cara yang sedikit berbeda, yang merupakan cara kontrak drift menyebar.

A garis finish bukanlah garis finish. Garis finish adalah klien yang jenisnya masih sesuai dengan kenyataan setelah API berkembang, karena generasi dimulai dari kontrak publik, validasi waktu runtime melindungi batas, dan pemetaan DTO menjaga perubahan internal tidak menyebar ke luar.

Error Handling, Pengujian, dan Observabilitas yang Benar-Benar Bermanfaat

Contoh API TypeScript paling banyak adalah terlalu tenang. Permintaan berhasil, JSON sesuai dengan interface, dan gagal menjadi throw new Error("something went wrong"). Produksi tidak pernah berperilaku dengan sopan seperti itu.

Pertama-tama, perbaikan mekanis. Dalam TypeScript, nilai yang tertangkap harus dianggap sebagai unknownlalu dipersempit sebelum membaca message, stackatau properti respons. Panduan ahli juga merekomendasikan kelas kesalahan kustom, mempertahankan gagal asli dengan causemengvalidasi di batas-batas, mengnormalisasi lemparan non-Error, dan menambahkan konteks permintaan untuk observabilitas (Panduan pengelolaan kesalahan TypeScript).

An infographic detailing five best practices for writing resilient production code in a TypeScript environment.

Nerima kesalahan sebelum menyentuhnya

Belum aman catch block masih umum:

try {
  await client.orders.create(input)
} catch (error) {
  logger.error(error.message)
}

Namun itu mengasumsikan terlalu banyak. error mungkin tidak ada Error atau tidak ada.

Polanya yang lebih aman:

try {
  await client.orders.create(input)
} catch (error: unknown) {
  if (error instanceof Error) {
    logger.error({ message: error.message, stack: error.stack })
    throw new OrderSyncError("Order sync failed", { cause: error })
  }

  logger.error({ error })
  throw new OrderSyncError("Order sync failed", { cause: new Error("Non-Error thrown") })
}

Ini tampak sedikit lebih berat. Ini bertahan lebih baik ketika gagal datang dari SDK pihak ketiga, parsing JSON gagal, atau lemparan yang tidak terduga.

Coba ulangi hanya ketika kesalahan bersifat sementara

Perbaikan kedua yang besar adalah klasifikasi kesalahan. Pedoman untuk operasi TypeScript SDK dan API berkonvergen pada aturan yang jelas: ulangi kesalahan yang bersifat sementara seperti kesalahan jaringan atau respons HTTP 429 dan 503, validasi awal, simpan konteks kesalahan, dan hindari ulang untuk kesalahan aturan bisnis. Pedoman yang sama juga merekomendasikan Promise.all untuk pekerjaan parallel yang cepat gagal dan Promise.allSettled ketika kesuksesan sebagian saja dapat diterima (Pola penanganan SDK).

Saya suka tiga wadah:

Error validasi berarti permintaan salah sebelum meninggalkan proses Anda.
Error sementara mungkin berhasil lagi dengan backoff.
Error permanen merefleksikan aturan bisnis, izin, atau sumber daya yang hilang dan harus muncul langsung.

Klasifikasi itu menghasilkan code yang lebih baik daripada bantuan “coba lagi setelah gagal” yang umum.

Aturan lapangan: Ulang coba milik ketidakpastian transportasi, bukan perselisihan domain.

Opsiabilitas harus menjelaskan gagal, bukan hanya merekamnya saja

Log tanpa konteks tidak ada observabilitas. Untuk API di TypeScript, tambahkan ID korelasi, nama rute, metadata permintaan, dan bentuk kesalahan normalisasi di mana saja permintaan melintasi batas.

A baseline yang berguna:

ID Korelasi hubungkan permintaan masuk ke panggilan turunannya
Log Terstruktur simpan bidang, bukan blob teks
Catatan Perbatasan rekam gagal pars di terpisah dari kecuali bisnis
Pemberitahuan berdasarkan kelas kesalahan dan rute, bukan hanya status code volume

Jika aplikasi mobile atau klien Anda mengonsumsi API ini, perubahan observabilitas juga penting. Salah satu pilihan praktis di lapisan rilis adalah Capgoyang menyediakan API yang terdefinisi untuk mengirim dan mengikuti pembaruan hidup di Capacitor dan lingkungan Electron. Hal ini berguna ketika perbaikan kontrak sisi klien memerlukan peluncuran yang dikendalikan dan visibilitas per-versi daripada menunggu aplikasi lainnya di toko aplikasi secara buta. Untuk tim yang memperketat lingkaran feedback yang lengkap, panduan ini pada pengamatannya aplikasi cocok berada di samping logging sisi server.

Uji kontrak, bukan hanya implementasinya

Unit test sendiri tidak akan menangkap perubahan. Tambahkan tes di tempat perubahan terjadi.

Pengujian validasi batas: Masukkan input yang rusak ke dalam skema dan asert gagal bentuk.
Pengujian kontrak: Konfirmasi respons HTTP yang sebenarnya sesuai dengan kontrak yang dipublikasikan.
Pengujian asertsi kesalahan yang terdefinisi: Verifikasi gagal sementara dan permanen normalisasi dengan benar.
Pengujian integrasi klien: Pastikan klien yang dihasilkan atau dibungkus dapat memproses respons nyata.

Sebuah tes kuat untuk API yang tipe tidak hanya membuktikan jalur code. Ini membuktikan bahwa kontrak Anda masih berbicara kebenaran.

Menyampaikan ke Produksi dengan Percaya Diri dan Kontrol

Kualitas rilis berasal dari loop yang dapat diulang. Bukan heroik.

Sebuah API yang dapat diandalkan dalam pipeline TypeScript biasanya memiliki beberapa hal penting: pengecekan skema di CI, pengecekan tipe pada artefak yang dihasilkan, tinjauan perbedaan kontrak sebelum merge, dan jalur pengiriman yang dapat memperlambat atau mengembalikan ketika populasi klien tidak siap.

Loop rilis yang menahan

Saya suka menjaga checklist produksi singkat sehingga tim mengikuti:

Gagalkan CI pada perubahan kontrak: Jika OpenAPI berubah, jenis dan klien yang dihasilkan harus diperbarui dalam perubahan yang sama.
Bagikan kontrak yang bersama versi secara sengaja: Paket DTO publik memerlukan disiplin rilis, bukan refaktor santai.
Keluarkan melalui saluran atau kelompok: Don’t terapkan perubahan integrasi yang mengganggu secara bersamaan kepada setiap konsumen.
Pastikan rollback sederhana: Mengembalikan kontrak, klien, atau bundle web harus menjadi operasional yang membosankan.

Untuk tim yang berpindah infrastruktur dan alur pengiriman pada saat yang sama, panduan ini untuk pemindahan ke awan untuk pengembang adalah referensi perencanaan yang berguna karena API keandalan sering menurun selama transisi platform, bukan hanya selama code perubahan.

Kontrol sangat penting seperti kebenaran.

Habitan produksi terakhir adalah visibilitas oleh versi. Anda perlu tahu mana build klien yang memanggil mana kontrak, mana rilis yang berhasil diterapkan, dan mana kegagalan yang berkumpul setelah peluncuran. Hal itu sangat penting untuk konsumen mobile dan edge-distributed yang tidak semua mengupdate secara sekaligus.

Jika stack Anda termasuk Capacitor atau Electron, live update tooling dapat mengurangi kesenjangan antara memperbaiki bug kontrak dan mendapatkan perbaikan ke tangan pengguna. Bagian yang penting bukanlah ‘perbaruan yang lebih cepat’ secara abstrak. Itu adalah memiliki peluncuran berdasarkan saluran, perlindungan rollback, dan observabilitas pada tingkat versi agar perbaikan kontrak tetap terkendali.

API yang tipe akan tetap sehat ketika skema, validasi waktu eksekusi, penghasil klien, dan operasi rilis semua memperkuat satu sama lain. Lupa satu lapisan dan yang lainnya akan menggantikan dengan cara yang buruk.

Capgo gives teams shipping Capacitor and Electron apps a typed way to deliver web bundle fixes, control rollout channels, and monitor adoption and failures by version. If your API contract fixes also need to reach clients quickly without waiting on store review, visit Capgo.

API di TypeScript Cara Membangun API yang Siap Produksi dengan Tipe