توثيق صيغ تبادل المعلومات - سهلة وبسيطة

1. مقدمة

2. القضايا

3. جوهر المشكلة

• 1. تحديد كمية البيانات لتبادل المعلومات - في هذه الخطوة يتم تحديد كمية البيانات التي سيتم إرسالها بين المشاركين في تبادل المعلومات - الكيان ، وبنيتهم ​​المنسوبة وعلاقاتهم.
• 2. تطوير مخططات XSD - بناءً على الخطوة رقم 1 ، يقوم المهندس المعماري أو المطور بتطوير مخططات XSD ، التي تحتوي ، بالإضافة إلى البيانات نفسها ، على آليات رسائل SOAP اللازمة للنقل والأمان وما إلى ذلك.
• 3. وصف تنسيقات الرسائل - في هذه الخطوة ، يتم تطوير وثائق تصف التنسيقات وتقدم أمثلة على الرسائل.
• 4. التوفيق - في هذه الخطوة ، يتم التحقق من الصيغ والموافقة عليها داخل فريق تطوير هذه التنسيقات. إذا تم العثور على عدم دقة ، يتم تكرار تكرار التطوير.

• 2. تطوير مخططات XSD - يقوم المهندس المعماري بإجراء تغييرات على مخططات XSD ، وهذا يستغرق وقتًا أقل بكثير من تطوير هذه المخططات في أول تكرار.
• 3. وصف تنسيقات الرسائل - يجب على المحلل أو الكاتب التقني تحديث الوثائق مع وصف التنسيقات.
  
  وهنا لديه معضلة: إجراء التغييرات فقط التي أبلغه بها المهندس المعماري أو الذهاب إلى جميع المخططات التي تغير حجم الملف من أجلها. أي شخص ، حتى الموظف الأكثر وعيًا سيختار الخيار الأول - وسيكون على خطأ. هذا الخيار لا يعمل! - في كثير من الأحيان هناك تغييرات غير معلنة في المخططات ، والتي ينسى المهندس المعماري أو المطور الإبلاغ عنها ، وبهذه الطريقة سيختلف وصف التنسيقات حتمًا عن المخططات. ماذا يهدد هذا؟ - عندما يبدأ التطوير ، سيتم العثور على تناقض سوف يجلب القليل من الفوضى ، وبدرجات متفاوتة ، يعقد تطوير جميع الفرق المشاركة في الاندماج.
  
  هل يمكن أن يكون أسوأ؟ - نعم ، إذا كان جدول تطوير الفرق المشاركة مختلفًا. يقوم أحد الفرق في بداية العام ، وفقًا للمواصفات ، بتنفيذ إرسال الرسائل مع البيانات المعبأة بشكل غير صحيح وإغلاق العقد بنجاح. يدرك فريق آخر في منتصف العام استلام هذه الرسائل ويجد تعارضًا بين البيانات المطلوبة ووصفها. هذه المرة ، تبقى الفوضى لفترة طويلة ويمكن أن يكون التناقض بين الأشكال ووصفها مكلفًا للغاية.
  
  ما الحل؟ للأسف - يبقى الخيار الوحيد - أن يخطيء في كل مرة ، كل الأنماط المتغيرة. هذا صعب جدا للقبول. يمكن أن يستغرق المستند الذي يحتوي على ألبوم من التنسيقات أكثر من مائة ورقة ويرشها ، إنه عمل شاق ومضن للغاية. في كثير من الأحيان ، يتعرض الشخص الذي يطور هذه الوثيقة لضغوط شديدة بسبب إلحاح التنفيذ. لا يفهم الجميع لماذا يمكن أن يؤدي تغيير وصف العديد من العناصر في العديد من المخططات إلى "تكلفة" يوم عمل كامل أو حتى أكثر.
  
  وهكذا ، تصبح هذه الخطوة "عنق الزجاجة" للتطور ، حيث يحدد الجميع ، قدر استطاعتهم ، ما هو الأكثر قيمة في الوقت الحالي - الجودة أو الوقت.
• 4. الموافقة - يذهب الموافقة في البداية داخل الفريق تطوير الأشكال. عند اكتمال التنسيق الداخلي ، يأتي دور التنسيق الخارجي - لجميع المشاركين في تبادل المعلومات.

4. توثيق صيغ الرسائل

