Документирование Форматов Обмена Информацией – Легко И Просто

1. Введение Еще в 2001 году консорциум W3C разработал рекомендации по языку определения схем XML (XSD), объединив наиболее популярные языки определения схем в один стандарт. Основная цель, которую преследовали, — получить платформенно-независимый стандарт, которым могли бы пользоваться все участники обмена информацией.

Обуздав хаос, XML стал наиболее привлекательным форматом обмена информацией.

В настоящее время формат XML очень широко используется в информационных технологиях, выходя далеко за рамки простого обмена данными.

Следствием популярности и широты использования XML является как увеличение объема, так и усложнение структуры данных, передаваемых в XML. Значительный вклад в этот процесс внес и более молодой и простой формат JSON, который «отнял» у XML все информационные потоки с более или менее простой структурой форматов сообщений.

Сегодня мы имеем то, что схемы XSD, описывающие структуру данных XML-сообщений, стали большими и сложными.

Читать большие и сложные диаграммы в текстовом виде стало очень сложно, поэтому существует необходимость как в специальном программном обеспечении, так и в актуальной документации, описывающей форматы сообщений XML. В этой статье я расскажу о том, как была решена проблема документирования форматов XML-сообщений, используемых для обмена информацией.

2. Проблемы

При разработке приложения, использующего схемы XSD, вы также можете столкнуться с требованием описать разрабатываемые форматы сообщений в технической или сопроводительной документации.

Если вы занимаетесь разработкой приложений со слабосвязанными или распределенными компонентами в сервис-ориентированной архитектуре, знакомы с понятиями SOA (сервис-ориентированная архитектура) и SOAP (простой протокол доступа к объектам), то очень скоро наступит момент наступит, когда вам самому понадобится новейшая документация больше, чем вашему заказчику.

Поэтому вопрос «Нужна ли документацияЭ» имеет четкий ответ «Да», рано или поздно с этим столкнутся все, кто занимается разработкой программного обеспечения, использующего XML. Следующий очевидный вопрос: каков должен быть результат документирования форматов? Ответить на этот вопрос довольно сложно, поскольку у разных потребителей результата (архитекторов, разработчиков, аналитиков, технических писателей, администраторов, представителей Заказчика и всех остальных) совершенно разные задачи.

Эта проблема решается разными способами.

Кто-то (например, разработчики oXygen) пошел по пути полного описания схемы XSD. В результате описание становится еще сложнее для понимания, чем сама диаграмма.

Другие утверждают, что каждый должен уметь читать схемы XSD и никакая документация не нужна — иногда только потому, что они понимают, что не в состоянии поддерживать эту документацию в актуальном состоянии.

Как всегда, истина лежит где-то посередине.

3. Суть проблемы

рисунок ниже).

Итерация №1:

• 1. Определить объем данных для обмена информацией – на этом этапе определяется объем данных, которые необходимо передать между участниками информационного обмена – сущностями, их атрибутивным составом и связями.

• 2. Разработка схем XSD — на основе шага №1 архитектор или разработчик разрабатывает схемы XSD, которые помимо самих данных содержат механизмы сообщений SOAP, необходимые для транспорта, безопасности и т. д.
• 3. Описать форматы сообщений – на этом этапе разрабатывается документация, в которой описываются форматы и приводятся примеры сообщений.

• 4. Согласование — на этом этапе форматы рассматриваются и согласовываются внутри команды, разрабатывающей эти форматы.

  При обнаружении неточностей итерация разработки повторяется.

После завершения первой итерации и получения комментариев следующая начинается сразу с шага №2:

• 2. Разработка XSD-схем – архитектор вносит изменения в XSD-схемы, это занимает гораздо меньше времени, чем ушло на разработку этих схем в первой итерации.

• 3. Опишите форматы сообщений.

  Аналитик или технический писатель должен обновить документацию, описывающую форматы.

  И здесь у него возникает дилемма: внести только те изменения, о которых ему сообщил архитектор, или сохранить все схемы, у которых изменился размер файла.

  Любой, даже самый добросовестный сотрудник выберет первый вариант – и будет не прав.

  Этот вариант не работает! — схемы очень часто содержат необъявленные изменения, о которых архитектор или разработчик забывает сообщить, и при таком подходе описание форматов неизбежно будет расходиться со схемами.

  Что это значит? — когда начнется разработка, будет выявлено несоответствие, которое внесет некоторый хаос и в той или иной степени усложнит разработку для всех команд, участвующих в интеграции.

  Может ли быть хуже? – да, если график развития команд-участниц разный.

  В начале года одна из команд в соответствии со спецификацией отправляет сообщения с неверно заполненными данными и успешно закрывает контракт. Другая команда получает эти сообщения в середине года и обнаруживает несоответствие между требуемыми данными и их описанием.

  На этот раз хаос надолго задержится и несоответствие форматов и их описания может стоить слишком дорого.

  Каково решение? Увы, остается единственный вариант – каждый раз воровать все измененные схемы.

  Это очень трудно принять.

  Документ с альбомом форматов может занимать сотни листов и его обложка – очень тяжелая и кропотливая работа.

  Очень часто на того, кто разрабатывает этот документ, оказывается сильное давление с целью его завершения.

  Не все понимают, почему изменение описания нескольких элементов на нескольких схемах может стоить целый рабочий день, а то и больше.

  Таким образом, этот шаг становится «узким местом» развития, где каждый в меру своей ответственности определяет, что в данный момент более ценно — качество или время.

• 4. Согласовать — сначала происходит согласование внутри команды, разрабатывающей форматы.

  Когда внутренняя координация завершена, наступает очередь внешней координации всех участников информационного обмена.

