Frontend Platformu için Golden Path: İskelet, Paylaşılan Paketler ve Görev CLI'si

Bir organizasyon çok sayıda küçük frontend uygulaması işlettiğinde, her ekip farklı bir iskeletten başlar ve build yapılandırması, lint kuralları ile dağıtım şekli birkaç sprint içinde birbirinden kayar. Bu kayma tembellikten değildir: bir uygulamayı başlatmanın standart yolunun aynı zamanda en hızlı yolu olduğu tek bir yer yoktur, bu yüzden her ekip temelleri yeniden kurar ve gözlemlenebilirliği, i18n’i ve dağıtımı biraz farklı şekilde yeniden uygular. Çözüm, üç temel taştan kurulan ince bir asfalt yoldur (bir golden-path iskeleti, sürümlü paylaşılan paketler ve bir görev CLI’si); işe yaradığını kanıtlayan tek ölçüt ise zorunlu tutulması değil, gönüllü benimsenmesidir.

Ekipler Arası Kayma Neden Birikir#

Kaymanın nedeni yapısaldır. Standart kurulum araçlarda değil dokümantasyonda yaşadığında, her yeni uygulama tüm kurulum maliyetini yeniden öder, bu yüzden ekipler en yakın mevcut repoyu kopyalar ve derlenene kadar düzenler. Özellikle dört maliyet üst üste binerek büyür:

• Build yapılandırması, lint kuralları ve test eşikleri, paylaşılan bir kaynaktan genişletilmek yerine kopyalandığı için birbirinden ayrışır. Bir kural değişikliği o zaman N repoda N düzenleme gerektirir.
• Gözlemlenebilirlik, i18n ve dağıtım manifestoları uygulama başına yeniden uygulanır, bu yüzden platform genelindeki bir değişiklik tek bir migrasyon yerine N bağımsız migrasyon haline gelir.
• Paylaşılan UI ve tasarım token’ları her uygulamaya çatallanır ya da kopyalanır, bu yüzden bir tasarım değişikliği hiçbir zaman her yere aynı anda inmez.
• Kimlik bilgilerini almanın, servis token’larını takas etmenin ve dağıtım yapmanın adımları bir araçta değil birinin shell geçmişinde yaşar, bu yüzden yeni bir uygulamayı ya da mühendisi devreye almak günlerce kopyala-yapıştır ve hata ayıklama gerektirir.

Daha fazla dokümantasyon ya da daha sıkı bir inceleme listesi bu açığı kapatmaz. Çözüm, standart yolu en az dirençli yol haline getirmektir; öyle ki bir ekip ona uzanır çünkü kendi yolunu kurmak daha yavaştır. Asfalt yol fikri budur ve Netflix bunu açıkça ifade eder: asfalt-yol araçlarının benimsenmesini zorunlu kılmaz, bunu “bu teknolojilerle geliştirme ve operasyonun, onları kullanmamaktan çok daha iyi bir deneyim olmasını sağlayarak” kazanır (Full Cycle Developers at Netflix (yeni sekmede açılır)). Spotify aynı fikri, parçalanmayı azaltan ve ekiplerin “daha az karar vermesini” sağlayarak yaratıcılığı daha yüksek hedeflere yönlendiren bir Golden Path olarak çerçeveler (How We Use Golden Paths (yeni sekmede açılır)).

Yolun sahibi platform ekibidir; ürün ekipleri onun üzerinde ilerler. Gözlemlenebilirlik, i18n, dağıtım şekli ve tasarımda tutarlılık, her ekibin yeniden icat ettiği bir şey olmaktan çıkıp varsayılan durum haline gelir. Yol, Team Topologies anlamında bir üründür: bir platform ekibi, onu tüketen ekiplerin “teslimatını hızlandıracak ikna edici bir iç ürün” kurar (Team Topologies Key Concepts (yeni sekmede açılır)). Aşağıdaki üç temel taş, o ürünün en ince versiyonudur.

