Geekly articles weekly

Documentação de formatos de troca de informações - fácil e simples

1. Introdução


Em 2001, o consórcio W3C fez recomendações sobre a XML Schema Definition Language (XSD), combinando as linguagens de definição de esquema mais populares em um padrão. O objetivo principal, perseguido nesse caso, era obter um padrão independente de plataforma que todos os participantes da troca de informações possam usar. Aproveitando o caos, o XML se tornou o formato de troca de informações mais atraente. Atualmente, o formato XML em tecnologia da informação é amplamente utilizado, indo muito além da simples troca de dados.

A popularidade e a amplitude do uso de XML resultam em um aumento de volumes e em uma complicação da estrutura de dados transmitidos em XML. O formato JSON mais novo e mais simples, que "levou" todas as informações flui do XML com uma estrutura mais ou menos simples de formatos de mensagem, também contribuiu para esse processo. Hoje, temos o fato de que os esquemas XSD que descrevem a estrutura de dados das mensagens XML se tornaram grandes e complexos. Tornou-se muito difícil ler esquemas grandes e complexos em forma de texto; portanto, são necessários softwares especiais e documentação atualizada que descreva os formatos de mensagens XML.
Neste artigo, falarei sobre como foi resolvido o problema de documentar os formatos de mensagens XML usados ​​para troca de informações ...



2. Questões


A melhor documentação do esquema XSD é o próprio esquema XSD. Esse axioma é verdadeiro até que o esquema exceda um certo limite de complexidade ou você encontre uma pessoa que não sabe ou não deseja ler os esquemas XSD. Ao desenvolver um aplicativo usando esquemas XSD, você também pode se deparar com o requisito de descrever os formatos de mensagem desenvolvidos na documentação técnica ou anexa.

Se você está conectado com o desenvolvimento de aplicativos com componentes distribuídos ou pouco acoplados em uma arquitetura orientada a serviços, conhece os conceitos de SOA (arquitetura orientada a serviços) e SOAP (Simple Object Access Protocol), muito em breve chegará um momento em que você precisará atualizar há mais documentação do que seu cliente.

Portanto, a pergunta "Preciso de documentação?" tem uma resposta definitiva "Sim", mais cedo ou mais tarde, todos os envolvidos no desenvolvimento de software usando XML encontrarão isso.

A próxima pergunta óbvia é qual deve ser o resultado da documentação dos formatos? É bastante difícil responder a essa pergunta, porque diferentes consumidores do resultado (arquitetos, desenvolvedores, analistas, redatores técnicos, administradores, representantes do Cliente e todos os demais) têm tarefas completamente diferentes.

Eles resolvem esse problema de maneiras diferentes. Alguém (por exemplo, desenvolvedores de oXygen) foi o caminho de uma descrição completa do esquema XSD. Como resultado, a descrição se torna ainda mais difícil de entender do que o próprio esquema. Outros confiam no fato de que todos devem poder ler esquemas XSD e nenhuma documentação é necessária - às vezes apenas porque eles entendem que não são capazes de manter a relevância desta documentação. Como sempre, a verdade está em algum lugar no meio ...

3. A essência do problema


O processo de desenvolvimento de formatos de mensagens pode ser representado nas seguintes etapas principais (veja a figura abaixo).



Iteração No. 1:

  • 1. Determine a quantidade de dados para troca de informações - nesta etapa, é determinada a quantidade de dados a serem transmitidos entre os participantes da troca de informações - a entidade, sua estrutura e relacionamentos de atribuição.
  • 2. Desenvolva esquemas XSD - com base na etapa 1, o arquiteto ou desenvolvedor desenvolve esquemas XSD que, além dos próprios dados, contêm os mecanismos de mensagem SOAP necessários para transporte, segurança etc.
  • 3. Descreva os formatos das mensagens - nesta etapa, é desenvolvida a documentação que descreve os formatos e fornece exemplos de mensagens.
  • 4. Reconciliar - nesta etapa, a verificação e aprovação dos formatos é realizada dentro da equipe que os desenvolve. Se forem encontradas imprecisões, a iteração do desenvolvimento é repetida.

