Bu durum için icat edilmiş eğitici bir örnek değil. Aşağıdaki her kod parçacığı, Aurabase kökü Cargo.toml'den ve bugün depoda mevcut olan sandık bildirimlerinden gelir; bu makale için bunları yeniden okurken bulduğumuz ve yayınlanmadan önce sessizce düzeltmek yerine olduğu gibi belgelediğimiz iki tutarsızlık da dahil.
- Aurabase root Cargo çalışma alanı 18 açık üye bildirir: 11 hizmet,
aura-cliCLI, 5 paylaşılan kütüphane veaurabase-rsSDK —resolver = "2"ve tek birCargo.lockaltında. [workspace.dependencies]paylaşılan sürümleri merkezileştirir; her sandık kendi numarasını ayarlamak yerine{ workspace = true }ile miras alır - bir sandığın sessizce geçersiz kılınması durumu hariç.services/altındaki bir klasör, otomatik olarak çalışma alanının bir üyesi değildir:memberslistesi, tam olarak Rust olmayan kodu hariç tutabilmek için bir glob değil, açık bir listedir.[profile.release]tüm çalışma alanına yalnızca bir kez uygulanır;panic = "unwind"gibi bir seçim aynı anda on bir hizmetin tamamına uygulanır.
Hizmet başına bir depo mu, yoksa yalnızca bir Cargo.lock mu?
Bir çalışma alanı Cargo birden fazla kasayı tek bir Cargo.lock ve tek bir hedef dizin altında gruplandırır; bu, Rust paket yöneticisinin bu durum için sağladığı işlevselliktir. Her biri kendi deposunda bulunan on bir ayrı Rust ikili dosyası ilk bakışta daha bağımsız görünüyor. Pratikte bu, on bir farklı Cargo.lock, zaman içinde farklılık gösterebilecek on bir sürüm çözünürlüğü anlamına gelir ve iki hizmetin aynıaxum veya sqlx sürümünü derleyeceğinin garantisi yoktur.
A Cargo workspace solves this at the package manager level, not the team discipline level. All members share a single Cargo.lock at the root: a common dependency is resolved once, to an identical version, for the entire graph. This is also what makes a cross-service refactor (changing a signature in aura-core, for example) visible to a single cargo build --workspace, rather than discovered service by service in production. This is one of the choices that distinguishes our 100% unified Rust core from a heterogeneous stack assembled service by service.
Cargo.toml kökü: çözümleyici ve üyeler
Her şey [workspace] bildirimi ve onun members listesiyle başlar. Aurabase adresinde bu liste, services/* gibi genel bir kalıp tarafından oluşturulmak yerine, rollere (hizmetler, araçlar, kütüphaneler) göre gruplandırılarak elle yazılmıştır.
[workspace]
resolver = "2"
members = [
# Hizmetler
"services/aura-gateway",
"services/aura-auth",
"services/aura-db",
# … 8 diğer hizmet (aura-gerçek zamanlı, aura-depolama, aura-ai, …)
# Araçlar
"aura-cli",
# Kitaplıklar
"libs/aura-core",
# …4 diğer kitaplık
"aurabase-rs",
]
resolver = "2" kozmetik bir detay değildir. Cargo'nun çözümleyici v2, build-dependencies işlevselliğini ve hedefe özgü bağımlılıkları (örneğin target.'cfg(windows)') grafiğin geri kalanından yalıtır; bunlar artık son ikili dosyaya sızmaz. Ayrıca, çalışma alanının onu paylaşan tüm üyeleri arasında aynı bağımlılığın sürümlerini birleştirir: tek bir axum, yalnızca bir kez, on bir bağımsız çözüm değil.
workspace.package: tek sürüm, tek sürüm, prensipte paylaşılır
[workspace.package] bir kez, her kasanın kopyalamak yerine version.workspace = true ile devralabileceği ortak alanları (sürüm, basım, yazarlar, lisans) bildirir.
[workspace.package]
version = "0.1.1"
edition = "2021"
# hizmetler/aura-gateway/Cargo.toml
[package]
name = "aura-gateway"
version.workspace = true
Aurabase'nin on bir hizmetinin tümü bu modeli izler. İki kasa sapıyor ve bu, bu makaleyi hazırlarken bulunan iki tutarsızlıktan ilkidir: aura-cli basılı kopyada version = "0.2.0" bildirir ve lib libs/aura-migrations version = "0.1.0" bildirir — her ikisi de çalışma alanının 0.1.1'sinden farklıdır.
version.workspace = true isteğe bağlıdır; tarla tarla, sandık sandık. Hiçbir şey bir sandığın kendi numaralandırmasını korumasına engel olamaz - gönüllü olarak (örneğin ayrı olarak yayınlanan bir araç) veya unutkanlık nedeniyle. Bir çalışma alanı denetimi bu sahayı sandık başına kontrol etmeli, mirası üstlenmemelidir.
çalışma alanı.bağımlılıklar: bir sandık onu atlamadığı sürece gerçeğin kaynağı
[workspace.dependencies] çeşitli kasalar tarafından paylaşılan bağımlılıkları merkezileştirir. Her hizmet, kendi sürüm sınırlamasını ayarlamak yerine { workspace = true } ile ona başvurur.
[workspace.dependencies]
axum = { version = "0.8", features = ["ws", "multipart", "macros"] }
sqlx = { version = "0.8", default-features = false, features = […] }
tower_governor = { version = "0.8", features = ["axum"] }
governor = "0.10"
# services/aura-gateway/Cargo.toml — çalışma alanı yöneticisini devralmaz
governor = "0.8" # yerel sürüm, farklı
This is the second real discrepancy: the workspace centralizes governor in version 0.10, but aura-gateway redeclares its own line governor = "0.8" instead of inheriting — the gateway applies its rate limiting with the bare governor crate, when aura-auth, aura-ai, aura-db and aura-functions pass through tower_governor in middleware. A workspace does not prevent divergence: it only makes it visible, if we take the trouble to compare.
Ancak tüm bağımlılıklar merkezileştirilmeyi hak etmiyor. wasmtime, [workspace.dependencies] içinde hiçbir yerde görünmüyor: yalnızca bir kasa, aura-functions, onu WASM çalışma zamanı için kullanıyor, dolayısıyla yerel olarak bildirilmiş durumda kalıyor. Uyguladığımız kural: çalışma alanı seviyesine bağımlılığı daha önce değil, iki veya daha fazla kasanın paylaştığı andan itibaren yükseltin.
libs/ to services/: neye bağlı
Beş paylaşılan kütüphane (aura-core, aura-crypto, aura-db-adapters, aura-migrations, aura-telemetry) [workspace.dependencies] — aura-core = { path = "libs/aura-core" } içinde yol bağımlılıkları olarak bildirilir ve ardından her hizmet gerçekte hangisine ihtiyaç duyduğunu seçer.
Ortaya çıkan grafik bir dosyadan diğerine okunabilir durumda kalır. aura-gateway yalnızca beş dahili kütüphaneden üçüne bağlıdır — aura-core, aura-crypto ve aura-telemetry. Yönlendirmek için yeterli, PostgREST sepet için bir JWT imzalayın ve aura-db-adapters veya aura-migrations dokunmadan izlerini dışa aktarın. aura-provisionerşunu ekler: aura-migrations: bir projenin oluşturulmasından kaynaklanan şema geçişlerini yeniden oynatır.
En dar durum, CI/CD geçişlerini gerçekleştiren özel ikili dosya olan aura-migrator'dir. Aurabase dahili kütüphaneleri arasında, üretimi [dependencies] yalnızcaaura-migrations'yi listeler — aura-core, test amacıyla yalnızca [dev-dependencies] içinde görünür. Bu nedenle üretime teslim edilen ikili dosya herhangi biraura-core kodunu içermez; yalnızca cargo test sırasında mevcuttur.
Bir sandık, birkaç ikili dosya: aura-gerçek zamanlı bölme
Bir çalışma alanı, her yeni konuşlandırılabilir süreç istediğinizde yeni bir üye oluşturmayı gerektirmez. aura-realtime çalışma alanının tek bir üyesi olarak kalır, ancak Cargo.toml aynı paylaşılan [lib] etrafında üç farklı [[bin]] tablosu bildirir.
[lib]
name = "aura_realtime"
[[bin]]
name = "aura-realtime"
[[bin]]
name = "aura-realtime-cdc-worker"
path = "src/bin/cdc_worker.rs"
[[bin]]
name = "aura-realtime-ws-front"
path = "src/bin/ws_front.rs"
Manifesto bu ikisi arasındaki sınırı belgeliyor. cdc-worker, yoklama yoluyla Postgres değişikliklerini yakalar ve bir WebSocket sunucusu açmadan pub/sub çekirdeğinde (Client::publish_with_headers) NATS yayınlar — JetStream, aynı hizmette, CDC yayılımına değil, yalnızca örnekler arası varlık KV'sine hizmet eder. ws-front yalnızca NATS tüketir ve CDC'ye hiç dokunmadan WebSocket/SSE bağlantılarını tutar — tüm ayrıntılar gerçek zamanlı motor belgelerindedir. Her iki ikili dosya da [lib] aracılığıyla aynı RLS filtreleme kodunu paylaşır ancak Kubernetes'te bağımsız olarak dağıtılır ve ölçeklendirilir. Bu, yeni bir çalışma alanı üyesi yerine bir sandıkta birkaç ikili dosya seçmek için doğru sinyaldir: aynı dahili mantık, farklı dağıtım topolojileri.
Hizmetler/ altındaki bir dosyanın mutlaka Kargo üyesi olması gerekmez
aura-edge-runtime klasörü Aurabase deposunda mevcut. Ancak herhangi bir Cargo.toml içermez — yalnızca TypeScript (index.ts, envelope.ts) ve kök çalışma alanının members listesinde hiçbir yerde görünmez.
Aurabase'in members listesinin services/* gibi genel bir kalıpla değiştirilmek yerine elle yazılmasının nedeni tam olarak budur. Bir glob,Rust olmayan bu klasörü çalışma alanına eklemeyi deneyebilir ve sonuç olarak bir çözümleme hatası ortaya çıkabilir. Açık bir liste, aynı dili konuşmayan klasörlerin aynı ebeveyn services/ altında bir arada bulunmasına olanak tanır.
Ders genelleştirir: Rust arka ucunun hizmetlerini, services/ alt klasörlerini listeleyerek saymak yanlış bir sayı verir. Yalnızca Cargo.toml kökü, çalışma alanında gerçekte neyin derlendiği konusunda yetkilidir.
[profile.release]: tüm çalışma alanı için tek bir ayar
Çalışma alanının kökünde bildirilen bir [profile.release], yayın modunda derlenen tüm üyelere uygulanır; ayarlanacak on bir değil yalnızca tek bir yer vardır. Cargo, derleme profili referansındaki tüm mevcut anahtarları belgeliyor; Aurabase yalnızca beşini etkinleştirir.
[profile.release]
lto = "thin" # LTO çapraz kasaları, performans/derleme süresi dengesi
codegen-units = 1 # en iyi genel satır içi
panic = "unwind" # tokio/axum tarafından izole edilen bir panik → 500, küresel bir çöküş değil
strip = "symbols"
opt-level = 3
"abort" yerine panic = "unwind" seçimi doğrudan dosya yorumunda belgelenmiştir: axum işleyicisindeki panik tokio tarafından durdurulur, görev 500 değerini döndürür ve süreç diğer eşzamanlı istekleri sunmaya devam eder.abort'nin performans kazancı, sorgular arası izolasyon kaybına değmez.
Alet zincirini ve önemli komutları dondurun
Birleşik bir çalışma alanı bağımlılık sürümlerini belirler ancak derleyicinin kendi sürümünü ayarlamaz. rust-toolchain.toml, kökte, depodaki cargo veya rustc öğesine doğrudan çağrı için araç zincirini (bugün channel = "1.93") dondurur.
Bu dosya tam olarak sessiz bir kayma meydana geldiği için var: Bir CI eylemi, günün stable kanalını rust-toolchain.toml okumadan yüklerken, serbest bırakılan Docker görüntüsü donmuş sürümle derlendi. Bir taahhüt, günümüzün kararlı özelliği olan Rust ile tüm testleri geçebilir, ardından görüntü yapısında başarısız olabilir - birleşmeden önce değil, birleşmeden sonra keşfedilir. rustupbu dosyaya herhangi bir doğrudan komut için saygı duyar: CI iş akışlarını etkilemeden gerekli olan tek düzeltmeydi.
# Tüm çalışma alanını derleyin
cargo build --workspace
# Tek bir sandığı test edin (tüm çalışma alanını değil)
cargo test -p aura-auth
# Çalışma alanının tamamında katı tüy bırakmama, uyarılar = hatalar
cargo clippy --workspace --all-targets -- -D warnings
# Biçimlendirme
cargo fmt --all
Bir bildirimi çalıştırmadan önce okuyanlar için son bir ayrıntı: aura-cli sandığı, [[bin]] tablosu onu aura değil aurabase olarak adlandıran bir ikili dosya derler. Yayınlanan npm sarmalayıcısı @aurabase/cli iki komutu ortaya çıkarır — aura ve aurabase her ikisi de aynı betiğe işaret eder. [[bin]] Kargonun adı, sandığın adı ve npm ambalajının gösterdiği ad üç ayrı şeydir; hiçbiri diğer ikisinden tahmin edilemez.
Kontrol listesi: neyin nerede beyan edileceği
Kargo çalışma alanına her sandık eklediğinizde beş karar ortaya çıkar. Yukarıda ele alınan Aurabase örneğine göre her birinin bildirildiği yer burasıdır.
| Üye listesi | [çalışma alanı] üyeler | Kök - açık liste, asla küresel değil |
|---|---|---|
| Paylaşılan sürüm/baskı | [çalışma alanı.paket] | Kök — version.workspace = true, kasaya göre, isteğe bağlı |
| 2'den fazla kasanın paylaştığı bağımlılık | [çalışma alanı.bağımlılıklar] | Kök — ardından her sandıkta { çalışma alanı = doğru } |
| Tek bir tüketiciye bağımlılık | sandığın [bağımlılıkları] | Yerel olarak, çalışma alanından geçmeden |
| Profil oluştur | [profil.yayın] | Yalnızca kök — tüm üyeler için geçerlidir |
Mevcut bir Kargo çalışma alanını (sizin veya devraldığınız bir projenin) denetlemek için yukarıda belgelenen türdeki tutarsızlıkları bulmak için dört kontrol yeterlidir:
[workspace.package].versionile her sandığınversiondeğerini karşılaştırın; farklı bir değer mutlaka bir hata değildir ancak belgelenmeye değerdir.[workspace.dependencies]'i her kasa tarafından yerel olarak bildirilen bağımlılıklarla karşılaştırın; her iki tarafta da farklı sürümlerde bulunan adları bulun.Cargo.tomlkökündekimemberslistesini depodaki gerçek alt klasörlerle karşılaştırın;members'de eksik olan bir klasör mutlaka bir gözden kaçma anlamına gelmez.- Sandık adıyla veya olası bir npm sarmalayıcısının gösterdiği adla eşleştiğini varsaymak yerine, derlenmiş her ikili dosyanın (
[[bin]] name) gerçek adını kontrol edin.