Golden-Path İskeleti#

İlk temel taş, ilk klonlamada üretime hazır olan bir başlangıç reposudur. Bir ekip onu klonlar, uygulamayı yeniden adlandırır ve herhangi bir özellik kodu yazmadan önce çalışan bir build, lint, test, bileşen atölyesi ve dağıtım manifestosuna sahip olur. İskelet, donmuş bir anlık görüntü üreten bir oluşturucu yerine klonla-ve-başla bir monorepodur; çünkü bir araya getirdiği şeyler, ürettiği dosya ağacından daha önemlidir.

Faydalı bir iskelette neler bulunur:

• Monorepo çalışma alanı araçları. Bu hâlâ canlı bir tercihtir. lerna kendini artık “JavaScript monorepoları için orijinal araç” ve “Nx tarafından desteklenen hızlı, modern bir build sistemi” olarak tanıtır (lerna.js.org (yeni sekmede açılır)), yani modern hikâye lerna artı Nx önbelleğidir; lerna’yı bırakma yönündeki eski tavsiye projenin bugünkü hâline uymuyor. Alternatifler, görev grafiği ve hesaplama önbelleği olan akıllı bir build sistemi olan tek başına Nx (Nx intro (yeni sekmede açılır)) ve önbellekleyen başka bir monorepo build sistemi olan Turborepo’dur (Turborepo docs (yeni sekmede açılır)). Bir görev çalıştırıcı ve bir sürümleme aracı seçin; başarısızlık modu, ikisi de yayını sahiplenmeye çalışan iki aracı birlikte çalıştırmaktır.
• Paylaşılan TypeScript ve lint/format yapılandırması, kopyalanmadan genişletilerek. İskelet, kuralları içine gömmek yerine paylaşılan registry’den yayınlanan bir yapılandırmayı genişletir, böylece bir kural değişikliği bir kez gönderilir ve uygulamalar yükseltmede onu çeker.
• Kapsam eşikleri yerleşik test kurulumu. Alt sınırı yol zorunlu kılar; ekip, onun üzerinde neyi test edeceğine kendisi karar verir.
• Önceden bağlanmış bir bileşen atölyesi. Storybook “UI bileşenlerini ve sayfalarını izole halde kurmak için bir frontend atölyesidir” (Storybook docs (yeni sekmede açılır)); mevcut ana sürüm hattı Storybook 10’dur ve npm create storybook@latest ile iskelet kurulur. Sabitlemeden önce araç zincirinizdeki tam yamayı doğrulayın.
• Standartlaştırılmış bir dağıtım manifestosu. Bunu, her uygulamanın gönderdiği bir delivery.yaml olarak genelleştirin; böylece gözlemlenebilirlik, i18n ve yönlendirme ekip başına değil varsayılan olarak bağlanır.

Bir iskelet kurma komutu, sıradan bir klonlama artı yeniden adlandırma adımı gibi görünür:

git clone <skeleton-repo> my-app && cd my-app
node ./scripts/rename-app.mjs my-app
npm install
npm run dev

Bir dağıtım manifestosu, eskiden uygulama başına farklılaşan dağıtım şeklini taşır. Genelleştirildiğinde uygulamayı, çalışma zamanını ve yolun varsayılan olarak bağladığı kesişen kaygıları adlandırır:

# delivery.yaml
app: my-app
runtime: node-20
observability:
  tracing: enabled
  logs: structured
i18n:
  default: en
  locales: [en, tr]
routing:
  base_path: /my-app

Manifesto, uygulama ile yol arasındaki sözleşmedir. Her uygulama aynı şekli bildirdiği için, gözlemlenebilirliğin ya da yönlendirmenin nasıl sağlandığına dair platform genelindeki bir değişiklik, her uygulamayı tek tek düzenlemek yerine yolu düzenler.

Sürümlü Paylaşılan Paket Registry’si#

