node.js - JSON şeması, TypeScript türleri ve çalışma zamanı doğrulayıcıları dahil olmak üzere API istek/yanıt şekilleri için tek kaynak mı?

JSON girişlerini (POST gövdeleri olarak) alan ve JSON yanıtları döndüren uç noktaları olan tipik bir Node.js REST servisi yazıyorum.

Bu üç şeyi istiyorum:

  1. Uç noktalarım için istek gövdeleri ve yanıt gövdelerinin şekillerini tanımlayan JSON şemaları. (Veya Swagger dosyaları ya da istemciler için sözleşmeyi tanımlamak için uygun olan herhangi bir şey.)
  2. JSON şemalarını mükemmel şekilde yansıtan TypeScript türleri/arayüzleri.
  3. Kendi işleyicilerimden çağırabileceğim, bir nesnenin doğru şekilde olup olmadığını doğrulamak için çalışma zamanı doğrulama fonksiyonları. (Ve bir giriş nesnesi doğrulandıktan sonra, TypeScript kodum onun arayüzünü bilmelidir.)

Ama bu üç bileşenin senkron dışına çıkmasını önlemek için tek bir doğruluk kaynağı istiyorum. Bu yüzden sadece bunlardan birini (ya JSON Şemaları ya da TypeScript tipleri) elle yönetmek istiyorum. Diğer iki bileşen, elle yazılmış olandan üretilmeli ve sürüm kontrolüne gönderilmemelidir.

Bunun günümüzde oldukça yaygın bir gereksinim seti olması gerektiğini hissediyorum, ama bununla ilgili internette pek bir şey bulamıyorum. Belki de bunu araştırmak için yanlış arama terimlerini kullanıyorum. Bu hedefi ele alan herhangi bir çerçeve veya standart bir desen var mı, yani girdi üzerinde sıkı doğrulama, standartlaştırılmış şema dokümantasyonu ve TypeScript'te tamamen tiplenmiş nesnelerin tüm kolaylıklarını sağlayan JSON API tanımlama hedefi?

Cevap #1

Ön uç ve arka uçta TypeScript kullandığınızı varsayıyorum.

Özel Tür Yeniden Kullanımı

Diyelim ki üç ana klasör içeren bir proje deposuna sahibiz: client, server ve shared.

shared içinde, tüm özel tür tanımlarınızı içeren bir Types.ts dosyanız var. Örneğin:

export interface Person {
  name: string;
  age: number;
}

Artık bu türleri herhangi bir alt klasörden, örneğin .\client\src\components\SomeComponent.ts veya sunucudan .\server\src\api\SomeRoute.ts şu şekilde içe aktarabilirsiniz:

import { Person } from `..\..\..\..\shared\Types.ts`;

Böylece, sunucu ve istemcide proje genelinde kullanılabilecek tür tanımları için tek bir yere sahip olursunuz.

JSON Modeli ve Belgeleme Üretimi

API'nizi belgelemek için ts-doc yorumlarını kullanabilir ve bir markdown belgesi oluşturmak için ts-docs-gen kullanabilirsiniz.

Alternatif olarak typedoc kullanılabilir. TypeDoc, TypeScript kaynak kodundaki yorumları HTML belgelerine veya bir JSON modeline dönüştürür. Sadece ilgili API dosyalarının dikkate alınacağı şekilde yapılandırabilirsiniz.

Çalışma Zamanı Doğrulaması

Girdi ve çıktının çalışma zamanı doğrulaması ile ilgili olarak, her tür için kendi doğrulama fonksiyonunuzu yazabilirsiniz; bunu stereobooster bu makalede açıklıyor: pragmatic-types-io-validation-or-how-to-handle-json-based-apis-in-statically-typed-language. Ya da io-ts gibi bir kütüphane kullanabilirsiniz.

Muhtemelen hepsi için uygun tek bir araç yoktur, çünkü neyi başarmak istediğinizin tam gereksinimlerine büyük ölçüde bağlıdır. Bu nedenle, farklı araçlardan oluşan araç setinizi oluşturmak sizi doğru yönde yönlendirmelidir. Size iyi çalışan bir kurulum bulduysanız, kendiniz bir cevap paylaşmaktan çekinmeyin.

Cevap #2

Projeler için tüm JSON verilerinin JSD şemaları aracılığıyla tanımlandığı bir desen fikrini seviyorum. JSD şeması SÖZLEŞMEDİR. JSD'leri Kafka konularına (Avro formatları yerine), Mongo'ya bağlayabilir veya bunları dilinizin kullandığı herhangi bir JSON doğrulama kütüphanesinde kullanabilirsiniz (örneğin .NET dünyasında Newtonsoft gibi). JSD, dil bağımsız sözleşmelerin kutsal kâresidir. Burada kabul edeceğim bir nokta, gRPC ve Protobuf ile ikili verilerin hız avantajlarına sahip olduğudur ve dikkate alınmalıdır. Ayrıca, verinin yüzde 99'unun JSON gövde iş verisi olduğunu ve bu desen kullanılarak yapılabileceğini görüyorum. Özet: JSD'nizi oluşturun, yazılım sisteminizin herhangi bir katmanında doğrulama için kodunuzun referans alabileceği bir yere (web sitesi konumu) koyun.

İlgili makaleler