Geekly articles weekly

Dokumentation von Informationsaustauschformaten - einfach und unkompliziert

1. Einleitung


Bereits im Jahr 2001 gab das W3C-Konsortium Empfehlungen zur XML Schema Definition Language (XSD) ab und kombinierte die beliebtesten Schemadefinitionssprachen zu einem Standard. Das Hauptziel, das in diesem Fall verfolgt wurde, war es, einen plattformunabhängigen Standard zu erhalten, den alle Teilnehmer am Informationsaustausch verwenden können. XML nutzt das Chaos und ist zum attraktivsten Format für den Informationsaustausch geworden. Heutzutage wird das XML-Format in der Informationstechnologie sehr häufig verwendet und geht weit über den einfachen Datenaustausch hinaus.

Die Popularität und Breite der Verwendung von XML führt sowohl zu einer Zunahme des Volumens als auch zu einer Komplikation der Struktur der in XML übertragenen Daten. Zu diesem Prozess trug auch das jüngere und einfachere JSON-Format bei, das alle Informationsflüsse aus XML mit einer mehr oder weniger einfachen Struktur von Nachrichtenformaten „übernahm“. Heute haben wir die Tatsache, dass XSD-Schemata, die die Datenstruktur von XML-Nachrichten beschreiben, groß und komplex geworden sind. Es ist sehr schwierig geworden, große und komplexe Schemata in Textform zu lesen. Daher sind sowohl spezielle Software als auch aktuelle Dokumentationen erforderlich, die XML-Nachrichtenformate beschreiben.
In diesem Artikel werde ich darüber sprechen, wie das Problem der Dokumentation von XML-Nachrichtenformaten für den Informationsaustausch gelöst wurde ...



2. Probleme


Die beste Dokumentation zum XSD-Schema ist das XSD-Schema selbst. Dieses Axiom gilt so lange, bis das Schema einen bestimmten Komplexitätsschwellenwert überschreitet oder Sie eine Person treffen, die nicht weiß, wie oder nicht XSD-Schemata lesen möchte. Bei der Entwicklung einer Anwendung mit XSD-Schemata müssen Sie möglicherweise auch die entwickelten Nachrichtenformate in der technischen oder begleitenden Dokumentation beschreiben.

Wenn Sie mit der Entwicklung von Anwendungen mit lose gekoppelten oder verteilten Komponenten in einer serviceorientierten Architektur verbunden sind, sind Sie mit den Konzepten von SOA (serviceorientierte Architektur) und SOAP (Simple Object Access Protocol) vertraut. Dann wird es sehr bald eine Zeit geben, in der Sie selbst auf dem neuesten Stand sein müssen Es gibt mehr Dokumentation als Ihr Kunde.

Daher die Frage "Benötige ich Dokumentation?" hat eine eindeutige Antwort "Ja", früher oder später wird jeder, der an der Entwicklung von Software unter Verwendung von XML beteiligt ist, darauf stoßen.

Die nächste naheliegende Frage ist, was das Ergebnis der Dokumentation der Formate sein sollte. Es ist ziemlich schwierig, diese Frage zu beantworten, da verschiedene Konsumenten des Ergebnisses (Architekten, Entwickler, Analysten, technische Redakteure, Administratoren, Vertreter des Kunden und alle anderen) völlig unterschiedliche Aufgaben haben.

Sie lösen dieses Problem auf unterschiedliche Weise. Jemand (zum Beispiel Entwickler von oXygen) hat eine vollständige Beschreibung des XSD-Schemas vorgenommen. Infolgedessen wird die Beschreibung noch schwieriger zu verstehen als das Schema selbst. Andere verlassen sich auf die Tatsache, dass jeder in der Lage sein sollte, XSD-Schemata zu lesen, und keine Dokumentation erforderlich ist - manchmal nur, weil sie verstehen, dass sie die Relevanz dieser Dokumentation nicht aufrechterhalten können. Wie immer liegt die Wahrheit irgendwo dazwischen ...

