Validateur de demande

La fonctionnalité Validator vérifie une valeur structurée (un corps de requête analysé, un fichier de configuration décodé, un message sur le point d'être mis en file d'attente) par rapport à un schéma et renvoie une liste complète d'erreurs avec des chemins lisibles par machine. Les backends sont enfichables : le même trait présente les ponts JSON Schema, CUE et (futurs) Zod/TypeBox.

Quand l'utiliser#

Utilisez un ValidatorPlugin chaque fois que vous en avez besoin :

• Validation de formulaire multi-erreurs où l'interface utilisateur affiche chaque problème à une fois, pas seulement le premier échec.
• Validation du fichier de configuration au démarrage.
• Application de la forme du message sur une limite de file d'attente avant la charge utile atteint un gestionnaire.

Si vous n'avez besoin que d'une seule vérification de type, la commande en ligne est plus simple. Accédez à Validator lorsque le schéma réside en dehors de votre code Rust (fichiers JSON, interface utilisateur d'administration, partagé avec d'autres services).

Le trait#

pub trait ValidatorPlugin: Send + Sync {
    fn name(&self) -> &str;
    fn schema_language(&self) -> &str;          // "json-schema", "cue", ...
    fn register_schema(&self, name: &str, source: &str) -> Result<(), ValidatorError>;
    fn validate(
        &self,
        schema: &str,
        value: &serde_json::Value,
    ) -> Result<ValidationReport, ValidatorError>;
}

La répartition registre-puis-validation amortit les coûts d'analyse sur de nombreux appels de validation sur le même schéma. Le réenregistrement d'un nom remplace l'entrée précédente.

Types de clés#

ValidatorError se distingue de ValidationReport par valid = false. Le premier signifie « le plugin n’a pas pu faire son travail » ; le second signifie "le plugin a fait son travail et la saisie était fausse".

Implémentations de référence#

@bext/validate-jsonschema#

Sous-ensemble de schéma JSON minimal et sans dépendance couvrant les mots-clés qui couvrent 95 % de l'utilisation dans le monde réel :

• type (string, number, integer, boolean, object, array, null)
• required
• properties
• minimum / maximum
• minLength / maxLength
• pattern
• enum
• items

Parfait pour la validation de formulaires HTTP et les fichiers de configuration pour lesquels vous souhaitez une portabilité entre les outils.

@bext/validate-cue (expérimental)#

Expérimental — pas pour la production. Un talon qui démontre la surface du trait avec une grammaire jouet field: type ; il s'agit de et non de, un véritable évaluateur CUE. L'évaluation complète du CUE nécessite soit une utilisation du binaire cue, soit un interpréteur intégré, qui sont tous deux des travaux futurs. Utilisez-le uniquement pour expérimenter la surface des traits.

Le serveur sélectionne le validateur avec BEXT_VALIDATOR_PROVIDER — jsonschema (valeur par défaut, recommandée) ou cue (expérimental). Le Le backend @bext/validate-jsonschema est ce que chaque déploiement de production devrait utiliser.

Exemple#

use bext_plugin_api::validator::*;
use serde_json::json;

// Register at startup
let plugin: &dyn ValidatorPlugin = /* @bext/validate-jsonschema */;
plugin.register_schema(
    "create_user",
    r#"{
        "type": "object",
        "required": ["email", "age"],
        "properties": {
            "email": { "type": "string", "pattern": "^.+@.+\\..+$" },
            "age":   { "type": "integer", "minimum": 13, "maximum": 150 }
        }
    }"#,
)?;

// Validate on each request
let body = json!({ "email": "not-an-email", "age": 12 });
let report = plugin.validate("create_user", &body)?;

if !report.valid {
    for err in &report.errors {
        eprintln!("{}: {} ({:?})", err.path, err.message, err.kind);
    }
    // returns structured errors to the caller
}

Sortie typique pour cette entrée :

/email: value does not match pattern (PatternMismatch)
/age:   value 12 is less than minimum 13 (OutOfRange)

Notez que les deux erreurs apparaissent en un seul passage — le trait rapporte explicitement tout plutôt que de s'en remettre à la première incompatibilité.

Choisir un back-end#

Vous pouvez installer plusieurs plugins de validation côte à côte et en choisir un sur chaque site d'appel : ils ne partagent aucun état global au-delà du registre des plugins.

Indicateur de fonctionnalité#

Aucun. Le trait et les types du validateur résident dans bext-plugin-api et sont toujours disponibles ; aucune fonction de chargement ne les bloque.

Voir aussi#

• @bext/validate-jsonschema — le backend minimal du schéma JSON.
• @bext/validate-cue — l'emplacement back-end CUE.
• Recherche — câblez un validateur avant index() pour appliquer la forme du document à la limite d'écriture.
• Webhook : valide les charges utiles de webhook décodées par rapport à un schéma enregistré.
• Aperçu des capacités — la liste complète des fonctionnalités enfichables.