Выбрать между ними практически невозможно, ведь нужны оба варианта сразу!

4. Форматы сообщений документов

Вы открываете схему и описываете ее поэлементно, что занимает много рабочего времени.

Если схема большая или их много, то уже через несколько дней вы приобретете специфический красный оттенок глаз профессионального программиста и стойкое отвращение к этой работе.

Дальше приходит понимание невозможности того, чтобы такая работа давно не была автоматизирована и последующий настойчивый поиск готового инструмента.

Прежде чем искать средство автоматизации, неплохо было бы понять, как вы хотели бы его использовать и какой должен быть результат его работы? Вся работа по документированию форматов сообщений укладывается в следующие варианты использования:

• Документирование структуры элементов одной или нескольких XSD-схем с заполненной «документацией» — самый простой вариант, когда мы генерируем документ из одного источника информации (XSD-схемы).

  Обычно это схемы, которые разрабатываются внутри команды в рамках текущей работы.

  В идеале разработка ведется с учетом договора разработки схемы, в котором указывается не только, какие элементы схемы должны быть документированы, но и в каком конкретном содержании и формулировках.

• Документирование структуры элементов одной или нескольких XSD-схем с пустым или частично заполненным «документацией» — этот вариант более сложный.

  Это схемы, которые были разработаны другими командами.

  Зачастую такие схемы регулярно поступают со стороны «Как есть» и мы не можем к ним предъявлять какие-либо требования.

  В этом случае из самой схемы можно взять только структуру, а описание элементов необходимо добавить вручную.

• Сравнение структуры элементов схемы XSD разных версий — у нас есть схемы и их описания, а сейчас схемы изменились и нам необходимо обновить описание или получить информацию об изменениях.

  Схемы могут меняться как существенно, при добавлении или удалении элементов, так и чисто косметически, когда в каком-то комментарии убиралось лишнее место и менялась контрольная сумма файла.

  Отдельно следует отметить случай, когда схема переписывается по другому шаблону – в этом случае с точки зрения данных ничего не меняется, но распознать старое в новой схеме можно, только потратив много времени на это или с помощью специального программного обеспечения.

  С учетом того, что схемы могут идти пачками по сотни штук, становится понятно, что сравнение схем глазами – очень сложная и ресурсоемкая работа.

Основу концепции можно описать всего тремя пунктами:

• Сама схема вторична – данные первичны.

  При разработке нам не нужно описание схемы как таковой — нам нужно описание данных, которые эта схема описывает. По сути, нам необходимо описание формата элементов в том виде, в котором они появляются в XML-сообщении, или в XSD-схеме, разработанной с использованием шаблона проектирования «Матрешка» (подробнее о шаблонах проектирования см.

  статью « Шаблоны проектирования XSD ").

  Именно в таком виде удобно обсуждать схему как во время разработки, так и много позже, при интеграции или сопровождении.

  Именно это хочет видеть Заказчик в технической документации.

• Описание форматов должно представлять собой простую и понятную таблицу, с которой одинаково легко смогут работать как профессиональные разработчики, так и те, для кого все, что связано с разработкой, является своего рода «волшебством».

  Всегда найдется кто-то, кто, являясь для вас критичным источником или потребителем информации, укажет пальцем на XSD-диаграмму и скажет: «Что это??Э»

• Все элементы должны быть описаны один раз в альбоме формата.

  Это означает, что при описании любого элемента, входящего в отдельную схему XSD, в таблице должен быть описан только этот элемент. Нет необходимости перетаскивать туда весь формат сообщения SOAP; нет необходимости расширять типы, описанные в импортированных схемах.

  Такой подход не позволит документу раздуться до неприличных размеров и его будет легче читать, а если вам потребуется ввести дополнительную информацию по какому-либо элементу, то это нужно будет сделать в одном месте!

• «№ позиции» — здесь показано расположение элемента на схеме в виде многоуровневого списка.

• «Имя элемента и его тип» — здесь отображаются данные, идентифицирующие элемент — имя элемента и его тип.

• «Описание элемента» — здесь показаны бизнес-данные об элементе — его описание с точки зрения бизнеса.

• «Правила заполнения» — здесь отображаются технические данные: правила заполнения элемента, формат данных, примерные значения и т. д.
• «Мн».

  - здесь отображается мощность элемента - обязательность, кратность и возможность выбора элемента.

5. Поиск решения

• Формирование описания форматов элементов для выбранной схемы XSD.
• Создает описания форматов элементов для всех схем XSD в выбранной папке и ее дочерних папках.

• Сравнение описаний форматов элементов выбранной схемы (или схем в папках) и ее предыдущей версии.

• Дополнение описания форматов элементов в выходном документе описаниями элементов, указанными в отдельном файле.

• Приведение описания форматов элементов к единому виду в структуре шаблона Матрёшки, независимо от того, какой шаблон используется при проектировании 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 >
 

   

• Новая Возможность В Rambler News

  19 Oct, 24

• Дороги 21 Века

  19 Oct, 24

• Шаблон Zabbix Для Мониторинга Репликации Dfs

  19 Oct, 24

• Скрипт Нагрузочного Тестирования Для Проверки Соответствия Текущих Параметров Каналов Связи Заявленным

  19 Oct, 24

• Microsoft Activedirectory — Обновление Паролей Пользователей Во Внешних Хранилищах

  19 Oct, 24

• Apple Может Отказаться От Процессоров Intel

  19 Oct, 24

• Виджеты Для Интернет-Магазинов

  19 Oct, 24

• Видеообзор Вектор Тд 2

  19 Oct, 24

• Псевдоперерегистрация Ооо. Может, Айтишники Не Дрогнут?

  19 Oct, 24

• Архаизм

  19 Oct, 24