3. Das Wesentliche des Problems


Der Prozess der Entwicklung von Nachrichtenformaten kann in den folgenden Hauptschritten dargestellt werden (siehe Abbildung unten).



Iteration Nr. 1:

  • 1. Bestimmen Sie die Datenmenge für den Informationsaustausch - in diesem Schritt wird die Datenmenge bestimmt, die zwischen den Teilnehmern des Informationsaustauschs übertragen werden soll - die Entität, ihre Attributionsstruktur und Beziehungen.
  • 2. XSD-Schemata entwickeln - Basierend auf Schritt Nr. 1 entwickelt der Architekt oder Entwickler XSD-Schemata, die zusätzlich zu den Daten selbst die für Transport, Sicherheit usw. erforderlichen SOAP-Nachrichtenmechanismen enthalten.
  • 3. Nachrichtenformate beschreiben - In diesem Schritt wird eine Dokumentation entwickelt, die die Formate beschreibt und Beispiele für Nachrichten enthält.
  • 4. Abgleich - In diesem Schritt wird die Überprüfung und Genehmigung von Formaten innerhalb des Teams durchgeführt, das diese Formate entwickelt. Wenn Ungenauigkeiten festgestellt werden, wird die Entwicklungsiteration wiederholt.

Der Prozess der Entwicklung von Nachrichtenformaten ist iterativ. Nachdem die erste Iteration abgeschlossen ist und die Kommentare empfangen wurden, beginnt die nächste sofort mit Schritt Nr. 2:

  • 2. XSD-Schemata entwickeln - Der Architekt nimmt Änderungen an den XSD-Schemata vor. Dies dauert viel weniger lange als die Entwicklung dieser Schemata bei der ersten Iteration.
  • 3. Nachrichtenformate beschreiben - Der Analyst oder technische Redakteur sollte die Dokumentation mit einer Beschreibung der Formate aktualisieren.

    Und hier hat er ein Dilemma: nur die Änderungen vorzunehmen, über die der Architekt ihn informiert hat, oder alle Schemata zu verwerfen, für die sich die Dateigröße geändert hat. Jeder, selbst der gewissenhafteste Mitarbeiter, wird die erste Option wählen - und sich irren. Diese Option funktioniert nicht! - Sehr oft gibt es nicht deklarierte Änderungen in den Schemata, die der Architekt oder Entwickler vergisst zu melden, und bei diesem Ansatz weicht die Beschreibung der Formate zwangsläufig von den Schemata ab. Was bedroht das? - Wenn die Entwicklung beginnt, wird eine Diskrepanz festgestellt, die ein wenig Chaos mit sich bringt und in unterschiedlichem Maße die Entwicklung aller an der Integration beteiligten Teams erschwert.

    Könnte es schlimmer sein? - ja, wenn der Entwicklungsplan für die teilnehmenden Teams unterschiedlich ist. Eines der Teams zu Beginn des Jahres implementiert gemäß der Spezifikation das Senden von Nachrichten mit falsch ausgefüllten Daten und schließt den Vertrag erfolgreich ab. Ein anderes Team erkennt Mitte des Jahres den Empfang dieser Nachrichten und stellt eine Diskrepanz zwischen den erforderlichen Daten und ihrer Beschreibung fest. Dieses Mal bleibt das Chaos lange bestehen und die Diskrepanz zwischen den Formaten und ihrer Beschreibung kann zu teuer sein.

    Was ist die Lösung? Leider - die einzige Möglichkeit bleibt - jedes Mal alle geänderten Muster zu vermasseln. Dies ist sehr schwer zu akzeptieren. Ein Dokument mit einem Album mit Formaten kann mehr als einhundert Blätter aufnehmen und darüber streuen. Es ist eine sehr harte und sorgfältige Arbeit. Sehr oft wird derjenige, der dieses Dokument entwickelt, stark von der Dringlichkeit der Umsetzung unter Druck gesetzt. Nicht jeder versteht, warum das Ändern der Beschreibung mehrerer Elemente in mehreren Schemata einen ganzen Arbeitstag oder sogar mehr „kosten“ kann.

    Somit wird dieser Schritt zum „Engpass“ der Entwicklung, bei dem jeder nach besten Kräften bestimmt, was im Moment wertvoller ist - Qualität oder Zeit.
  • 4. Zustimmen - Die Genehmigung erfolgt zunächst innerhalb des Teams, das die Formate entwickelt. Wenn die interne Koordination abgeschlossen ist, ist die externe Koordination an der Reihe - für alle Teilnehmer des Informationsaustauschs.