O processo de desenvolvimento de formatos de mensagem é iterativo. Depois que a primeira iteração é concluída e os comentários são recebidos, o próximo começa imediatamente a partir da etapa No. 2:

  • 2. Desenvolver esquemas XSD - o arquiteto faz alterações nos esquemas XSD, isso leva muito menos tempo do que o desenvolvimento desses esquemas na primeira iteração.
  • 3. Descreva os formatos das mensagens - o analista ou redator técnico deve atualizar a documentação com uma descrição dos formatos.

    E aqui ele tem um dilema: fazer apenas as alterações que o arquiteto o informou ou adotar todos os esquemas para os quais o tamanho do arquivo foi alterado. Qualquer um, mesmo o funcionário mais consciente escolherá a primeira opção - e estará errado. Esta opção não funciona! - muitas vezes há mudanças não declaradas nos esquemas, que o arquiteto ou desenvolvedor esquece de relatar, e com essa abordagem a descrição dos formatos inevitavelmente diverge dos esquemas. O que isso ameaça? - quando o desenvolvimento começar, será encontrada uma discrepância que trará um pouco de caos e, em graus variados, complicará o desenvolvimento de todas as equipes envolvidas na integração.

    Poderia ser pior? - sim, se o cronograma de desenvolvimento para as equipes participantes for diferente. Uma das equipes no início do ano, de acordo com a especificação, implementa o envio de mensagens com dados preenchidos incorretamente e fecha o contrato com sucesso. Outra equipe no meio do ano realiza a recepção dessas mensagens e encontra uma discrepância entre os dados necessários e sua descrição. Desta vez, o caos permanece por um longo tempo e a discrepância entre os formatos e sua descrição pode ser muito cara.

    Qual é a solução? Infelizmente - a única opção que resta - é brincar sempre, com todos os padrões alterados. Isso é muito difícil de aceitar. Um documento com um álbum de formatos pode ocupar mais de cem folhas e polvilhá-lo, é um trabalho muito difícil e meticuloso. Muitas vezes, quem desenvolve este documento é fortemente pressionado pela urgência da implementação. Nem todo mundo entende por que alterar a descrição de vários elementos em vários esquemas pode "custar" um dia útil inteiro ou até mais.

    Assim, esse passo se torna o "gargalo" do desenvolvimento, onde todos, da melhor maneira possível, determinam o que é mais valioso no momento - qualidade ou tempo.
  • 4. Concordo - a aprovação entra primeiro na equipe que desenvolve os formatos. Quando a coordenação interna é concluída, é a vez da coordenação externa - para todos os participantes do intercâmbio de informações.

O gargalo detectado apresenta uma escolha muito difícil entre qualidade e tempo de desenvolvimento. É quase impossível escolher entre eles, porque as duas opções são necessárias ao mesmo tempo!

4. Documentar formatos de mensagem


A maneira mais óbvia de documentar formatos é com canetas. Abra o diagrama e descreva seu elemento por elemento, o que leva muito tempo de trabalho. Se o esquema for grande ou houver muitos deles, em alguns dias você terá um tom vermelho específico dos olhos de um programador profissional e uma aversão persistente a esse trabalho. Em seguida, vem uma compreensão do que não pode ser, para que esse trabalho não seja automatizado por um longo tempo e a subsequente pesquisa persistente por uma ferramenta concluída.

Antes de procurar uma ferramenta de automação, seria bom entender como você gostaria de usá-la e qual deve ser o resultado de seu trabalho?