İkinci temel taş, uygulamaların semver ile tükettiği paylaşılan bir paket registry’sidir: bir UI bileşen kütüphanesi, bir tasarım-token paketi ve bir istek istemcisi ile sunucu ara katmanı gibi küçük paylaşılan yardımcılar. Anahtar özellik, bağımsız sürümlemedir. Platform yeni bir sürüm gönderir; ekipler onu kendi temposunda çeker. Özerkliği koruyan budur: yol sürümlüdür, bu yüzden hiçbir yükseltme küresel bir yeniden inşayı zorunlu kılmaz.

Bağımsız sürümleme, changelog otomasyonu gerektirir. changesets “monorepolara odaklanarak sürümleme ve changelog’ları yönetmek için bir araçtır” (changesets (yeni sekmede açılır)); bir katkıda bulunan bir niyet kaydeder ve araç, sürüm anında sürümleri ve changelog’ları hesaplar. Proje birden fazla dal sürdürdüğü için benimsemeden önce kurulumunuzda hangi sürüm hattının GA olduğunu doğrulayın. lerna da aynı iş için lerna version ve lerna publish sunar. Birini seçin ve ikisini birlikte çalıştırmayın, yoksa sürüm artışları birbiriyle çatışır.

Bir changesets adımı, sürüm akışının kısa, çalıştırılabilir bir parçasıdır:

npx changeset            # bir niyet kaydet: hangi paketler değişti, hangi artışla
npx changeset version    # artışları uygula ve changelog'ları yaz
npx changeset publish    # değişen paketleri registry'ye yayınla

Semver sözleşmesi yük taşıyan kısımdır. Ayrıştırılmış benimseme şu demektir: paylaşılan UI kütüphanesindeki bir düzeltme bir kez yayınlanır, her uygulama da onu kendi yükseltme takviminde alır. Maliyeti sürüm dağınıklığıdır (aşağıda Trade-off’lar bölümünde); bu bedeli karşılayan şey özerkliktir: ekip hangi sürümde çalıştığına ve ne zaman geçeceğine kendisi karar verir.

Görev CLI’si#

Üçüncü temel taş, tekrarlayan komut dizilerini saran bir görev CLI’sidir: kimlik bilgilerini almak, servis token’larını takas etmek, kümeyle etkileşmek ve ortak build ile dağıtım adımlarını çalıştırmak. CLI yolun giriş rampasıdır: ezberlenen bir shell dizisi yerine tek bir komut.

Düz çizgi yoldur; kesik çizgi, yol olmadan ne olduğudur. CLI önemlidir çünkü kişiye bağlı bilgiyi shell geçmişinden çıkarıp tüm organizasyonun paylaştığı ve platform ekibinin sürdürdüğü bir araca taşır. Dağıtım yolu, birinin hatırladığı bir dizi değil, dokümante edilmiş bir deploy alt komutu olduğunda, o diziye yapılan platform genelindeki bir değişiklik CLI’de gönderilir ve her ekip bir sonraki çekişte onu alır.

CLI, yolun ergonomik avantajının ilk günden hissedildiği yerdir.

İnce Yoldan Ne Zaman Sapmalı#

İnce yol varsayılandır ve iki sapma durumu adlandırmaya değer.

Keşfin kendisi bir maliyet haline geldiğinde bir geliştirici portalı ekleyin. Backstage, bir yazılım kataloğu üzerine kurulu, “yeni projeleri başlatmak ve araçları standartlaştırmak” için Software Templates ve dokümantasyon için TechDocs içeren, “geliştirici portalları kurmak için açık kaynaklı bir çerçevedir” (What is Backstage? (yeni sekmede açılır)). Bir portal, çok sayıda uygulama arasında doğru uygulamayı, sahibi ya da şablonu bulmak başlı başına bir sorun haline geldiğinde ağırlığını hak eder. O eşiğin altında, bir iskelet reposu artı bir CLI daha hafif ve daha hızlıdır ve portal kimsenin istemediği bir yüktür. Tetik, tek başına uygulama sayısından çok keşif maliyetidir: net sahipliği olan on uygulamanın portala ihtiyacı olmayabilir, sahipliği belirsiz dağınık bir uygulama envanterinin ise vardır.

