1.简介
早在2001年，W3C联盟就XML架构定义语言（XSD）提出了建议，将最受欢迎的架构定义语言合并为一种标准。 在这种情况下追求的主要目标是获得一个独立于平台的标准，供信息交换的所有参与者使用。 利用混乱，XML已成为最有吸引力的信息交换格式。 如今，信息技术中的XML格式已被广泛使用，远远超出了简单的数据交换。
XML的流行和广度导致XML传输的数据量增加和结构复杂化。 更年轻，更简单的JSON格式（从或多或少具有消息格式结构的XML中“获取”所有信息流）也为这一过程做出了贡献。 今天，我们有了一个事实，即描述XML消息的数据结构的XSD方案已经变得庞大而复杂。 以文本形式阅读大型和复杂的方案已经变得非常困难，因此需要专用软件和描述XML消息格式的最新文档。
在本文中，我将讨论如何解决用于信息交换的XML消息格式的文档编制问题。
2.问题
最好的XSD模式文档是XSD模式本身。 直到该方案超过一定的复杂性阈值，或者遇到一个不知道如何或不希望阅读XSD方案的人，这个公理才是正确的。 当使用XSD方案开发应用程序时，您可能还需要在技术或随附文档中描述开发的消息格式。
如果您连接了面向服务的体系结构中具有松散耦合或分布式组件的应用程序开发，那么您将熟悉SOA（面向服务的体系结构）和SOAP（简单对象访问协议）的概念，那么很快您就会需要最新的信息文档比您的客户更多。
因此，问题“我需要文件吗？” 有一个肯定的答案“是”，早晚使用XML进行软件开发的每个人都会遇到这个问题。
下一个明显的问题是记录格式应该是什么结果？ 很难回答这个问题，因为结果的不同使用者（建筑师，开发人员，分析师，技术作家，管理员，客户代表和其他所有人）具有完全不同的任务。
他们以不同的方式解决了这个问题。 有人（例如oXygen的开发人员）对XSD方案进行了完整描述。 结果，与方案本身相比，描述变得更加难以理解。 其他人则依靠这样的事实，即每个人都应该能够阅读XSD方案，并且不需要任何文档-有时仅仅是因为他们了解自己无法维持本文档的相关性。 和往常一样，真相介于两者之间。
3.问题的实质
可以通过以下主要步骤来表示开发消息格式的过程（请参见下图）。
迭代1：
- 1.确定用于信息交换的数据量-在此步骤中，确定要在信息交换参与者之间传输的数据量-实体，其属性结构和关系。
- 2.开发XSD方案-架构师或开发人员基于第1步开发XSD方案，该XSD方案除了数据本身之外，还包含传输，安全性等必需的SOAP消息机制。
- 3.描述消息格式-在此步骤中，将开发说明该格式并提供消息示例的文档。
- 4.协调-在此步骤中，格式的验证和批准是在开发这些格式的团队内部进行的。 如果发现错误，则重复开发迭代。
开发消息格式的过程是迭代的。 第一次迭代完成并收到注释后，下一个立即从步骤2开始：
- 2.开发XSD方案-架构师对XSD方案进行了更改，这比第一次迭代开发这些方案所花费的时间要少得多。
- 3.描述消息格式-分析人员或技术作家应使用格式说明来更新文档。
在这里他遇到了一个难题：仅进行架构师告知他的那些更改，或者废除文件大小已更改的所有方案。 任何人，甚至是最尽职的员工都将选择第一个选项-这是错误的。 此选项不起作用！ -方案中经常有未声明的更改，而架构师或开发人员忘记报告这些更改，并且采用这种方法时，格式说明将不可避免地与方案有所不同。 这有什么威胁？ -当开发开始时，将会发现差异，这会带来一些混乱，并在不同程度上使参与集成的所有团队的发展复杂化。
会更糟吗？ -是的，如果参加团队的开发时间表不同。 根据规范，在年初开始时，其中一个团队将发送包含错误填充数据的消息并成功完成合同。 年中的另一个团队意识到了这些消息的接收，并发现所需数据与其描述之间存在差异。 这次，混乱会持续很长时间，格式和描述之间的差异可能会变得过于昂贵。
有什么解决办法？ las-唯一的选择就是-每次都改变所有已更改的样式。 这很难接受。 带有相册格式的文档可能会占用一百多页并撒上，这是一项非常艰巨而艰巨的工作。 通常，编写此文档的人会因实施的紧迫性而承受巨大压力。 并非每个人都理解为什么更改几种方案中几个要素的描述会“花费”整个工作日甚至更多的时间。
因此，这一步骤成为发展的“瓶颈”，每个人都尽其所能确定当前更有价值的是质量还是时间。 - 4.同意-首先要批准格式制定团队。 内部协调完成后，轮到外部协调了-所有信息交流的参与者。
检测到的瓶颈在质量和开发时间之间造成了非常困难的选择。 几乎不可能在它们之间进行选择，因为同时需要两个选项！
4.记录消息格式
记录格式最明显的方法是用笔。 打开图表并逐个元素地描述它，这需要大量的工作时间。 如果方案很大或有很多方案，那么几天后，您将在专业程序员的视线中看到特定的红色阴影，并对这项工作产生持久的厌恶感。 接下来是对不可能完成的事情的理解，这样的工作已经很长时间没有自动化了，并且随后不断地寻找完成的工具。
在寻找自动化工具之前，最好先了解一下您想如何使用它以及该工具的工作结果是什么？
有关记录消息格式的所有工作都适合以下使用方案：
- 当我们从一个信息源（XSD方案）形成文档时，用填写好的“文档”来记录一个或多个XSD方案的元素的结构是最简单的选择。 通常，这些计划是团队内部作为当前工作的一部分开发的。 理想情况下，如果进行开发时要考虑到有关计划制定的协议，这不仅表明应该记录计划的要素，而且要说明内容和措辞。
- 使用未填写的“文档”或部分填写的文档来记录一个或多个XSD方案的元素的结构-此选项更加复杂。 这些是其他团队开发的方案。 通常，此类计划经常来自“现状”，而我们不能对此提出任何要求。 在这种情况下，只能从电路本身获取结构，并且必须用笔添加对元素的描述。
- 比较不同版本的XSD方案元素的结构-我们有方案及其描述，现在方案已更改，您需要更新描述或获取有关更改的信息。 当添加或删除元素时，或者纯粹从外观上看，当注释中的多余空间被删除并且文件校验和已更改时，方案可能会发生重大变化。 另外，应该注意的是使用另一个模板重写方案的情况-在这种情况下，从数据的角度来看没有任何变化，但是只有花费大量时间或使用专用软件才能找到旧的方案。 考虑到方案可以成百上千个组合，很明显，用眼睛比较方案是一项非常困难且需要大量资源的工作。
至于结果，经过多年使用方案及其文档的工作，我对消息格式描述的结果应该是什么形成了自己的理解，这被称为“ from plow”。 这个概念的基础可以从三点描述：
- 电路本身是次要的-主要数据。 在开发过程中，我们不需要这样的方案描述-我们需要对该方案描述的数据进行描述。 实际上，我们需要以XML消息中的形式或使用俄罗斯娃娃设计模板开发的XSD方案中的形式描述元素的格式（有关设计模板的更多详细信息，请参见文章“ XSD设计模板 ” ） 以此形式，可以方便地在开发过程中以及在以后的集成或维护过程中讨论该方案。 这就是客户希望在技术文档中看到的内容。
- 格式的描述应该是一个简单易懂的表格，专业开发人员和与开发相关的一切都是某种“魔术”的开发人员都可以使用它们轻松地工作。 总是有人会成为您的重要信息来源或消费者，在XSD电路上戳一下手指，然后说：“这是什么？”。
- 所有项目必须在格式相册中描述一次。 这意味着，当描述在单独的XSD方案中取出的任何元素时，表中仅应描述此元素。 无需在那里提取整个SOAP消息格式，也无需扩展导入方案中描述的类型。 这种方法可以防止文档膨胀到不合理的尺寸，并且可以更好地阅读，并且，如果有必要，在任何元素上添加其他信息，则需要在一个地方进行！
该文件中的格式说明如何？ 在此过程中，描述XSD方案的元素格式的表已通过列集及其填充而反复更改，直到我收到以下描述的列：
- “编号p / p”-此处以多级列表的形式显示图中元素的位置。
- “元素名称及其类型”-显示元素的数据在此处显示-元素名称及其类型。
- “元素描述”-此处显示元素的业务数据-从业务角度对其的描述。
- “填充规则”-此处显示技术数据：填充元素的规则，数据格式，值示例等。
- 锰 -此处显示元素的力量-义务性，多重性和选择元素的可能性。
下面的“解决方案”部分提供了格式说明的示例...
5.寻找解决方案
根据使用场景和预期结果，已经形成了使该活动自动化的工具功能的基本要求：
- 生成所选XSD方案的元素格式的描述。
- 生成所选文件夹及其子文件夹中所有XSD方案的元素格式的描述。
- 所选方案（或文件夹中的方案）及其以前版本的元素格式说明的比较。
- 使用在单独文件中指定的元素描述来丰富输出文档中元素格式的描述。
- 无论在XSD方案设计中使用的模板如何，都可以在Matryoshka模板的结构中将元素格式的描述放到一个视图中。
尽管XSD的使用非常普遍，并且使用XSD的软件很多，但我仍然没有找到至少能够部分满足这些要求的工具。
但是，这个问题比以往任何时候都更加相关，因此创建了这样的工具...
6.决定
对于那些对工具感兴趣的人，我将在文章后的注释中提供指向该工具的链接，但是在文章的框架内，作为记录消息格式的示例，查看结果会更加有趣。
6.1。 处理文档化架构的示例
这是描述从XSD方案获得的元素格式的结果，并带有“文档”。
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。 外部描述示例
这是从XSD方案获得的元素格式的描述结果，其中包含空白文档。
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。 比较两个方案的示例
这是通过比较XSD方案的不同版本获得的元素格式的描述。
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。 结果
新的FirstName，LastName和Zip元素的所有列均以粗体显示。 “地址”元素的位置已更改-仅第一列以粗体突出显示。 已删除的“全名”和“国家/地区”项目显示为灰色。 行的背景还有助于“读取”更改。
此演示文稿使差异易于在屏幕和印刷版上阅读。
7.总结
现在，要为数百个XSD电路制作格式专辑的新版本，只需几分钟。 将获得Word文档格式的输出文件，其大小将近1,500张。 说明中的错误问题消失了，最重要的是，方案说明的不相关性。 因此，事实证明，它成功地自动化了管理应用程序开发中劳动最密集的领域之一。