Défauts ou objets de résultats SOAP ?

Question

J'ai eu une discussion à ce sujet avec un collègue de travail et nous n'avons pas réussi à nous mettre d'accord, alors je voulais avoir votre avis. J'ai mon propre avis sur la question, mais je ne vais pas vous le dévoiler.

Quand dois-je renvoyer un Défaut SOAP et quand dois-je renvoyer un objet résultat qui contient des informations sur les erreurs ? Supposons qu'il s'agisse d'un service Web générique pouvant être utilisé par divers systèmes (.NET, Java, etc.). L'objet résultat aurait un drapeau isError, un errorType (similaire au type d'exception spécifique) et un message.

Quelques points à considérer :

1. Une erreur de validation des données est-elle une faute ?
2. Devrait-il y avoir une combinaison de fautes (pour les cas très exceptionnels) et de l'objet de résultats (pour les erreurs "attendues") ?
3. Comment regrouper les erreurs SOAP (critique [référence nulle] ou validation [code postal incorrect]) ?
4. La rapidité d'exécution et la nécessité de vérifier les erreurs.
5. Meilleures pratiques, modèles, normes, etc.

Les liens vers les articles sont valables. Même si j'ai l'air de vouloir votre avis, s'en tenir aux faits (x est meilleur à cause de y et z...)

Answer 1

La plupart des clients SOAP convertiront les défauts en une exception d'exécution (si le langage client le permet). En gardant cela à l'esprit, je pense que vous pourriez reformuler la question comme suit : "Quand est-ce que je veux lancer une exception au lieu de retourner une valeur d'erreur" ? Je suis sûr que vous pouvez trouver beaucoup d'opinions sur la conception de l'API en général et sur ce sujet en particulier.

Cela dit, renvoyer une erreur n'est généralement pas utile pour le client :

1. Le client doit énumérer et gérer manuellement vos codes d'erreur au lieu de laisser le code du stub générer et lancer une exception du type approprié. L'utilisation de codes d'erreur empêche le client d'utiliser des techniques orientées objet comme la gestion des exceptions par superclasse.

2. Si vos codes d'erreur ne font pas partie du WSDL, le client n'aura aucune documentation sur ce qu'ils sont ou quand ils se produisent. Les erreurs typées font partie de la WSDL et sont donc (dans une certaine mesure) auto-documentées.

3. Les messages d'erreur peuvent contenir un contexte spécifique à l'erreur que le client peut utiliser pour signaler et récupérer les erreurs. Par exemple, le lancement d'une erreur de validation d'entrée contenant l'élément d'entrée invalide réel et une raison. Si vous renvoyez un résultat avec un code d'erreur et une chaîne opaque, le client n'a d'autre choix que de transmettre votre message d'erreur à l'utilisateur, ce qui nuit à l'internationalisation, à la cohérence de l'interface utilisateur, etc.

Pour répondre à vos questions spécifiques :

1. Une erreur de validation est une faute. Imaginez que vous invoquez le service Web à partir d'un client AJAX dont la capacité de gestion des erreurs est limitée ; vous voulez que le service renvoie un code HTTP 5xx, et non un code de réussite 400 avec une réponse inattendue.

2. Non. Les API doivent fournir des interfaces de rapport d'erreur cohérentes. La conception WSDL est une conception d'API. Le fait d'obliger le client à mettre en œuvre deux gestionnaires d'erreurs distincts ne lui facilite pas la vie.

3. La conception des fautes doit refléter votre modèle de demande/réponse et afficher des informations appropriées à l'abstraction du service. Ne concevez pas un défaut NullReference ; concevez un XYZServiceRuntimeFault. Si les clients fournissent fréquemment des requêtes invalides, concevez un InvalidRequestFault, avec des sous-classes appropriées afin que les clients puissent rapidement déterminer où se trouvent les données invalides.

Answer 2

Un objet de résultat ne doit contenir que des résultats. Si votre objet de résultat fournit une liste d'erreurs qui se sont produites sur un autre système, c'est un exemple de cas où vous pouvez avoir un drapeau "isError" ; sinon, vous ne pouvez pas car un résultat est soit valide, soit non valide.

Vous devriez toujours utiliser un SOAPFault lorsqu'une erreur se produit. La validation est une erreur, et c'est le piège du diable que de penser que la validation est moins grave que l'impossibilité d'ouvrir une base de données. Les deux cas ont le même impact - l'opération ne peut pas être achevée comme demandé.

Vous devez donc utiliser des objets de résultat pour les résultats et des défauts SOAP pour tout ce qui empêche un objet de résultat valide, y compris, mais sans s'y limiter, les erreurs, les échecs de validation, les avertissements, les défauts de bus, etc.

À l'époque où les exceptions n'existaient pas, il n'y avait pas de choix et, par conséquent, de nombreuses API sont devenues incohérentes et la plupart des API différaient sur la façon de renvoyer une erreur. C'était (et c'est toujours) horrible, déroutant et cela ralentit souvent le développement car il faut chercher comment chaque entrée d'API renvoie une erreur, et souvent comment décoder ou en savoir plus sur l'erreur.

1. Gérer la validation avec SOAPFaults / Exceptions est plus logique quand on y pense, et une fois qu'on y a pensé, c'est généralement plus facile. Vous devez concevoir la classe d'erreur de validation de manière à ce qu'elle contienne suffisamment d'informations pour identifier les éléments fautifs d'une manière qui ne nécessite pas nécessairement la requête originale. De cette façon, vous pouvez commencer à traiter les erreurs de validation de manière plus générique.

2. Si l'objet de résultats contient des erreurs, elles ne peuvent se produire que dans le domaine des résultats ; par exemple "produit en rupture de stock" parce que quelqu'un dans l'entrepôt ne sait pas compter.

3. Il n'est pas judicieux de faire la distinction entre une erreur critique et une erreur de validation, ce qui, à mon avis, n'est pas une comparaison valable car toute attribution d'un niveau de gravité est très subjective. Pour un système fournissant des informations sur les produits chimiques à un pompier, critique signifie probablement que le camion en feu transporte les numéros ONU 1298 et 1436 et non une référence nulle lors de la tentative de chargement du graphique d'avertissement.

   Concevez les défauts de manière à pouvoir les identifier de manière concise et les traiter en conséquence. Assurez-vous qu'ils transmettent suffisamment d'informations. La catégorisation arbitraire n'est pas nécessaire lorsque vous disposez d'informations suffisantes, car la défaillance se laisse identifier d'elle-même.

4. Les SOAPFaults transformés en Exceptions sont le moyen le plus sûr d'avoir un système fail-fast.

5. Meilleures pratiques, références, etc.

   • La gestion des exceptions dans un monde SOA : Ramesh

   • Quand les exceptions sont la règle : réaliser des architectures orientées services fiables et traçables

   • Meilleures pratiques en matière de pannes SOAP

   • Utilisez les fautes SOAP pour fournir le niveau de détail approprié au développeur au moment du développement, et au client lorsque le service Web est en production.

   • Les services Web utilisent les erreurs SOAP pour signaler les cas d'erreur aux clients. Les fautes peuvent être générées par le cadre SOAP dans le cas de messages SOAP invalides, de jetons de sécurité invalides ou elles peuvent être générées par la logique métier du service lui-même.

   • Si vous envoyez un message qui n'a pas abouti pour une raison ou une autre, vous pouvez recevoir une réponse contenant un élément SOAP fault, qui vous donne des informations sur l'état, l'erreur ou les deux. Il ne peut y avoir qu'un seul élément d'erreur SOAP dans un message, et il doit s'agir d'une entrée dans le corps SOAP. De plus, s'il y a un élément SOAP fault dans le corps SOAP, il ne peut y avoir aucun autre élément dans le corps SOAP. Cela signifie que lorsque vous ajoutez un élément d'erreur SOAP, vous avez effectivement terminé la construction du corps SOAP.

   • Les messages d'erreur SOAP sont le mécanisme par lequel les applications SOAP signalent les erreurs "en amont", aux nœuds situés plus tôt dans le chemin du message. La mission de cette section est de fournir une explication complète et détaillée des erreurs SOAP afin que vous puissiez les gérer de manière appropriée dans vos propres services Web.

Answer 3

Je pense que la réponse courte est d'utiliser un soap fault, à moins que vous ne sachiez que le client sera équipé pour gérer une erreur retournée comme résultat. Je pensais aussi à l'analogie entre les exceptions et les résultats d'erreurs, comme mentionné dans les autres réponses.

Il existe des zones grises qui pourraient être traitées raisonnablement comme des exceptions ou comme des erreurs de résultat, selon les besoins du client. Vous pourriez alors fournir un paramètre au service qui modifie la façon dont ces types d'erreur sont renvoyés. Par défaut, une erreur SOAP est utilisée, mais si le client définit le paramètre pour obtenir des résultats d'erreur, il indique alors qu'il est prêt à gérer cela comme faisant partie du résultat. Pour moi, les erreurs de validation se situent dans cette zone grise. Pour la plupart des clients, elles doivent être considérées comme des erreurs, mais si le client veut utiliser les données pour baliser l'interface utilisateur avec des erreurs de validation, il peut être plus utile de renvoyer les erreurs de validation dans le cadre du résultat.