$ go install github.com/Elagoht/collage/cmd/collage@latest
$ collage new <project_name>
$ cd <project_name>
$ go mod tidy
$ collage devSunucuda render edilen web için bir Go framework'ü
Sunucudan HTML, fragment fragment.
Sunucuda fragment'lerden render edilen, neye bağlıysa ona göre cache'lenen ve kısım kısım güncellenen page'ler. Tek bir Go binary'sinde.
Bir landing page, single-page app değildir
Bir ürün sayfası, bir landing page, tıklanacak pek bir şeyi olmayan birkaç sayfalık bir site: hiçbiri sunucuda bir JavaScript runtime'ına, bir client framework'üne ve bir hydration adımına ihtiyaç duymaz. Böyle bir runtime Go'dan yavaştır ve sunucuda daha fazla bellek ve disk tüketir. Client framework'ü ise tarayıcıya, doğrudan alabileceği HTML'i kurması için bir program gönderir. collage HTML'i gönderir.
Component değil, fragment
Bir page, fragment'leri saran bir layout'tur. Her fragment bir template ve kendi verisini çeken bir fonksiyondur. Kardeş fragment'ler verilerini aynı anda çeker, page yine de sırasıyla yazılır. Bir fragment'i WithFragmentPath ile kendine ait bir URL'de açın; üç satırlık bir fetch page'in yalnızca o kısmını yenisiyle değiştirir. Sunucudaki state sunucuda render edilir ve her seferinde bir fragment güncellenir.
fetch, XHR, server-sent events ve WebSocket tam da bunun için yapıldı. Script'i yazmak istemezseniz bir plugin fragment'leri belirli aralıklarla ya da sunucu push ettiğinde yeniler, isterseniz yerinde morph da eder. elagoht/live
collage.NewPage("search").
WithLayouts(layout).
WithContent(searchPage).
WithPath("en", "/search").
WithFragmentPath("en", "/search/results", results).
Build()input.addEventListener("input", async () => {
const res = await fetch("/search/results?q=" + encodeURIComponent(input.value));
document.querySelector("#results").outerHTML = await res.text();
});Layout'lar ve slot'lar
Layout, page'in içeriği için bir slot bırakır. Bir fragment da kendi slot'larını bırakabilir. Slot'ları fragment'lerle doldurun, collage page'i birleştirir.
Neye bağlıysa ona göre cache'lenir
Her page ve cache'lenen her değer, neyden oluştuysa onun tag'lerini taşır: post:hello, author:ada. InvalidateTags, bir tag'i kullanan page'leri stale olarak işaretler ve arka planda yeniden render eder, bu sırada eski page'i fallback olarak saklar. PurgeTags ise onları doğrudan siler; bu, bir daha asla gösterilmemesi gereken içerik içindir. Geri kalan her şey cache'te kalır.
app.InvalidateTags(ctx, "author:ada")
app.PurgeTags(ctx, "user:42")Tag ile invalidate edin
Bir page neyden oluştuğunu hatırlar. Bir tag'i invalidate edin, yalnızca onu kullanan page'ler yeniden render edilir; geri kalanı olduğu gibi kalır.
İstediğiniz kadar middleware ve plugin
Bir framework size tek bir middleware dosyası verip bir request'in ihtiyaç duyduğu her şeyi onun içinde elle zincirletiyorsa, collage'da app.Use'u istediğiniz kadar çağırabilirsiniz; her çağrı herhangi bir func(http.Handler) http.Handler alır. Her plugin de kendi middleware'ini getirir ve bunlar plugin'leri listelediğiniz sırayla çalışır. Çekirdek küçük kalır: session, spam koruması, canlı güncelleme, SEO ve metrikler plugin'dir. Kırk beş plugin yayımlanmış durumda. Kendi plugin'iniz ise ihtiyaç duyduğu hook'lara sahip bir Go tipidir.
app, err := collage.New(&collage.Config{
Plugins: []collage.Plugin{
session.New(session.Options{KeyEnv: "SESSION_KEY"}),
honeypot.New(honeypot.Options{KeyEnv: "HONEYPOT_KEY"}),
client.New(),
live.New(live.Options{}),
},
})
app.Use(requestID)
app.Use(auditLog)Teslimat ve operasyon
minimizercompressbundleopti-imagedeployprometheusotelhealthjobsaccesslog
Hâlâ Go yazıyorsunuz
İkinci bir dil de ikinci bir process de yok. Veri katmanınız Go kodunuzdur: veritabanı, kuyruk, dış API. Elinizdeki bir API'yi ya da servisi app.Handle ile collage'ın kendi mux'ına mount edersiniz. Page'lerin yanında, aynı middleware'lerin arkasında çalışır. Tek proje, tek binary.
api := http.NewServeMux()
api.HandleFunc("GET /api/users/{id}", users.Get)
api.HandleFunc("POST /api/users", users.Create)
app.Handle("/api/", api)Siteler ve web uygulamaları için küçük bir çekirdek
collage batteries-included değildir ve size neyi bıraktığını açıkça söyler. Sahip oldukları, sunucuda render edilen bir front end'in ihtiyaç duyduklarıdır. Bu yüzden çok kullanıcılı, rol bazlı bir web uygulaması da bir landing page kadar rahat yazılır: session'lar ve roller, sahtesi üretilemeyen form'lar, spam koruması, page'in canlı güncellenen kısımları.
Çekirdekte
- Fragment'ler ve fragment path'leri
- Forgery korumalı action'lar
- Cache, tag'ler, invalidate ve purge
- Private page'ler ve roller için guard'lar
- Locale URL'leri ve adla link'ler
- Static export
Bir plugin ile
- Session'lar
- Honeypot ve validation
- Flash mesajları
- SSE ya da WebSocket üzerinden canlı fragment'ler
- OAuth, basic auth, rate limit'ler
Dahil değil
- Backend: iş kuralları ve servisler sizin Go kodunuzdur
- ORM
- Migration'lar
- Veritabanı katmanı: o sizin Go kodunuz
Nasıl çalışır
Aynı anda çekin
Her fragment'in kendi data handler'ı vardır. Kardeş fragment'ler verilerini aynı anda çeker, HTML yine de sırasıyla yazılır.
Fragment'leri canlı stream edin
collage-live ile bir tag'i invalidate etmek, onu kullanan ve açık olan her fragment'i yeniden render eder ve tek bir stream üzerinden tarayıcıya gönderir. Yalnızca o kısım değişir. Örneğin burada, sunucunun CPU kullanımı.
Kaydedin ve görün
collage dev, bir template değiştiğinde tarayıcıyı yeniler, Go kodu değiştiğinde yeniden build eder. Başarısız bir render, dosyasını ve satırını tarayıcıda gösterir.
Build edin, export edin, serve edin
collage build, her işletim sistemi ve mimari için sitenin sunucusunun tamamı olan tek bir static binary üretir. collage export siteyi static dosyalar olarak yazar, collage serve de onları bir static host gibi serve eder.
Rehber
Başlarken
- Girişcollage neden var, neyin üzerine kurulu, size neyi bırakır ve ne zaman doğru araçtır.
- KurulumGo'yu ve collage CLI'ını kurun, collage new ile bir proje scaffold edin ve onu collage dev ile çalıştırın.
- İlk page'inizUygulamalı bir rehber: layout, data handler ve template ile tarif page'i kurar, slot'a ikinci bir fragment ekler, tarifleri static dosyalara export edersiniz.
- Page'in bir kısmını güncellemekPlugin'siz, uygulamalı bir rehber: öğeleri kendi URL'sinde bir fragment olan, form ve birkaç satır JavaScript ile yerinde güncellenen bir alışveriş listesi.
Temel kavramlar
- Page'ler ve layout'larPage nedir: layout'ları ve içeriği, kimin görebileceği, ona ulaşan path'ler, nasıl cache'lendiği, başarısız olunca ne gösterdiği ve register etmenin etkisi.
- Fragment'ler ve slot'larFragment'ler, sundukları slot'lar, bir fragment başarısız olduğunda ne olduğu ve render sırasında içerikten doldurulan slot'lar.
- Data handler'larFragment'in verisini nasıl çektiği: handler sözleşmesi, dependency tag'ler, 404'ler, eşzamanlılık, render context'i, timeout'lar, template'in veriyle kontrolü.
- Template'lerTemplate'lerin nerede durduğu, nasıl yüklenip binary'ye embed edildiği, development'ta nasıl yeniden yüklendiği; slot'lar, fonksiyonlar ve escaping.
Site kurmak
- Cachingcollage'ın render edilmiş page'leri ve onların dayandığı veriyi nasıl cache'lediğini, neyi atacağını nasıl bildiğini anlatır.
- Form'lar ve action'larForm post'larını, fetch çağrılarını ve webhook'ları action'larla karşılamak ve onları request forgery'ye karşı korumak.
- Link'ler ve locale'lerBir siteyi birkaç dilde sunmak ve page'lere adlarıyla link vermek; böylece link'ler page'i her locale'de takip eder.
- Head ve SEOTitle'ları, meta tag'leri, stylesheet'leri ve structured data'yı onları bilen fragment tanımlar, layout yerleştirir.
- Static asset'lerStylesheet'leri, script'leri, görselleri ve indirilecek dosyaları bir dizinden ya da gömülü bir dosya sisteminden, bir yıl cache'lenebilen URL'lerle sunmak.
- Document'lar: sitemap'ler, feed'ler, robots.txtSitemap'ler, feed'ler, robots.txt ve JSON gibi HTML yerine byte dönen route'lar, page'ler gibi cache'lenir ve invalidate edilir.
- Middleware ve kendi API'nizapp.Use ile standart net/http middleware'leri, collage.Vary ile bir header'a bağlı cache key'leri ve app.Handle ile kendi http.Handler'ınız.
- Preview'larEditörlere yayımlanmamış taslakları gerçek sitede gösterin. Cache editöre yayımlanmış page'i, başka hiç kimseye de taslağı sunmaz.
Yayına almak
- Static exportSiteyi collage export ile static dosyalara render edin: nelerin yazıldığı, nelerin neden atlandığı, dynamic path'ler ve bir static host'ta yayımlama.
- DeploymentBinary'yi build edin, bir container'da ya da systemd altında çalıştırın, production'ın ihtiyaç duyduklarını ayarlayın ve TLS'in arkasına koyun.
- Güvenlikcollage'ın request forgery'ye, open redirect'lere, path hilelerine, cache sızıntılarına ve aşırı büyük body'lere karşı yaptıkları ve size bıraktıkları.
- Test yazmakGerçek uygulamayı app.Handler() ve cookie saklayıp form'ları tarayıcı gibi gönderen pkg/collagetest ile test edin: page'ler, form'lar, document'lar, export.
Genişletmek
- Plugin kullanmakBir plugin'in neler yapabildiği, bir plugin'in nasıl register edilip yapılandırıldığı ve ne işe yaradıklarına göre gruplanmış, yayımlanmış kırk altı plugin.
- Plugin yazmakPlugin sözleşmesi, Host ve ConfigHost'un sundukları, her hook ve neyi değiştirebileceği, testleriyle birlikte eksiksiz bir plugin.
- Plugin yazmak: repository sözleşmesicollage plugin add'in repository'yi kurması için gerekenler (ad, manifest, ayar istemeyen bir New, release tag'i) ve collage plugin check'in bunu doğrulaması.
Referans
- collage CLIcollage CLI'ın new, add ve dev'den plugin, ai, completion ve man'e kadar bütün komutları, flag'leri ve her birinin neyi çalıştırdığı.
- Configcollage.Config ve alt struct'larının her alanı, varsayılan değerleri ve validation'ın neleri kontrol ettiği.
- Template fonksiyonlarıBuilt-in template fonksiyonlarının tamamı (slot, hoist, asset, URL fonksiyonları, json, aritmetik, string'ler ve listeler), imzaları ve örnekleri.
- Hatalarcollage'ın export ettiği bütün error değerleri, nereden geldiklerine göre gruplanmış hâlde; her birinin ne anlama geldiği ve ne yapmanız gerektiğiyle birlikte.