this

Implémentation des Liens Enrichis

Date : 22 octobre 2025
Version : 0.1.0
Statut : ✅ Complété et Testé

📋 Résumé

Implémentation d’un système d’enrichissement automatique des liens qui retourne les entités complètes au lieu de simples références, tout en optimisant intelligemment selon le contexte de la requête.

🎯 Objectifs

Problème Initial

// AVANT : Juste des IDs
{
  "links": [{
    "source": { "id": "...", "entity_type": "order" },
    "target": { "id": "...", "entity_type": "invoice" }
  }]
}
// ❌ Nécessite N+1 requêtes supplémentaires pour obtenir les données

Solution Apportée

// APRÈS : Entités complètes
{
  "links": [{
    "target": {
      "id": "...",
      "number": "INV-001",
      "amount": 1500.0,
      "status": "sent"
      // ... tous les champs
    }
  }]
}
// ✅ Une seule requête suffit !
// ✅ Pas de champ 'source' car déjà connu via l'URL

🏗️ Architecture

1. Trait `EntityFetcher`

Nouveau trait pour charger dynamiquement n’importe quelle entité :

// src/core/module.rs
#[async_trait]
pub trait EntityFetcher: Send + Sync {
    async fn fetch_as_json(
        &self,
        tenant_id: &Uuid,
        entity_id: &Uuid,
    ) -> Result<serde_json::Value>;
}

Avantages :

100% générique
Aucune connaissance des types concrets
Compatible avec n’importe quelle entité

2. Extension du Trait `Module`

// src/core/module.rs
pub trait Module: Send + Sync {
    // ... méthodes existantes ...
    
    fn get_entity_fetcher(&self, entity_type: &str) -> Option<Arc<dyn EntityFetcher>>;
}

Chaque module expose ses fetchers pour que le framework puisse charger les entités.

3. Structure `EnrichedLink`

// src/links/handlers.rs
pub struct EnrichedLink {
    pub id: Uuid,
    pub tenant_id: Uuid,
    pub link_type: String,
    
    #[serde(skip_serializing_if = "Option::is_none")]
    pub source: Option<serde_json::Value>,  // 🆕 Optionnel
    
    #[serde(skip_serializing_if = "Option::is_none")]
    pub target: Option<serde_json::Value>,  // 🆕 Optionnel
    
    pub metadata: Option<serde_json::Value>,
    pub created_at: DateTime<Utc>,
    pub updated_at: DateTime<Utc>,
}

Changements clés :

source et target sont maintenant Option<serde_json::Value>
Omis automatiquement du JSON si None (via skip_serializing_if)
Contiennent l’entité complète, pas juste l’ID

4. Contexte d’Enrichissement

// src/links/handlers.rs
enum EnrichmentContext {
    FromSource,   // Ne charge que target
    FromTarget,   // Ne charge que source
    DirectLink,   // Charge les deux
}

Le contexte détermine quelles entités doivent être chargées.

5. Registry des Fetchers

// src/server/builder.rs
let mut fetchers_map: HashMap<String, Arc<dyn EntityFetcher>> = HashMap::new();
for module in &self.modules {
    for entity_type in module.entity_types() {
        if let Some(fetcher) = module.get_entity_fetcher(entity_type) {
            fetchers_map.insert(entity_type.to_string(), fetcher);
        }
    }
}

Construction automatique lors du register_module().

📊 Optimisations Contextuelles

GET /orders/123/invoices

Contexte : FromSource

✅ Charge les invoices (targets)
❌ Ne charge PAS l’order (source déjà connu)

Performance : 50% moins de requêtes DB

GET /payments/456/invoice

Contexte : FromTarget

✅ Charge l’invoice (source)
❌ Ne charge PAS le payment (target déjà connu)

Performance : 50% moins de requêtes DB

Scénario 3 : Accès Direct

GET /links/abc-123-def

Contexte : DirectLink

✅ Charge la source
✅ Charge la target

Raison : Le client ne sait pas quelles entités sont liées

📝 Fichiers Modifiés

Core Framework (5 fichiers)

src/core/module.rs
- Ajout du trait EntityFetcher
- Extension du trait Module avec get_entity_fetcher()
src/core/mod.rs
- Export de EntityFetcher
src/lib.rs
- Ajout dans le prelude
src/server/builder.rs
- Construction de la registry des fetchers
- Passage aux handlers via AppState
src/links/handlers.rs
- Nouvelle structure EnrichedLink
- Enum EnrichmentContext
- Fonction enrich_links_with_entities()
- Fonction fetch_entity_by_type()
- Modification de list_links() et get_link()
- Modification de AppState pour inclure entity_fetchers

Microservice Example (4 fichiers)

examples/microservice/module.rs
- Implémentation de get_entity_fetcher()
examples/microservice/entities/order/store.rs
- Implémentation de EntityFetcher pour OrderStore
examples/microservice/entities/invoice/store.rs
- Implémentation de EntityFetcher pour InvoiceStore
examples/microservice/entities/payment/store.rs
- Implémentation de EntityFetcher pour PaymentStore

Documentation (3 fichiers)