Todo o trabalho de documentação de formatos de mensagem se encaixa nos seguintes cenários de uso:

  • Documentar a estrutura dos elementos de um ou mais esquemas XSD com a “documentação” preenchida é a opção mais fácil quando formamos um documento a partir de uma fonte de informação (esquemas XSD). Normalmente, esses são esquemas desenvolvidos dentro da equipe como parte do trabalho atual. Idealmente, se o desenvolvimento for realizado levando em consideração o acordo sobre o desenvolvimento de esquemas, o que indica não apenas que os elementos do esquema devem ser documentados, mas também com que conteúdo e redação.
  • Documentar a estrutura dos elementos de um ou mais esquemas XSD com "documentação" não preenchida ou parcialmente preenchida - essa opção é mais complicada. Estes são esquemas desenvolvidos por outras equipes. Muitas vezes, esses esquemas vêm regularmente do lado de "como estão" e não podemos exigir deles. Nesse caso, somente a estrutura pode ser retirada do próprio circuito e a descrição dos elementos deve ser adicionada com canetas.
  • Comparação da estrutura dos elementos dos esquemas XSD de diferentes versões - temos esquemas e sua descrição, e agora os esquemas foram alterados e você precisa atualizar a descrição ou obter informações sobre as alterações. Os esquemas podem mudar significativamente quando elementos são adicionados ou removidos, ou puramente esteticamente, quando um espaço extra é removido em um comentário e a soma de verificação do arquivo foi alterada. Separadamente, deve-se observar o caso em que o esquema está sendo reescrito usando outro modelo - nesse caso, nada muda do ponto de vista dos dados, mas você pode descobrir o antigo apenas gastando muito tempo nele ou usando software especial. Considerando que os esquemas podem chegar em centenas de pacotes, fica claro que comparar esquemas com os olhos é um trabalho muito difícil e que consome muitos recursos.

Quanto ao resultado, ao longo de muitos anos trabalhando com esquemas e sua documentação, desenvolvi meu próprio entendimento sobre o que deveria ser o resultado da descrição dos formatos de mensagem, que é chamado de "do arado". A base do conceito pode ser descrita em apenas três pontos:

  • O circuito em si é secundário - os dados primários. Durante o desenvolvimento, não precisamos de uma descrição do esquema como tal - precisamos de uma descrição dos dados que esse esquema descreve. De fato, precisamos de uma descrição do formato dos elementos no formato em que estão na mensagem XML ou no esquema XSD desenvolvido usando o modelo de design da Boneca Russa (para obter mais detalhes sobre modelos de design, consulte o artigo " Modelos de Design XSD " ) É dessa forma que é conveniente discutir o esquema durante o desenvolvimento e muito mais tarde, durante a integração ou manutenção. É o que o Cliente deseja ver na documentação técnica.
  • A descrição dos formatos deve ser uma tabela simples e compreensível, com a qual desenvolvedores profissionais e aqueles para quem tudo relacionado ao desenvolvimento é algum tipo de "mágica" podem funcionar igualmente facilmente. Sempre haverá alguém que, sendo uma fonte crítica ou consumidor de informações para você, cutuca o circuito XSD e diz: “O que é isso ???”.
  • Todos os itens devem ser descritos no álbum de formato uma vez. Isso significa que, ao descrever qualquer elemento retirado em um esquema XSD separado, apenas esse elemento deve ser descrito na tabela. Não é necessário extrair todo o formato da mensagem SOAP, não é necessário expandir os tipos descritos nos esquemas importados. Essa abordagem evitará que o documento fique inchado para dimensões indecentes e é melhor ler e, se necessário, adicionar informações adicionais sobre qualquer elemento, você precisará fazer isso em um só lugar!