Der festgestellte Engpass stellt eine sehr schwierige Wahl zwischen Qualität und Entwicklungszeit dar. Es ist fast unmöglich, zwischen ihnen zu wählen, da beide Optionen gleichzeitig benötigt werden!

4. Nachrichtenformate dokumentieren


Der naheliegendste Weg, Formate zu dokumentieren, sind Stifte. Öffnen Sie das Diagramm und beschreiben Sie es Element für Element, was viel Arbeitszeit in Anspruch nimmt. Wenn das Schema groß ist oder es viele davon gibt, erhalten Sie in wenigen Tagen einen bestimmten roten Augenton eines professionellen Programmierers und eine anhaltende Abneigung gegen diese Arbeit. Als nächstes folgt ein Verständnis dessen, was nicht sein kann, so dass solche Arbeiten seit langem nicht mehr automatisiert wurden, und die anschließende dauerhafte Suche nach einem fertigen Werkzeug.

Bevor Sie nach einem Automatisierungstool suchen, sollten Sie wissen, wie Sie es verwenden möchten und was das Ergebnis seiner Arbeit sein sollte.

Alle Arbeiten zur Dokumentation von Nachrichtenformaten passen in die folgenden Verwendungsszenarien:

  • Die Dokumentation der Struktur der Elemente eines oder mehrerer XSD-Schemata mit der ausgefüllten „Dokumentation“ ist die einfachste Option, wenn wir ein Dokument aus einer Informationsquelle (XSD-Schemata) erstellen. In der Regel handelt es sich dabei um Schemata, die im Rahmen der aktuellen Arbeit im Team entwickelt werden. Idealerweise, wenn die Entwicklung unter Berücksichtigung der Vereinbarung über die Entwicklung von Systemen durchgeführt wird, aus der hervorgeht, dass nicht nur die Elemente des Systems dokumentiert werden sollten, sondern auch mit welchem ​​Inhalt und Wortlaut.
  • Dokumentieren der Struktur von Elementen eines oder mehrerer XSD-Schemata mit nicht ausgefüllter oder teilweise ausgefüllter „Dokumentation“ - diese Option ist komplizierter. Dies sind Programme, die von anderen Teams entwickelt wurden. Oft kommen solche Systeme regelmäßig von der Seite von „wie sie sind“ und wir können keine Anforderungen an sie stellen. In diesem Fall kann nur die Struktur aus der Schaltung selbst entnommen werden, und die Beschreibung der Elemente muss mit Stiften hinzugefügt werden.
  • Vergleich der Struktur von Elementen von XSD-Schemata verschiedener Versionen - wir haben Schemata und deren Beschreibung, und jetzt haben sich die Schemata geändert, und Sie müssen die Beschreibung aktualisieren oder Informationen über die Änderungen erhalten. Schemata können sich sowohl beim Hinzufügen oder Entfernen von Elementen als auch rein kosmetisch erheblich ändern, wenn ein zusätzlicher Platz in einem Kommentar entfernt wird und sich die Dateiprüfsumme geändert hat. Unabhängig davon sollte der Fall beachtet werden, wenn das Schema mit einer anderen Vorlage neu geschrieben wird. In diesem Fall ändert sich aus Sicht der Daten nichts, aber Sie können das alte nur herausfinden, indem Sie viel Zeit damit verbringen oder spezielle Software verwenden. In Anbetracht der Tatsache, dass Schemata in Gruppen von Hunderten angeboten werden können, wird deutlich, dass der Vergleich von Schemata mit Augen eine sehr schwierige und ressourcenintensive Aufgabe ist.