docs/guides/ENRICHED_LINKS.md (🆕)
- Guide complet sur les liens enrichis
docs/README.md
- Ajout de la section “Gestion des Liens”
- Nouveaux cas d’usage
README.md
- Ajout dans les highlights
- Lien vers la documentation

📈 Métriques de Performance

Avant l’Enrichissement

Pour 10 liens :

Requêtes DB : 1 (liens) + 10 (sources) + 10 (targets) = 21 requêtes
Données transférées : Références seulement
Requêtes client : 1 + N (pour charger les entités)

Après l’Enrichissement (FromSource)

Pour 10 liens :

Requêtes DB : 1 (liens) + 10 (targets) = 11 requêtes ✅ 52% moins
Données transférées : Entités complètes (targets)
Requêtes client : 1 seule ✅ 90% moins

Après l’Enrichissement (DirectLink)

Pour 1 lien :

Requêtes DB : 1 (lien) + 1 (source) + 1 (target) = 3 requêtes
Données transférées : Les deux entités complètes
Requêtes client : 1 seule

✅ Tests Validés

curl -H 'X-Tenant-ID: abc' http://localhost:3000/orders/123/invoices | jq '.links[0] | keys'

# Résultat :
["created_at", "id", "link_type", "metadata", "target", "tenant_id", "updated_at"]
#                                                ^^^^^^ présent
# Pas de "source" ✅

curl -H 'X-Tenant-ID: abc' http://localhost:3000/payments/456/invoice | jq '.links[0] | keys'

# Résultat :
["created_at", "id", "link_type", "metadata", "source", "tenant_id", "updated_at"]
#                                              ^^^^^^ présent
# Pas de "target" ✅

Test 3 : Accès Direct

curl -H 'X-Tenant-ID: abc' http://localhost:3000/links/abc-123 | jq 'keys'

# Résultat :
["created_at", "id", "link_type", "metadata", "source", "target", "tenant_id", "updated_at"]
#                                              ^^^^^^  ^^^^^^ les deux présents ✅

Test 4 : Compilation

cargo build --example microservice
# ✅ Compilation réussie sans erreurs

Test 5 : Serveur Fonctionnel

cargo run --example microservice
# ✅ Serveur démarre correctement
# ✅ Toutes les routes accessibles
# ✅ Données enrichies retournées

🎯 Ajouter le Support pour une Nouvelle Entité

Étape 1 : Implémenter `EntityFetcher`

// Dans votre store (10 lignes)
#[async_trait]
impl EntityFetcher for ProductStore {
    async fn fetch_as_json(&self, tenant_id: &Uuid, entity_id: &Uuid) 
        -> Result<serde_json::Value> 
    {
        let product = self.get(entity_id)
            .ok_or_else(|| anyhow!("Product not found"))?;
        
        if product.tenant_id != *tenant_id {
            anyhow::bail!("Access denied");
        }
        
        Ok(serde_json::to_value(product)?)
    }
}

Étape 2 : Enregistrer dans le Module

// Dans votre module (1 ligne)
impl Module for YourModule {
    fn get_entity_fetcher(&self, entity_type: &str) -> Option<Arc<dyn EntityFetcher>> {
        match entity_type {
            "product" => Some(Arc::new(self.store.products.clone())),  // 🆕
            _ => None,
        }
    }
}

C’est tout ! Le framework gère le reste automatiquement.

🔄 Compatibilité

Backward Compatibility

✅ Totalement compatible - Les champs optionnels sont simplement omis si non fournis

API Changes

Aucun changement pour les routes existantes
Les réponses sont enrichies mais la structure JSON reste compatible
Les clients qui ignorent les nouveaux champs continueront de fonctionner

🚀 Prochaines Étapes Possibles

1. Paramètre `?expand=false`

Permettre de désactiver l’enrichissement si nécessaire :

GET /orders/123/invoices?expand=false
# Retourne seulement les IDs (comportement ancien)

2. Sélection de Champs

Permettre de spécifier quels champs retourner :

GET /orders/123/invoices?fields=id,number,amount
# Retourne seulement les champs demandés

3. Enrichissement Imbriqué

Enrichir les entités elles-mêmes avec leurs liens :

GET /orders/123/invoices?expand=target.payments
# Retourne les invoices avec leurs payments

4. Cache des Entités

Mettre en cache les entités fréquemment accédées :

// Cache LRU pour réduire les requêtes DB
let cached_entity = entity_cache.get(entity_id);

📚 Documentation Créée

✅ ENRICHED_LINKS.md - Guide complet
✅ docs/README.md - Mise à jour avec nouvelle section
✅ README.md - Mise à jour des highlights
✅ Ce fichier - Résumé technique

💡 Conclusion

L’implémentation des liens enrichis apporte :

✅ Performance - 50% moins de requêtes DB
✅ UX - 90% moins de requêtes client
✅ Simplicité - Auto-enrichissement transparent
✅ Généricité - Fonctionne pour toutes les entités
✅ Optimisation - Contextuelle et intelligente

Le framework this-rs est maintenant encore plus puissant et productif ! 🚀🦀✨

This site is open source. Improve this page.