Riskler düzenleyici ya da güvenlik açısından kritik olduğunda teşvik etmek yerine zorunlu kılın. Varsayılan teşvik etmektir, ama bazı bağlamlarda zorunlu kılma meşrudur. Standartlaştırma gücü üzerine yazılanlar, asfalt yolları ve golden path’leri korkuluklardan ve raylardan ayırır: hafif biçimler bir tercihi teşvik eder, güçlü biçimler onu kısıtlar (mia-platform: Paved Roads, Golden Paths, Guardrails and Railroads (yeni sekmede açılır)). Düzenlemeye tabi bir alanda, zorunlu bir dağıtım şekli ya da gerekli bir denetim kancası, katılığına değen bir korkuluktur. Pratik kural: ayrışmanın gerçek risk yarattığı yerlerde kapsam tabanlarını ve dağıtım şeklini zorunlu kılın; bileşen kompozisyonunu ve iş mantığını ekiplere bırakın.

Teşvik etmek önerilen daldır çünkü zorunlu bir yol, aynı zamanda daha kolay yol değilse gölge iskeletler üretir. Zorunlu kılmak risk dalıdır ve yalnızca risklerin katılığı haklı çıkardığı yerlerde meşrudur.

Bu, frontend’e özgü bir asfalt yoldur: iskelet kurma, sürümlü UI paketleri ve bir görev CLI’si; kapsamı genel bir altyapı self-servis platformundan daha dardır. Kaynak sağlama, ad alanları ve küme erişimi gibi altyapı platformu kaygıları komşudur ve zaten var olabilir; frontend yolu onların üzerinde oturur, uygulamaların nasıl kurulduğunu ve gönderildiğini standartlaştırır, işlem gücünün sağlanmasını ise alttaki katmana bırakır.

Trade-off’lar#

Her temel taş, baştan adlandırmaya değer bir maliyet taşır.

Temel taş	Ana fayda	Ana maliyet / başarısızlık modu
Golden-path iskeleti	Dakikalar içinde üretime hazır klon	Anlık görüntü çürümesi: iskelet dogfood edilmedikçe iskeletler eskir, üretilen uygulamalar güncel yoldan ayrışır
Sürümlü paketler	Bağımsız, ayrıştırılmış benimseme	Sürüm dağınıklığı: platform genelindeki bir düzeltme yine de ekiplerin yükseltmesini gerektirir, böylece eski sürümler kalır
Görev CLI’si	Kişiye bağlı bilgi paylaşılan bir araca dönüşür	Tek hata noktası ve bakım yükü; soyutlama, bir mühendisin hata ayıklarken görmesi gerekeni gizleyebilir

İskelet trade-off’u en keskin olanıdır. Donmuş bir anlık görüntü üreten bir iskelet, üretildiği anda eskir ve uygulamalar yeniden özel yapıma doğru kayar. Hafifletme, iskeleti dogfood etmek (platform ekibi ondan gerçek uygulamalar kurar) ve yapılandırmayı registry’den genişletilmiş biçimde tutmaktır; uygulama reposunda kopyalanmış kural dosyası kalmaz, böylece bir yükseltme bir sonraki çekişte her uygulamaya ulaşır.

Sık Yapılan Hatalar#

Dört hata tekrar eder, her biri somut bir düzeltmeyle.

