1. Introducción
En 2001, el consorcio W3C hizo recomendaciones sobre el lenguaje de definición de esquemas XML (XSD), combinando los lenguajes de definición de esquemas más populares en un estándar. El objetivo principal, que se persiguió en este caso, era obtener un estándar independiente de la plataforma que todos los participantes en el intercambio de información puedan usar. Aprovechando el caos, XML se ha convertido en el formato de intercambio de información más atractivo. Hoy en día, el formato XML en tecnología de la información se usa ampliamente, yendo mucho más allá del simple intercambio de datos.
La popularidad y la amplitud del uso de XML dan como resultado un aumento en los volúmenes y una complicación de la estructura de los datos transmitidos en XML. El formato JSON más joven y simple, que "tomó" todos los flujos de información de XML con una estructura más o menos simple de formatos de mensajes, también contribuyó a este proceso. Hoy tenemos el hecho de que los esquemas XSD que describen la estructura de datos de los mensajes XML se han vuelto grandes y complejos. Se ha vuelto muy difícil leer esquemas grandes y complejos en forma de texto, por lo que se necesita un software especial y documentación actualizada que describa los formatos de mensajes XML.
En este artículo hablaré sobre cómo se resolvió el problema de documentar los formatos de mensajes XML utilizados para el intercambio de información ...
2. Problemas
La mejor documentación del esquema XSD es el propio esquema XSD. Este axioma es cierto hasta que el esquema excede un cierto umbral de complejidad o conoce a una persona que no sabe cómo o no quiere leer los esquemas XSD. Al desarrollar una aplicación utilizando esquemas XSD, también puede enfrentarse al requisito de describir los formatos de mensaje desarrollados en la documentación técnica o adjunta.
Si está conectado con el desarrollo de aplicaciones con componentes distribuidos o acoplados libremente en una arquitectura orientada a servicios, está familiarizado con los conceptos de SOA (arquitectura orientada a servicios) y SOAP (Protocolo simple de acceso a objetos), muy pronto llegará un momento en que usted mismo necesitará una actualización Hay más documentación que su cliente.
Por lo tanto, la pregunta "¿Necesito documentación?" tiene una respuesta definitiva "Sí", tarde o temprano, todos los que estén involucrados en el desarrollo de software utilizando XML se encontrarán con esto.
La siguiente pregunta obvia es ¿cuál debería ser el resultado de documentar los formatos? Es bastante difícil responder a esta pregunta, porque los diferentes consumidores del resultado (arquitectos, desarrolladores, analistas, escritores técnicos, administradores, representantes del Cliente y todos los demás) tienen tareas completamente diferentes.
Resuelven este problema de diferentes maneras. Alguien (por ejemplo, desarrolladores de oXygen) realizó una descripción completa del esquema XSD. Como resultado, la descripción se vuelve aún más difícil de entender que el esquema en sí. Otros confían en el hecho de que todos deberían poder leer esquemas XSD y no se necesita documentación, a veces solo porque entienden que no pueden mantener la relevancia de esta documentación. Como siempre, la verdad se encuentra en algún punto intermedio ...
3. La esencia del problema.
El proceso de desarrollo de formatos de mensajes se puede representar en los siguientes pasos principales (consulte la figura a continuación).
Iteración No. 1:
- 1. Determine la cantidad de datos para el intercambio de información: en este paso se determina la cantidad de datos que se transmitirán entre los participantes del intercambio de información: la entidad, su estructura atributiva y sus relaciones.
- 2. Desarrolle esquemas XSD: en base al paso 1, el arquitecto o desarrollador desarrolla esquemas XSD que, además de los datos mismos, contienen los mecanismos de mensajes SOAP necesarios para el transporte, la seguridad, etc.
- 3. Describa los formatos de mensaje: en este paso, se desarrolla documentación que describe los formatos y proporciona ejemplos de mensajes.
- 4. Conciliar: en este paso, la verificación y aprobación de los formatos se lleva a cabo dentro del equipo que desarrolla estos formatos. Si se encuentran imprecisiones, se repite la iteración de desarrollo.
El proceso de desarrollar formatos de mensajes es iterativo. Una vez que se completa la primera iteración y se reciben los comentarios, el siguiente comienza inmediatamente desde el paso 2:
- 2. Desarrolle esquemas XSD: el arquitecto realiza cambios en los esquemas XSD, esto lleva mucho menos tiempo que el desarrollo de estos esquemas en la primera iteración.
- 3. Describa los formatos de mensaje: el analista o escritor técnico debe actualizar la documentación con una descripción de los formatos.
Y aquí tiene un dilema: hacer solo aquellos cambios que el arquitecto le informó o modificar todos los esquemas para los cuales el tamaño del archivo ha cambiado. Cualquiera, incluso el empleado más concienzudo elegirá la primera opción, y se equivocará. ¡Esta opción no funciona! - muy a menudo hay cambios no declarados en los esquemas, que el arquitecto o desarrollador olvida informar, y con este enfoque la descripción de los formatos inevitablemente divergerá de los esquemas. ¿Qué amenaza esto? - cuando comienza el desarrollo, se encontrará una discrepancia que traerá un poco de caos y, en diversos grados, complicará el desarrollo de todos los equipos involucrados en la integración.
¿Podría ser peor? - Sí, si el cronograma de desarrollo para los equipos participantes es diferente. Uno de los equipos a principios de año, de acuerdo con la especificación, implementa el envío de mensajes con datos completados incorrectamente y cierra el contrato con éxito. Otro equipo a mediados de año se da cuenta de la recepción de estos mensajes y encuentra una discrepancia entre los datos requeridos y su descripción. Esta vez, el caos se queda por mucho tiempo y la discrepancia entre los formatos y su descripción puede ser demasiado costosa.
Cual es la solucion? Lamentablemente, la única opción sigue siendo, siempre, todos los patrones cambiados. Esto es muy difícil de aceptar. Un documento con un álbum de formatos puede ocupar más de cien hojas y rociarlo, es un trabajo muy duro y laborioso. Muy a menudo, quien desarrolla este documento está fuertemente presionado por la urgencia de la implementación. No todos entienden por qué cambiar la descripción de varios elementos en varios esquemas puede "costar" un día hábil completo o incluso más.
Por lo tanto, este paso se convierte en el "cuello de botella" del desarrollo, donde todos, lo mejor que puedan, determina lo que es más valioso en este momento: calidad o tiempo. - 4. De acuerdo: la aprobación al principio va dentro del equipo que desarrolla los formatos. Cuando se completa la coordinación interna, es el turno de la coordinación externa, para todos los participantes del intercambio de información.
El cuello de botella detectado plantea una elección muy difícil entre calidad y tiempo de desarrollo. ¡Es casi imposible elegir entre ellos porque ambas opciones son necesarias a la vez!
4. Documentar formatos de mensajes
La forma más obvia de documentar formatos es con bolígrafos. Abra el diagrama y describa su elemento por elemento, lo que requiere mucho tiempo de trabajo. Si el esquema es grande o hay muchos de ellos, en unos días obtendrá un tono rojo específico de los ojos de un programador profesional y una aversión persistente a este trabajo. Luego viene una comprensión de lo que no puede ser, de modo que dicho trabajo no se haya automatizado durante mucho tiempo y la búsqueda persistente posterior de una herramienta terminada.
Antes de buscar una herramienta de automatización, sería bueno entender cómo le gustaría usarla y cuál debería ser el resultado de su trabajo.
Todo el trabajo para documentar formatos de mensajes se ajusta a los siguientes escenarios de uso:
- Documentar la estructura de los elementos de uno o más esquemas XSD con la "documentación" completada es la opción más fácil cuando formamos un documento a partir de una fuente de información (esquemas XSD). Típicamente, estos son esquemas que se desarrollan dentro del equipo como parte del trabajo actual. Idealmente, si el desarrollo se lleva a cabo teniendo en cuenta el acuerdo sobre el desarrollo de esquemas, lo que indica, no solo que los elementos del esquema deben documentarse, sino también con qué contenido y redacción.
- Documentar la estructura de los elementos de uno o más esquemas XSD con "documentación" sin llenar o parcialmente llena: esta opción es más complicada. Estos son esquemas desarrollados por otros equipos. A menudo, tales esquemas regularmente vienen del lado de "Tal como está" y no podemos exigirles nada. En este caso, solo la estructura puede tomarse del circuito mismo, y la descripción de los elementos debe agregarse con plumas.
- Comparación de la estructura de elementos de esquemas XSD de diferentes versiones: tenemos esquemas y su descripción, y ahora los esquemas han cambiado y usted necesita actualizar la descripción u obtener información sobre los cambios. Los esquemas pueden cambiar significativamente tanto cuando se agregan o eliminan elementos, o puramente cosméticamente, cuando se elimina un espacio adicional en un comentario y la suma de verificación del archivo ha cambiado. Por separado, debe tenerse en cuenta el caso cuando el esquema se está reescribiendo usando otra plantilla; en este caso, nada cambia desde el punto de vista de los datos, pero puede descubrir el anterior solo gastando mucho tiempo en él o usando un software especial. Teniendo en cuenta que los esquemas pueden venir en paquetes de cientos, queda claro que comparar esquemas con los ojos es un trabajo muy difícil y que requiere muchos recursos.
En cuanto al resultado, durante muchos años de trabajo con esquemas y su documentación, desarrollé mi propia comprensión de cuál debería ser el resultado de la descripción de los formatos de mensajes, que se llama "desde el arado". La base del concepto se puede describir en solo tres puntos:
- El circuito en sí mismo es secundario: los datos primarios. Durante el desarrollo, no necesitamos una descripción del esquema como tal, necesitamos una descripción de los datos que describe este esquema. De hecho, necesitamos una descripción del formato de los elementos en la forma en que están en el mensaje XML, o en el esquema XSD desarrollado utilizando la plantilla de diseño de Russian Doll (para más detalles sobre las plantillas de diseño, consulte el artículo " Plantillas de diseño XSD " ) Es de esta forma que es conveniente discutir el esquema tanto durante el desarrollo como mucho más tarde, durante la integración o el mantenimiento. Es lo que el Cliente quiere ver en la documentación técnica.
- La descripción de los formatos debe ser una tabla simple y comprensible con la que tanto los desarrolladores profesionales como aquellos para quienes todo lo relacionado con el desarrollo sea una especie de "magia", puedan trabajar igualmente fácilmente. Siempre habrá alguien que, siendo una fuente crítica o consumidor de información para usted, toque el circuito XSD y diga: "¿Qué es esto?".
- Todos los elementos deben describirse en el álbum de formato una vez. Esto significa que al describir cualquier elemento que se extraiga en un esquema XSD separado, solo este elemento debe describirse en la tabla. No es necesario extraer todo el formato de mensaje SOAP, no es necesario expandir los tipos descritos en los esquemas importados. Este enfoque evitará que el documento se hinche a dimensiones indecentes y se lea mejor, y si es necesario, agregue información adicional sobre cualquier elemento, ¡deberá hacerlo en un solo lugar!
¿Cuál es la descripción de los formatos en el documento? En el proceso, la tabla con la descripción de los formatos de los elementos del esquema XSD ha cambiado repetidamente, tanto por el conjunto de columnas como por su relleno, hasta que recibí las columnas que se describen a continuación:
- "No. p / p": aquí se muestra el posicionamiento del elemento en el diagrama en forma de una lista de niveles múltiples.
- "Nombre del elemento y su tipo" - aquí se muestran los datos que muestran el elemento - el nombre del elemento y su tipo.
- “Descripción del elemento”: aquí se muestran los datos comerciales sobre el elemento, su descripción desde el punto de vista del negocio.
- “Reglas de llenado”: aquí se muestran datos técnicos: reglas para llenar un elemento, formato de datos, ejemplos de valores, etc.
- "Mn". - aquí se muestra el poder de un elemento: obligatoriedad, multiplicidad y la posibilidad de elegir un elemento.
Un ejemplo de una descripción de los formatos se da a continuación en la sección "Solución" ...
5. Encontrar una solución
Según los escenarios de uso y el resultado deseado, se han formado los requisitos básicos para las funciones de la herramienta que deberían automatizar esta actividad:
- Generación de descripciones de formatos de elementos para el esquema XSD seleccionado.
- Generación de descripciones de formatos de elementos para todos los esquemas XSD en la carpeta seleccionada y sus carpetas secundarias.
- Comparación de la descripción de los formatos de los elementos para el esquema seleccionado (o esquemas en carpetas) y su versión anterior.
- Enriquecer la descripción de los formatos de elementos en el documento de salida utilizando las descripciones de elementos especificadas en un archivo separado.
- Llevando la descripción de los formatos de elementos a una sola vista en la estructura de la plantilla Matryoshka, independientemente de la plantilla utilizada en el diseño de esquemas XSD.
A pesar de la prevalencia del uso de XSD y la gran cantidad de software que funciona con él, todavía no encontré una herramienta que cumpliera al menos parcialmente estos requisitos.
Sin embargo, el problema era más relevante que nunca y se creó dicha herramienta ...
6. Decisión
Para aquellos que estén interesados en mirar la herramienta, les proporcionaré enlaces en los comentarios después del artículo, pero dentro del marco del artículo es más interesante ver el resultado, como un ejemplo de documentación de formatos de mensajes.
6.1. Un ejemplo de procesamiento de un esquema documentado
Aquí está el resultado de la descripción de los formatos de los elementos obtenidos del esquema XSD con la "documentación" completa.
6.1.1. Circuito fuente
Encabezado 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. El resultado
6.2. Ejemplo de descripción externa
Aquí está el resultado de la descripción de los formatos de elementos obtenidos del esquema XSD con documentación en blanco.
6.2.1. Circuito fuente
Encabezado 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. Datos de archivo de descripción externa
Encabezado de spoiler \matr . Customer . CustomerId ID . FirstName . LastName . Address . StreetAddress . City . Zip . >>> .
6.2.3. El resultado
¡Tenga en cuenta que el resultado obtenido es completamente idéntico al resultado del procesamiento del esquema documentado!
6.3. Un ejemplo de comparación de dos esquemas
Aquí hay una descripción de los formatos de elementos obtenidos al comparar diferentes versiones del esquema XSD.
6.3.1. Circuito fuente
Encabezado 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. Versión anterior del esquema
Encabezado 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. El resultado
Los nuevos elementos FirstName, LastName y Zip tienen todas las columnas en negrita. La posición del elemento "Dirección" ha cambiado: solo la primera columna se resalta en negrita. Los elementos "Nombre completo" y "País" eliminados aparecen atenuados. El fondo de las líneas también ayuda a "leer" los cambios.
Esta presentación hace que las diferencias sean fáciles de leer tanto en pantalla como impresas.
7. Resumen
Ahora, para hacer una nueva versión del álbum de formatos para varios cientos de circuitos XSD, solo lleva unos minutos. El archivo de salida en el formato de un documento de Word se obtiene con un tamaño de casi 1,500 hojas. Los problemas de errores en la descripción desaparecieron, y lo más importante, la irrelevancia de la descripción de los esquemas. Por lo tanto, resultó automatizar con éxito una de las áreas más laboriosas en la gestión del desarrollo de aplicaciones.