Proje ve JSON

Proje dosyaları, JSON ve birleştirme kuralları

English · Türkçe · Languages / Diller

Kapsam: JSON API Forge 0.5.1 · İnceleme: 17 Eylül 2026 · Dil: Türkçe

Dosya sorumlulukları

Yol	Amaç
app/<Project>/app.json	Proje manifesti; alternatif manifest tanıma kodda desteklenir
app/<Project>/config/*.json	Alfabetik sırayla birleştirilen doğrudan JSON parçaları
app/<Project>/hooks/*.py	Açıkça içe aktarılan Python kodu
app/<Project>/graphs/*.forgegraph.json	Editör tasarım belgeleri
app/<Project>/data/	Projeye ait yerel veri dosyaları
Dağıtım kökündeki .env	Süreç ayarları ve uygulama sırları

app/config, app/data, app/hooks, app/plugins, app/schemas gibi ayrılmış kökler uygulama olarak kabul edilmez. Boş bir klasör tek başına proje değildir. Slug ve API prefix başka etkin projelerle çakışmamalıdır.

Minimal manifest

{
  "slug": "notes",
  "name": "Notes",
  "version": "1.0.0",
  "api_prefix": "/api/notes/v1",
  "enabled": true,
  "docs_enabled": true,
  "audit_enabled": true
}

Gerekli alanlar ve model varsayılanları tam proje referansında bulunur. project_dir runtime metadata'sıdır; taşınabilir uygulama belgelerine makinenizin mutlak yolunu gömmeyin.

Kesin merge kuralları

Numaralı parçalar alfabetik sırada yüklenir. 10-, 20-, 40- gibi aynı genişlikte önekler sıralamayı açık kılar.

Veri	Birleştirme davranışı
Nesne/dictionary	Alanlar özyinelemeli birleşir
Scalar veya tür değişimi	Sonraki değer öncekini değiştirir
resources, mongo_resources, operations, data_sources	Listeye ekleme
dependencies, custom_endpoints, event_channels, webhook_docs	Listeye ekleme
Diğer listeler	Sonraki liste öncekinin yerine geçer

Örneğin son parçada cors_origins: [] eski origin listesini temizler. Son parçada resources: [] daha önceki kaynakları silmez. Aynı kaynak path'ini ikinci kez eklemek bir alan güncellemesi değildir; çakışma oluşturabilir. Eski tanımı bulunduğu yerde değiştirin.

Bu ayrım güvenlik için önemlidir: daha dar bir allowlist yazdığınızda önceki geniş izinlerin kalması istenmez. Eski genel dokümanlardan farklı olarak bu tablodaki eklenen listeler doğrudan _APPEND_LIST_KEYS üzerinden doğrulanmıştır.

Ortam değişkenleri

{
  "databases": {
    "primary": {
      "url": "$env:NOTES_DATABASE_URL:-sqlite+aiosqlite:///./data/notes.db"
    }
  }
}

Sözdizimi tam string değerinde $env:NAME veya $env:NAME:-default biçimindedir. ${NAME} ve bir metnin ortasına $env: eklemek aynı mekanizma değildir. Önce gerçek süreç ortamı, sonra yüklenen dotenv, sonra varsa varsayılan değerlendirilir. Bulunmayan değişken ve varsayılan yoksa None dönebilir; sonraki tip kontrolü hatayı belirler. Boş string, bulunmayan değerle aynı değildir.

Env çözümlemesi otomatik JSON/bool/int parser olarak düşünülmemelidir; sonuç modelin tip kurallarından geçer. Sırlar için halka açık bir varsayılan tanımlamayın.

Şema ve doğrulama

project.schema.json tam birleşmiş yapı, manifest.schema.json manifest, fragment.schema.json parçalar, editor-graph.schema.json graph içindir. $schema editöre yardımcı olur; runtime'ın semantik doğrulamasını değiştirmez. Fragment tek başına geçerli görünse bile bütün proje hatalı olabilir.

pattern ve patternProperties ifadeleri 512 karakterle sınırlı lineer-zaman regex motorunu kullanır. Look-around ve backreference desteklenmez. Pattern içeren string request parametresine daha küçük sınır verilmezse max_length=16384 uygulanır.

JSON dosyasında yorum veya trailing comma kullanmayın. Değişiklik sonrası forge validate, sonra forge routes/OpenAPI kontrolü yapın. Tam alan kataloğu Referans içindedir.

Kaynak ve doğrulama

Bu sayfa aşağıdaki sabit commitlerdeki davranışı açıklar. Yeni bir sürümde aynı davranışın sürdüğünü varsaymayın.

• main/framework/config.py
• main/framework/safe_regex.py
• main/schemas/project.schema.json
• main/docs/36-Configuration-Merge-Semantics.md

---

Wiki ana sayfa · Tüm sayfalar · Sürüm ve bakım