• Zorunlu ama daha kolay değil. Platform gereklidir ama kendi yolunu kurmaktan daha yavaştır, bu yüzden ekipler isteksizce uyar ya da gölge iskeletlerle etrafından dolaşır. Düzeltme: giriş rampası süresini ana sinyal olarak ele alın, yönetişim eklemeden önce sürtünmeyi giderin ve benimsemeyi gönüllü bırakın; böylece direnç, gizli geçici çözümler yerine düşük benimseme olarak yüzeye çıkar.
• Büyük patlama platformu. Kimsenin istemediği, varsayılan ihtiyaçlara göre tasarlanmış “tam” bir platform göndermek. Düzeltme: en ince uygulanabilir platformu gönderin ve onu gerçek talepten büyütün; Team Topologies’in Thinnest Viable Platform fikri.
• Eşzamanlı yükseltmeler. Her uygulamayı aynı anda en son paket sürümüne zorlamak, semver sözleşmesinin korumaya çalıştığı özerkliği yok eder. Düzeltme: semver artı bağımsız benimseme; uygulamaların ne kadar geride çalıştığına dair görünürlükle, böylece platform ekibi zorlamadan teşvik edebilir.
• Platformu proje saymak. Yolu, iç müşterileri olan sürekli bir ürün yerine tek seferlik bir teslimat olarak ele almak. Düzeltme: platform-as-a-product; başarı ölçütü gönüllü benimseme ve ürün ekipleri, talepleri geri besleme döngüsü olan müşterilerdir.

Kapanış#

Ekipler arası kaymanın biriktiği, çok sayıda frontend uygulaması işleten bir organizasyon için ince asfalt yol (bir golden-path iskeleti, sürümlü paylaşılan paketler ve bir görev CLI’si) doğru varsayılandır. Bir geliştirici portalına yalnızca uygulamalar arası keşif başlı başına bir maliyet haline geldiğinde uzanın ve zorunlu kılmaya yalnızca ayrışmanın düzenleyici ya da güvenlik riski yarattığı yerde başvurun. Tek bir sonraki adım, bugün yeni bir uygulamanın giriş rampası süresini ölçmektir; dakikalar yerine günler sürüyorsa, o boşluk yolun ilk işidir.

Kaynaklar#

• Full Cycle Developers at Netflix (yeni sekmede açılır) - Kanonik asfalt-yol duruşu: araçlar zorunlu kılınmaz, onları daha iyi deneyim haline getirerek teşvik edilir.
• Spotify Engineering: How We Use Golden Paths to Solve Fragmentation (yeni sekmede açılır) - “Golden path” çerçevesinin kökeni: parçalanmayı azalt, daha az karar.
• Team Topologies Key Concepts (yeni sekmede açılır) - Dört ekip türü; iç ürün olarak platform ekibi; Thinnest Viable Platform fikri.
• What is Backstage? (yeni sekmede açılır) - Yazılım kataloğu, Software Templates ve TechDocs içeren geliştirici-portalı çerçevesi; büyük organizasyonlar için sapma durumu.
• What is platform engineering? (yeni sekmede açılır) - İç geliştirici platformu disiplininin topluluk tanımı.
• Nx: What is Nx? (yeni sekmede açılır) - Görev grafiği, hesaplama önbelleği ve modül-sınırı uygulaması olan akıllı monorepo build sistemi.
• Turborepo docs (yeni sekmede açılır) - Önbellekleyen alternatif monorepo build sistemi.
• Storybook docs (yeni sekmede açılır) - “UI bileşenlerini ve sayfalarını izole halde kurmak için bir frontend atölyesi”; mevcut ana sürüm hattı Storybook 10.
• changesets (yeni sekmede açılır) - Monorepolara odaklanan sürümleme ve changelog aracı; katkıcıların kaydettiği değişiklik niyetleri üzerine kurulu.
• lerna (yeni sekmede açılır) - Orijinal JavaScript monorepo aracı, artık Nx ekibi tarafından sürdürülüyor ve “Nx tarafından destekleniyor”.
• mia-platform: Paved Roads, Golden Paths, Guardrails and Railroads (yeni sekmede açılır) - Standartlaştırma gücünün bir sınıflandırması; zorunlu-kılma ile teşvik-etme gerilimi için faydalı.