In Bezug auf das Ergebnis habe ich über viele Jahre der Arbeit mit Schemata und deren Dokumentation mein eigenes Verständnis dafür entwickelt, wie das Ergebnis der Beschreibung von Nachrichtenformaten aussehen sollte, die als „vom Pflug“ bezeichnet wird. Die Grundlage des Konzepts kann in nur drei Punkten beschrieben werden:

  • Die Schaltung selbst ist sekundär - die primären Daten. Während der Entwicklung benötigen wir keine Beschreibung des Schemas als solches - wir benötigen eine Beschreibung der Daten, die dieses Schema beschreibt. Tatsächlich benötigen wir eine Beschreibung des Formats der Elemente in der Form, in der sie sich in der XML-Nachricht befinden, oder in dem XSD-Schema, das mit der russischen Puppen-Entwurfsvorlage entwickelt wurde (weitere Einzelheiten zu Entwurfsvorlagen finden Sie im Artikel „ XSD-Entwurfsvorlagen “). ) In dieser Form ist es zweckmäßig, das Schema sowohl während der Entwicklung als auch viel später während der Integration oder Wartung zu diskutieren. Dies möchte der Kunde in der technischen Dokumentation sehen.
  • Die Beschreibung der Formate sollte eine einfache und verständliche Tabelle sein, mit der sowohl professionelle Entwickler als auch diejenigen, für die alles, was mit der Entwicklung zu tun hat, eine Art „Magie“ ist, gleich leicht arbeiten können. Es wird immer jemanden geben, der als kritische Quelle oder Konsument von Informationen für Sie einen Finger auf die XSD-Schaltung steckt und sagt: „Was ist das ???“.
  • Alle Elemente müssen einmal im Formatalbum beschrieben werden. Dies bedeutet, dass bei der Beschreibung eines Elements, das in einem separaten XSD-Schema herausgenommen wird, nur dieses Element in der Tabelle beschrieben werden sollte. Sie müssen dort nicht das gesamte SOAP-Nachrichtenformat abrufen und die in den importierten Schemata beschriebenen Typen nicht erweitern. Dieser Ansatz verhindert, dass das Dokument auf unanständige Dimensionen aufgebläht wird, und wird besser gelesen. Fügen Sie bei Bedarf zusätzliche Informationen zu jedem Element hinzu. Sie müssen dies an einer Stelle tun!

Wie beschreiben die Formate im Dokument? Dabei hat sich die Tabelle mit der Beschreibung der Formate der Elemente des XSD-Schemas wiederholt geändert, sowohl durch den Satz von Spalten als auch durch deren Füllung, bis ich die im Folgenden beschriebenen Spalten erhalten habe:

  • "Nr. P / p" - hier zeigt die Positionierung des Elements im Diagramm in Form einer mehrstufigen Liste.
  • "Name des Elements und sein Typ" - hier werden Daten angezeigt, die das Element zeigen - der Name des Elements und sein Typ.
  • "Beschreibung des Elements" - Geschäftsdaten zum Element werden hier angezeigt - seine Beschreibung aus Sicht des Geschäfts.
  • "Füllregeln" - hier werden technische Daten angezeigt: Regeln zum Füllen eines Elements, Datenformat, Beispiele für Werte usw.
  • "Mn." - Hier wird die Kraft eines Elements gezeigt - Verbindlichkeit, Vielfältigkeit und die Möglichkeit, ein Element auszuwählen.

Ein Beispiel für eine Beschreibung der Formate finden Sie unten im Abschnitt "Lösung" ...

5. Eine Lösung finden


