1. Introduction
En 2001, le consortium W3C a formulé des recommandations sur le langage de définition de schéma XML (XSD), combinant les langages de définition de schéma les plus populaires en une seule norme. L'objectif principal, poursuivi dans ce cas, était d'obtenir une norme indépendante de la plate-forme que tous les participants à l'échange d'informations puissent utiliser. Exploitant le chaos, XML est devenu le format d'échange d'informations le plus attrayant. De nos jours, le format XML dans les technologies de l'information est très largement utilisé, allant bien au-delà du simple échange de données.
La popularité et l'étendue de l'utilisation de XML entraînent à la fois une augmentation des volumes et une complication de la structure des données transmises en XML. Le format JSON, plus jeune et plus simple, qui «tirait» tous les flux d'informations de XML avec une structure plus ou moins simple des formats de message, a également contribué à ce processus. Aujourd'hui, nous avons le fait que les schémas XSD décrivant la structure des données des messages XML sont devenus volumineux et complexes. Il est devenu très difficile de lire des schémas volumineux et complexes sous forme de texte, il existe donc un besoin à la fois d'un logiciel spécial et d'une documentation à jour décrivant les formats de message XML.
Dans cet article, je vais vous expliquer comment le problème de la documentation des formats de message XML utilisés pour l'échange d'informations a été résolu ...
2. Problèmes
La meilleure documentation du schéma XSD est le schéma XSD lui-même. Cet axiome est vrai jusqu'à ce que le schéma dépasse un certain seuil de complexité ou que vous rencontriez une personne qui ne sait pas ou ne veut pas lire les schémas XSD. Lors du développement d'une application à l'aide de schémas XSD, vous pouvez également être confronté à l'obligation de décrire les formats de message développés dans la documentation technique ou d'accompagnement.
Si vous êtes connecté au développement d'applications avec des composants faiblement couplés ou distribués dans une architecture orientée services, vous êtes familier avec les concepts de SOA (architecture orientée services) et SOAP (Simple Object Access Protocol), alors très bientôt viendra un moment où vous aurez vous-même besoin d'une mise à jour il y a plus de documentation que votre client.
Par conséquent, la question "Ai-je besoin de documentation?" a une réponse définitive «Oui», tôt ou tard, tous ceux qui sont impliqués dans le développement de logiciels utilisant XML le rencontreront.
La prochaine question évidente est quel devrait être le résultat de la documentation des formats? Il est assez difficile de répondre à cette question, car les différents consommateurs du résultat (architectes, développeurs, analystes, rédacteurs techniques, administrateurs, représentants du client et tout le monde) ont des tâches complètement différentes.
Ils résolvent ce problème de différentes manières. Quelqu'un (par exemple, les développeurs de oXygen) a opté pour une description complète du schéma XSD. En conséquence, la description devient encore plus difficile à comprendre que le schéma lui-même. D'autres s'appuient sur le fait que tout le monde devrait pouvoir lire les schémas XSD et qu'aucune documentation n'est nécessaire - parfois uniquement parce qu'ils comprennent qu'ils ne sont pas en mesure de maintenir la pertinence de cette documentation. Comme toujours, la vérité se situe quelque part entre les deux ...
3. L'essence du problème
Le processus de développement des formats de message peut être représenté dans les étapes principales suivantes (voir la figure ci-dessous).
Itération n ° 1:
- 1. Déterminer la quantité de données pour l'échange d'informations - à cette étape, la quantité de données à transmettre entre les participants à l'échange d'informations est déterminée - l'entité, sa structure attributive et ses relations.
- 2. Développer des schémas XSD - sur la base de l'étape n ° 1, l'architecte ou le développeur développe des schémas XSD qui, en plus des données elles-mêmes, contiennent les mécanismes de message SOAP nécessaires au transport, à la sécurité, etc.
- 3. Décrire les formats de message - à cette étape, une documentation est développée qui décrit les formats et fournit des exemples de messages.
- 4. Réconcilier - à cette étape, la vérification et l'approbation des formats sont effectuées au sein de l'équipe développant ces formats. Si des inexactitudes sont trouvées, l'itération de développement est répétée.
Le processus de développement des formats de message est itératif. Une fois la première itération terminée et les commentaires reçus, la suivante démarre immédiatement à l'étape n ° 2:
- 2. Développer des schémas XSD - l'architecte apporte des modifications aux schémas XSD, cela prend beaucoup moins de temps que le développement de ces schémas à la première itération.
- 3. Décrire les formats de message - l'analyste ou le rédacteur technique doit mettre à jour la documentation avec une description des formats.
Et ici, il a un dilemme: ne faire que les changements dont l'architecte l'a informé ou bafouer tous les schémas pour lesquels la taille du fichier a changé. N'importe quel employé, même le plus consciencieux, choisira la première option - et aura tort. Cette option ne fonctionne pas! - très souvent, il y a des changements non déclarés dans les schémas, que l'architecte ou le développeur oublie de signaler, et avec cette approche, la description des formats s'écartera inévitablement des schémas. Qu'est-ce que cela menace? - lorsque le développement commence, une divergence sera constatée qui apportera un peu de chaos et, à des degrés divers, compliquera le développement de toutes les équipes impliquées dans l'intégration.
Cela pourrait-il être pire? - oui, si le calendrier de développement des équipes participantes est différent. Une des équipes en début d'année, conformément au cahier des charges, met en œuvre l'envoi de messages avec des données incorrectement renseignées et clôt avec succès le contrat. Une autre équipe au milieu de l'année réalise la réception de ces messages et constate un écart entre les données requises et leur description. Cette fois, le chaos vient de durer longtemps et l'écart entre les formats et leur description peut être trop cher.
Quelle est la solution? Hélas - la seule option reste - de se moquer à chaque fois, de tous les motifs modifiés. C'est très difficile à accepter. Un document avec un album de formats peut prendre plus d'une centaine de feuilles et le saupoudrer, c'est un travail très dur et minutieux. Très souvent, celui qui élabore ce document est fortement pressé par l'urgence de sa mise en œuvre. Tout le monde ne comprend pas pourquoi changer la description de plusieurs éléments dans plusieurs schémas peut «coûter» une journée entière de travail ou même plus.
Ainsi, cette étape devient le «goulot d'étranglement» du développement, où chacun, au mieux de ses capacités, détermine ce qui a le plus de valeur à l'heure actuelle - la qualité ou le temps. - 4. D'accord - l'approbation va d'abord à l'intérieur de l'équipe qui développe les formats. Lorsque la coordination interne est terminée, c'est au tour de la coordination externe - pour tous les participants à l'échange d'informations.
Le goulot d'étranglement détecté pose un choix très difficile entre la qualité et le temps de développement. Il est presque impossible de choisir entre eux car les deux options sont nécessaires à la fois!
4. Documentation des formats de message
La façon la plus évidente de documenter les formats est d'utiliser des stylos. Ouvrez le diagramme et décrivez son élément par élément, ce qui prend beaucoup de temps de travail. Si le schéma est grand ou qu'il y en a beaucoup, dans quelques jours, vous obtiendrez une teinte rouge spécifique des yeux d'un programmeur professionnel et une aversion persistante pour ce travail. Vient ensuite une compréhension de ce qui ne peut pas être, de sorte qu'un tel travail n'a pas été automatisé depuis longtemps et la recherche persistante subséquente d'un outil fini.
Avant de chercher un outil d'automatisation, il serait bon de comprendre comment vous souhaitez l'utiliser et quel devrait être le résultat de son travail?
Tout le travail sur la documentation des formats de message s'inscrit dans les scénarios d'utilisation suivants:
- La documentation de la structure des éléments d'un ou plusieurs schémas XSD avec la «documentation» remplie est l'option la plus simple lorsque nous formons un document à partir d'une source d'information (schémas XSD). En règle générale, il s'agit de schémas développés au sein de l'équipe dans le cadre du travail en cours. Idéalement, si le développement est effectué en tenant compte de l'accord sur le développement des schémas, ce qui indique non seulement que les éléments du schéma doivent être documentés, mais aussi avec quel contenu et libellé.
- Documenter la structure des éléments d'un ou plusieurs schémas XSD avec une «documentation» non remplie ou partiellement remplie - cette option est plus compliquée. Ce sont des schémas développés par d'autres équipes. Souvent, de tels programmes viennent régulièrement du côté du «Tel quel» et nous ne pouvons pas leur faire de demande. Dans ce cas, seule la structure peut être tirée du circuit lui-même et la description des éléments doit être ajoutée avec des stylos.
- Comparaison de la structure des éléments des schémas XSD de différentes versions - nous avons des schémas et leur description, et maintenant les schémas ont changé et vous devez mettre à jour la description ou obtenir des informations sur les changements. Les schémas peuvent changer à la fois de manière significative lorsque des éléments sont ajoutés ou supprimés, ou purement cosmétique, lorsqu'un espace supplémentaire est supprimé dans un commentaire et que la somme de contrôle du fichier a changé. Séparément, il convient de noter le cas lorsque le schéma est en cours de réécriture à l'aide d'un autre modèle - dans ce cas, rien ne change du point de vue des données, mais vous ne pouvez découvrir l'ancien qu'en y consacrant beaucoup de temps ou en utilisant un logiciel spécial. Étant donné que les schémas peuvent être fournis par centaines, il devient clair que comparer les schémas avec les yeux est un travail très difficile et gourmand en ressources.
En ce qui concerne le résultat, au cours de nombreuses années de travail avec les schémas et leur documentation, j'ai développé ma propre compréhension de ce que devrait être le résultat de la description des formats de message, qui s'appelle «from plough». La base du concept peut être décrite en trois points seulement:
- Le circuit lui-même est secondaire - les données primaires. Pendant le développement, nous n'avons pas besoin d'une description du schéma en tant que tel - nous avons besoin d'une description des données que ce schéma décrit. En fait, nous avons besoin d'une description du format des éléments sous la forme dans laquelle ils se trouvent dans le message XML, ou dans le schéma XSD développé à l'aide du modèle de conception Russian Doll (pour plus de détails sur les modèles de conception, voir l'article « Modèles de conception XSD » ) C'est sous cette forme qu'il convient de discuter du schéma à la fois pendant le développement et bien plus tard, lors de l'intégration ou de la maintenance. C'est ce que le Client souhaite voir dans la documentation technique.
- La description des formats doit être un tableau simple et compréhensible avec lequel les développeurs professionnels et ceux pour qui tout ce qui concerne le développement est une sorte de «magie» peuvent fonctionner aussi facilement. Il y aura toujours quelqu'un qui, étant une source critique ou un consommateur d'informations pour vous, pointe un doigt sur le circuit XSD et dit: "Qu'est-ce que c'est ???".
- Tous les éléments doivent être décrits une fois dans le format album. Cela signifie que lors de la description de tout élément retiré dans un schéma XSD distinct, seul cet élément doit être décrit dans le tableau. Pas besoin de récupérer tout le format de message SOAP, pas besoin d'étendre les types décrits dans les schémas importés. Cette approche empêchera le document de gonfler à des dimensions indécentes et est mieux lue, et si nécessaire, ajoutez des informations supplémentaires sur n'importe quel élément, vous devrez le faire en un seul endroit!
Quelle est la description des formats dans le document? Dans le processus, le tableau avec la description des formats des éléments du schéma XSD a changé à plusieurs reprises, à la fois par l'ensemble de colonnes et par leur remplissage, jusqu'à ce que je reçoive les colonnes décrites dans ce qui suit:
- "Non. P / p" - montre ici le positionnement de l'élément dans le diagramme sous la forme d'une liste à plusieurs niveaux.
- «Nom de l'élément et son type» - les données montrant l'élément sont affichées ici - le nom de l'élément et son type.
- «Description de l'élément» - les données commerciales sur l'élément sont affichées ici - sa description du point de vue de l'entreprise.
- «Règles de remplissage» - les données techniques sont affichées ici: règles de remplissage d'un élément, format des données, exemples de valeurs, etc.
- "Mn." - la puissance d'un élément est montrée ici - l'obligation, la multiplicité et la possibilité de choisir un élément.
Un exemple de description des formats est donné ci-dessous dans la section "Solution" ...
5. Trouver une solution
Sur la base des scénarios d'utilisation et du résultat souhaité, les exigences de base pour les fonctions de l'outil qui devraient automatiser cette activité ont été formées:
- Génération de descriptions de formats d'éléments pour le schéma XSD sélectionné.
- Génération de descriptions des formats d'élément pour tous les schémas XSD dans le dossier sélectionné et ses dossiers enfants.
- Comparaison de la description des formats des éléments pour le schéma sélectionné (ou schémas dans des dossiers) et sa version précédente.
- Enrichissement de la description des formats d'élément dans le document de sortie à l'aide des descriptions d'éléments spécifiées dans un fichier séparé.
- Apporter la description des formats d'élément à une seule vue dans la structure du modèle Matryoshka, quel que soit le modèle utilisé dans la conception des schémas XSD.
Malgré la prévalence de l'utilisation de XSD et le grand nombre de logiciels qui fonctionnent avec, je n'ai toujours pas trouvé d'outil répondant au moins partiellement à ces exigences.
Cependant, le problème était plus pertinent que jamais et un tel outil a été créé ...
6. Décision
Pour ceux qui sont intéressés à regarder l'outil, je fournirai des liens vers celui-ci dans les commentaires après l'article, mais dans le cadre de l'article, il est plus intéressant de regarder le résultat, comme exemple de documentation des formats de message.
6.1. Un exemple de traitement d'un schéma documenté
Voici le résultat de la description des formats des éléments obtenus à partir du schéma XSD avec la «documentation» remplie.
6.1.1. Circuit source
En-tête de spoiler<?xml version="1.0" encoding="UTF-8"?> <xsd:schema xmlns:xsd="http://www.w3.org/2001/XMLSchema" targetNamespace="http://www.example.org/Customer" xmlns:tns="http://www.example.org/Customer" elementFormDefault="qualified"> <xsd:annotation> <xsd:documentation> .</xsd:documentation> </xsd:annotation> <xsd:element name="Customer"> <xsd:annotation> <xsd:documentation>.</xsd:documentation> </xsd:annotation> <xsd:complexType> <xsd:sequence> <xsd:element name="CustomerId" type="xsd:int"> <xsd:annotation> <xsd:documentation>ID .</xsd:documentation> </xsd:annotation> </xsd:element> <xsd:element name="FirstName" type="xsd:string"> <xsd:annotation> <xsd:documentation>.</xsd:documentation> </xsd:annotation> </xsd:element> <xsd:element name="LastName" type="xsd:string"> <xsd:annotation> <xsd:documentation>.</xsd:documentation> </xsd:annotation> </xsd:element> <xsd:element name="Address"> <xsd:annotation> <xsd:documentation>.</xsd:documentation> </xsd:annotation> <xsd:complexType> <xsd:sequence> <xsd:element name="StreetAddress" type="xsd:string"> <xsd:annotation> <xsd:documentation> .</xsd:documentation> </xsd:annotation> </xsd:element> <xsd:element name="City" type="xsd:string"> <xsd:annotation> <xsd:documentation> .</xsd:documentation> </xsd:annotation> </xsd:element> <xsd:element name="Zip" type="xsd:string"> <xsd:annotation> <xsd:documentation> . >>> .</xsd:documentation> </xsd:annotation> </xsd:element> </xsd:sequence> </xsd:complexType> </xsd:element> </xsd:sequence> </xsd:complexType> </xsd:element> </xsd:schema>
6.1.2. Le résultat
6.2. Exemple de description externe
Voici le résultat de la description des formats d'élément obtenus à partir du schéma XSD avec une documentation vierge.
6.2.1. Circuit source
En-tête de spoiler <?xml version="1.0" encoding="UTF-8"?> <xsd:schema xmlns:xsd="http://www.w3.org/2001/XMLSchema" targetNamespace="http://www.example.org/Customer" xmlns:tns="http://www.example.org/Customer" elementFormDefault="qualified"> <xsd:element name="Customer"> <xsd:complexType> <xsd:sequence> <xsd:element name="CustomerId" type="xsd:int" /> <xsd:element name="FirstName" type="xsd:string" /> <xsd:element name="LastName" type="xsd:string" /> <xsd:element name="Address"> <xsd:complexType> <xsd:sequence> <xsd:element name="StreetAddress" type="xsd:string"/> <xsd:element name="City" type="xsd:string"/> <xsd:element name="Zip" type="xsd:string"/> </xsd:sequence> </xsd:complexType> </xsd:element> </xsd:sequence> </xsd:complexType> </xsd:element> </xsd:schema>
6.2.2. Données du fichier de description externe
En-tête de spoiler \matr . Customer . CustomerId ID . FirstName . LastName . Address . StreetAddress . City . Zip . >>> .
6.2.3. Le résultat
Veuillez noter que le résultat obtenu est complètement identique au résultat du traitement du schéma documenté!
6.3. Un exemple de comparaison de deux schémas
Voici une description des formats d'élément obtenus en comparant différentes versions du schéma XSD.
6.3.1. Circuit source
En-tête de spoiler <?xml version="1.0" encoding="UTF-8"?> <xsd:schema xmlns:xsd="http://www.w3.org/2001/XMLSchema" targetNamespace="http://www.example.org/Customer" xmlns:tns="http://www.example.org/Customer" elementFormDefault="qualified"> <xsd:element name="Customer"> <xsd:complexType> <xsd:sequence> <xsd:element name="CustomerId" type="xsd:int" /> <xsd:element name="FirstName" type="xsd:string" /> <xsd:element name="LastName" type="xsd:string" /> <xsd:element name="Address"> <xsd:complexType> <xsd:sequence> <xsd:element name="StreetAddress" type="xsd:string"/> <xsd:element name="City" type="xsd:string"/> <xsd:element name="Zip" type="xsd:string"/> </xsd:sequence> </xsd:complexType> </xsd:element> </xsd:sequence> </xsd:complexType> </xsd:element> </xsd:schema>
6.3.2. Version précédente du schéma
En-tête de spoiler <?xml version="1.0" encoding="UTF-8"?> <xsd:schema xmlns:xsd="http://www.w3.org/2001/XMLSchema" targetNamespace="http://www.example.org/Customer" xmlns:tns="http://www.example.org/Customer" elementFormDefault="qualified"> <xsd:element name="Customer"> <xsd:complexType> <xsd:sequence> <xsd:element name="CustomerId" type="xsd:int" /> <xsd:element name="FullName" type="xsd:string" /> <xsd:element name="Address"> <xsd:complexType> <xsd:sequence> <xsd:element name="StreetAddress" type="xsd:string"/> <xsd:element name="City" type="xsd:string"/> <xsd:element name="Country" type="xsd:string"/> </xsd:sequence> </xsd:complexType> </xsd:element> </xsd:sequence> </xsd:complexType> </xsd:element> </xsd:schema>
6.3.3. Le résultat
Les nouveaux éléments FirstName, LastName et Zip ont toutes les colonnes en gras. La position de l'élément «Adresse» a changé - seule la première colonne est mise en évidence en gras. Les éléments «FullName» et «Country» supprimés sont grisés. L'arrière-plan des lignes permet également de «lire» les modifications.
Cette présentation rend les différences faciles à lire à l'écran et sur papier.
7. Résumé
Maintenant, pour faire une nouvelle version de l'album de formats pour plusieurs centaines de circuits XSD, cela ne prend que quelques minutes. Le fichier de sortie au format d'un document Word est obtenu avec une taille de près de 1 500 feuilles. Les problèmes d'erreurs dans la description ont disparu et, surtout, le manque de pertinence de la description des régimes. Ainsi, il s'est avéré réussir à automatiser l'un des domaines les plus exigeants en main-d'œuvre dans la gestion du développement d'applications.