Qual é a descrição dos formatos no documento? No processo, a tabela com a descrição dos formatos dos elementos do esquema XSD mudou repetidamente, tanto pelo conjunto de colunas quanto pelo preenchimento, até receber as colunas descritas a seguir:

  • "No. p / p" - mostra aqui o posicionamento do elemento no diagrama na forma de uma lista de vários níveis.
  • “Nome do elemento e seu tipo” - dados mostrando o elemento são mostrados aqui - o nome do elemento e seu tipo.
  • “Descrição do elemento” - dados comerciais sobre o elemento são mostrados aqui - sua descrição do ponto de vista da empresa.
  • “Regras de preenchimento” - os dados técnicos são mostrados aqui: regras para preenchimento de um elemento, formato de dados, exemplos de valores, etc.
  • "Mn". - o poder de um elemento é mostrado aqui - obrigatoriedade, multiplicidade e a possibilidade de escolher um elemento.

Um exemplo de descrição dos formatos é fornecido abaixo na seção "Solução" ...

5. Encontrando uma solução


Com base nos cenários de uso e no resultado desejado, foram formados os requisitos básicos para as funções da ferramenta que devem automatizar esta atividade:

  • Geração de descrições de formatos de elementos para o esquema XSD selecionado.
  • Geração de descrições de formatos de elementos para todos os esquemas XSD na pasta selecionada e em suas pastas filho.
  • Comparação da descrição dos formatos dos elementos para o esquema selecionado (ou esquemas em pastas) e sua versão anterior.
  • Enriquecendo a descrição dos formatos dos elementos no documento de saída usando as descrições dos elementos especificadas em um arquivo separado.
  • Trazendo a descrição dos formatos dos elementos para uma única visualização na estrutura do modelo Matryoshka, independentemente do modelo usado no design dos esquemas XSD.

Apesar da prevalência do uso de XSD e do grande número de softwares que funcionam com ele, ainda não encontrei uma ferramenta que atendesse ao menos parcialmente a esses requisitos.

No entanto, o problema foi mais relevante do que nunca e essa ferramenta foi criada ...

6. Decisão


Para quem estiver interessado em examinar a ferramenta, fornecerei links para ela nos comentários após o artigo, mas, dentro da estrutura do artigo, é mais interessante observar o resultado, como um exemplo de documentação de formatos de mensagem.

6.1 Um exemplo de processamento de um esquema documentado


Aqui está o resultado da descrição dos formatos dos elementos obtidos no esquema XSD com a "documentação" preenchida.

6.1.1 Circuito fonte


Título 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 O resultado




6.2 Exemplo de descrição externa


Aqui está o resultado da descrição dos formatos dos elementos obtidos no esquema XSD com documentação em branco.

6.2.1 Circuito fonte


Título 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 Dados do arquivo de descrição externa


Título de spoiler
 \matr      . Customer . CustomerId ID . FirstName . LastName . Address . StreetAddress  . City  . Zip  . >>>       .


6.2.3 O resultado



Observe que o resultado obtido é completamente idêntico ao resultado do processamento do esquema documentado!

6.3 Um exemplo de comparação de dois esquemas


Aqui está uma descrição dos formatos dos elementos obtidos comparando diferentes versões do esquema XSD.

6.3.1 Circuito fonte


Título 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 Versão anterior do esquema


Título 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 O resultado



Os novos elementos FirstName, LastName e Zip têm todas as colunas em negrito. A posição do elemento "Endereço" mudou - apenas a primeira coluna é destacada em negrito. Os itens excluídos "Nome completo" e "País" ficam acinzentados. O fundo das linhas também ajuda a "ler" as alterações.

Esta apresentação facilita a leitura das diferenças na tela e na impressão.

7. Resumo


Agora, para fazer uma nova versão do álbum de formatos para várias centenas de circuitos XSD, leva apenas alguns minutos. O arquivo de saída no formato de um documento do Word é obtido com um tamanho de quase 1.500 folhas. Os problemas dos erros na descrição desapareceram e, mais importante, a irrelevância da descrição dos esquemas. Portanto, acabou automatizando com êxito uma das áreas com mais trabalho no gerenciamento de desenvolvimento de aplicativos.

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

More articles:


All Articles