Basierend auf den Verwendungsszenarien und dem gewünschten Ergebnis wurden die grundlegenden Anforderungen für die Funktionen des Tools gebildet, die diese Aktivität automatisieren sollen:

  • Generierung von Beschreibungen von Elementformaten für das ausgewählte XSD-Schema.
  • Generierung von Beschreibungen von Elementformaten für alle XSD-Schemata im ausgewählten Ordner und seinen untergeordneten Ordnern.
  • Vergleich der Beschreibung der Formate der Elemente für das ausgewählte Schema (oder Schemata in Ordnern) und seine vorherige Version.
  • Anreicherung der Beschreibung von Elementformaten im Ausgabedokument anhand der in einer separaten Datei angegebenen Elementbeschreibungen.
  • Bringen Sie die Beschreibung der Elementformate in eine einzelne Ansicht in der Struktur der Matroschka-Vorlage, unabhängig von der Vorlage, die beim Entwurf von XSD-Schemata verwendet wird.

Trotz der Verbreitung der Verwendung von XSD und der großen Anzahl von Software, die damit arbeitet, habe ich immer noch kein Tool gefunden, das diese Anforderungen zumindest teilweise erfüllt.

Das Problem war jedoch relevanter denn je und ein solches Tool wurde erstellt ...

6. Entscheidung


Für diejenigen, die sich das Tool ansehen möchten, werde ich in den Kommentaren nach dem Artikel Links dazu bereitstellen. Im Rahmen des Artikels ist es jedoch interessanter, das Ergebnis als Beispiel für die Dokumentation von Nachrichtenformaten zu betrachten.

6.1. Ein Beispiel für die Verarbeitung eines dokumentierten Schemas


Hier ist das Ergebnis der Beschreibung der Formate der Elemente, die aus dem XSD-Schema mit der ausgefüllten „Dokumentation“ erhalten wurden.

6.1.1. Quellschaltung


Spoiler Überschrift
<?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. Das Ergebnis




6.2. Beispiel für eine externe Beschreibung


Hier ist das Ergebnis der Beschreibung der Elementformate, die aus dem XSD-Schema mit leerer Dokumentation erhalten wurden.

6.2.1. Quellschaltung


Spoiler Überschrift
 <?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. Externe Beschreibung Dateidaten


Spoiler Überschrift
 \matr      . Customer . CustomerId ID . FirstName . LastName . Address . StreetAddress  . City  . Zip  . >>>       .


6.2.3. Das Ergebnis



Bitte beachten Sie, dass das erhaltene Ergebnis völlig identisch mit dem Ergebnis der Verarbeitung des dokumentierten Schemas ist!

6.3. Ein Beispiel für den Vergleich zweier Schemata


Hier finden Sie eine Beschreibung der Elementformate, die durch Vergleichen verschiedener Versionen des XSD-Schemas erhalten wurden.

6.3.1. Quellschaltung


Spoiler Überschrift
 <?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. Vorherige Version des Schemas


Spoiler Überschrift
 <?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. Das Ergebnis



Bei den neuen Elementen Vorname, Nachname und Zip sind alle Spalten fett gedruckt. Die Position des Elements "Adresse" hat sich geändert - nur die erste Spalte ist fett hervorgehoben. Gelöschte "FullName" - und "Country" -Elemente sind ausgegraut. Der Hintergrund von Zeilen hilft auch beim „Lesen“ von Änderungen.

Diese Präsentation macht die Unterschiede sowohl auf dem Bildschirm als auch in gedruckter Form leicht lesbar.

7. Zusammenfassung


Die Erstellung einer neuen Version des Formatalbums für mehrere hundert XSD-Schaltkreise dauert nur wenige Minuten. Die Ausgabedatei im Format eines Word-Dokuments wird mit einer Größe von fast 1.500 Blatt erhalten. Die Fehlerprobleme in der Beschreibung verschwanden und vor allem die Irrelevanz der Beschreibung der Schemata. Es stellte sich heraus, dass einer der arbeitsintensivsten Bereiche bei der Verwaltung der Anwendungsentwicklung erfolgreich automatisiert wurde.

Source: https://habr.com/ru/post/de418345/

More articles:


All Articles