• يعد توثيق بنية عناصر واحد أو أكثر من مخططات XSD مع "الوثائق" المعبأة هو الخيار الأسهل عندما نقوم بتشكيل مستند من مصدر واحد للمعلومات (مخططات XSD). عادة ، هذه مخططات تم تطويرها داخل الفريق كجزء من العمل الحالي. من الناحية المثالية ، إذا تم تنفيذ التطوير مع مراعاة الاتفاق على تطوير المخططات ، مما يشير ، ليس فقط إلى أنه يجب توثيق عناصر المخطط ، ولكن أيضًا مع المحتوى والصياغة.
• توثيق بنية عناصر واحد أو أكثر من مخططات XSD مع "توثيق" غير معبأ أو ممتلئ جزئيًا - هذا الخيار أكثر تعقيدًا. هذه مخططات طورتها فرق أخرى. غالبًا ما تأتي مثل هذه المخططات بانتظام من جانب "كما هي" ولا يمكننا تقديم أي مطالب عليها. في هذه الحالة ، يمكن فقط أخذ الهيكل من الدائرة نفسها ، ويجب إضافة وصف العناصر مع الأقلام.
• مقارنة بين بنية عناصر مخططات XSD من إصدارات مختلفة - لدينا مخططات ووصفها ، والآن تغيرت المخططات وتحتاج إلى تحديث الوصف أو الحصول على معلومات حول التغييرات. يمكن أن تتغير المخططات بشكل كبير سواء عند إضافة العناصر أو إزالتها ، أو بشكل تجميلي بحت ، عندما تتم إزالة مساحة إضافية في التعليق وتغيير المجموع الاختباري للملف. بشكل منفصل ، يجب ملاحظة الحالة عندما تتم إعادة كتابة المخطط باستخدام قالب آخر - في هذه الحالة ، لا يتغير شيء من وجهة نظر البيانات ، ولكن لا يمكنك معرفة النموذج القديم إلا من خلال قضاء الكثير من الوقت عليه أو استخدام برنامج خاص. بالنظر إلى أن المخططات يمكن أن تأتي في حزم المئات ، يصبح من الواضح أن مقارنة المخططات بالعينين مهمة صعبة للغاية وتستهلك موارد كثيرة.

• الدائرة نفسها ثانوية - البيانات الأولية. أثناء التطوير ، لا نحتاج إلى وصف للمخطط على هذا النحو - نحن بحاجة إلى وصف للبيانات التي يصفها هذا المخطط. في الواقع ، نحتاج إلى وصف لتنسيق العناصر في الشكل الذي تكون فيه في رسالة XML ، أو في مخطط XSD الذي تم تطويره باستخدام قالب تصميم الدمية الروسية (لمزيد من التفاصيل حول قوالب التصميم ، راجع المقالة " قوالب تصميم XSD " ) في هذا الشكل ، من الملائم مناقشة المخطط أثناء التطوير وبعد ذلك بكثير ، أثناء التكامل أو الصيانة. هذا ما يريد العميل رؤيته في الوثائق الفنية.
• يجب أن يكون وصف التنسيقات جدولًا بسيطًا ومفهومًا يمكن لكل من المطورين المحترفين وأولئك الذين يتعلق بهم كل شيء يتعلق بالتطوير نوعًا من "السحر" أن يعملوا بنفس السهولة. سيكون هناك دائمًا شخص ما ، كونه مصدرًا حاسمًا أو مستهلكًا للمعلومات بالنسبة لك ، يضغط بإصبع على دائرة XSD ويقول: "ما هذا ؟؟؟".
• يجب وصف جميع العناصر في ألبوم التنسيق مرة واحدة. هذا يعني أنه عند وصف أي عنصر يتم أخذه في مخطط XSD منفصل ، يجب وصف هذا العنصر فقط في الجدول. لا حاجة لسحب تنسيق رسالة SOAP بأكمله هناك ، لا حاجة لتوسيع الأنواع الموضحة في المخططات المستوردة. سيمنع هذا النهج المستند من الانتفاخ إلى أبعاد غير لائقة ويتم قراءته بشكل أفضل ، وإذا لزم الأمر ، قم بإضافة معلومات إضافية حول أي عنصر ، ستحتاج إلى القيام بذلك في مكان واحد!

• "رقم p / p" - يظهر هنا وضع العنصر في الرسم التخطيطي في شكل قائمة متعددة المستويات.
• "اسم العنصر ونوعه" - تظهر البيانات التي تظهر العنصر هنا - اسم العنصر ونوعه.
• "وصف العنصر" - يتم عرض بيانات العمل على العنصر هنا - وصفه من وجهة نظر العمل.
• "قواعد الملء" - البيانات الفنية معروضة هنا: قواعد لملء عنصر وتنسيق البيانات وأمثلة على القيم وما إلى ذلك.
• "Mn." - قوة العنصر موضحة هنا - الالتزام والتعدد وإمكانية اختيار عنصر.

5. إيجاد حل

• توليد أوصاف تنسيقات العناصر لنظام XSD المحدد.
• إنشاء أوصاف تنسيقات العناصر لجميع مخططات XSD في المجلد المحدد والمجلدات الفرعية الخاصة به.
• مقارنة وصف تنسيقات العناصر للمخطط المحدد (أو المخططات في المجلدات) وإصداره السابق.
• إثراء وصف تنسيقات العناصر في مستند الإخراج باستخدام أوصاف العناصر المحددة في ملف منفصل.
• جلب وصف تنسيقات العناصر إلى عرض واحد في بنية قالب Matryoshka ، بغض النظر عن القالب المستخدم في تصميم مخططات XSD.

6. القرار

6.1. مثال على معالجة مخطط موثق

6.1.1. دارة المصدر

<?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. النتيجة

6.2. مثال الوصف الخارجي

6.2.1. دارة المصدر

 <?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. بيانات ملف الوصف الخارجية

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

6.2.3. النتيجة

6.3. مثال لمقارنة نظامين

6.3.1. دارة المصدر

 <?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. النسخة السابقة من المخطط

 <?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. النتيجة

7. الملخص