Geekly articles weekly

Dokumentasi format pertukaran informasi - mudah dan sederhana

1. Pendahuluan


Kembali pada tahun 2001, konsorsium W3C membuat rekomendasi tentang Bahasa Definisi Skema XML (XSD), menggabungkan bahasa definisi skema paling populer ke dalam satu standar. Tujuan utama, yang dikejar dalam kasus ini, adalah untuk memperoleh standar platform-independen yang dapat digunakan oleh semua peserta dalam pertukaran informasi. Memanfaatkan kekacauan, XML telah menjadi format pertukaran informasi yang paling menarik. Saat ini, format XML dalam teknologi informasi digunakan sangat luas, jauh melampaui pertukaran data sederhana.

Popularitas dan luasnya penggunaan hasil XML baik dalam peningkatan volume dan komplikasi dari struktur data yang ditransmisikan dalam XML. Format JSON yang lebih muda dan lebih sederhana, yang “mengambil” semua arus informasi dari XML dengan struktur format pesan yang kurang lebih sederhana, juga berkontribusi pada proses ini. Hari ini kita memiliki fakta bahwa skema XSD yang menggambarkan struktur data pesan XML telah menjadi besar dan kompleks. Sangat sulit untuk membaca skema besar dan kompleks dalam bentuk teks, sehingga ada kebutuhan untuk perangkat lunak khusus dan dokumentasi terbaru yang menjelaskan format pesan XML.
Pada artikel ini saya akan berbicara tentang bagaimana masalah mendokumentasikan format pesan XML yang digunakan untuk pertukaran informasi diselesaikan ...



2. Masalah


Dokumentasi skema XSD terbaik adalah skema XSD itu sendiri. Aksioma ini benar sampai skema melebihi ambang batas kompleksitas tertentu atau Anda bertemu seseorang yang tidak tahu bagaimana atau tidak ingin membaca skema XSD. Saat mengembangkan aplikasi menggunakan skema XSD, Anda mungkin juga dihadapkan dengan persyaratan untuk menggambarkan format pesan yang dikembangkan dalam dokumentasi teknis atau yang menyertainya.

Jika Anda terhubung dengan pengembangan aplikasi dengan komponen yang digabungkan atau didistribusikan secara longgar dalam arsitektur berorientasi layanan, Anda terbiasa dengan konsep SOA (arsitektur berorientasi layanan) dan SOAP (Simple Object Access Protocol), maka tidak lama lagi akan tiba saatnya ketika Anda sendiri akan membutuhkan informasi terkini. ada lebih banyak dokumentasi daripada pelanggan Anda.

Karena itu, pertanyaan "Apakah saya perlu dokumentasi?" memiliki jawaban yang pasti "Ya", cepat atau lambat, semua orang yang terlibat dalam pengembangan perangkat lunak menggunakan XML akan menghadapi ini.

Pertanyaan jelas berikutnya adalah apa yang harus menjadi hasil dari mendokumentasikan format? Agak sulit untuk menjawab pertanyaan ini, karena konsumen yang berbeda dari hasilnya (arsitek, pengembang, analis, penulis teknis, administrator, perwakilan Pelanggan dan semua orang lain) memiliki tugas yang sama sekali berbeda.

Mereka memecahkan masalah ini dengan berbagai cara. Seseorang (misalnya, pengembang oXygen) menggunakan deskripsi lengkap skema XSD. Akibatnya, deskripsi menjadi lebih sulit untuk dipahami daripada skema itu sendiri. Yang lain bergantung pada kenyataan bahwa setiap orang harus dapat membaca skema XSD dan tidak diperlukan dokumentasi - kadang-kadang hanya karena mereka mengerti bahwa mereka tidak dapat mempertahankan relevansi dokumentasi ini. Seperti biasa, kebenaran terletak di antara ...

3. Esensi masalah


Proses pengembangan format pesan dapat direpresentasikan dalam langkah-langkah utama berikut (lihat gambar di bawah).



Iterasi No. 1:

  • 1. Tentukan jumlah data untuk pertukaran informasi - pada langkah ini jumlah data yang akan ditransmisikan antara peserta pertukaran informasi ditentukan - entitas, struktur dan hubungan atributifnya.
  • 2. Mengembangkan skema XSD - berdasarkan langkah No. 1, arsitek atau pengembang mengembangkan skema XSD, yang, di samping data itu sendiri, berisi mekanisme pesan SOAP yang diperlukan untuk transportasi, keamanan, dll.
  • 3. Jelaskan format pesan - pada langkah ini, dokumentasi dikembangkan yang menjelaskan format dan memberikan contoh pesan.
  • 4. Rekonsiliasi - pada langkah ini, verifikasi dan persetujuan format dilakukan dalam tim yang mengembangkan format ini. Jika ketidakakuratan ditemukan, iterasi pengembangan diulang.

Proses pengembangan format pesan adalah berulang. Setelah iterasi pertama selesai dan komentar diterima, selanjutnya dimulai segera dari langkah No. 2:

  • 2. Mengembangkan skema XSD - arsitek membuat perubahan pada skema XSD, ini membutuhkan waktu jauh lebih sedikit daripada pengembangan skema ini pada iterasi pertama.
  • 3. Jelaskan format pesan - analis atau penulis teknis harus memperbarui dokumentasi dengan deskripsi format.

    Dan di sini dia memiliki dilema: untuk membuat hanya perubahan-perubahan yang diinformasikan arsitek kepadanya atau menyimpang dari semua skema yang ukuran file-nya telah berubah. Apa pun, bahkan karyawan yang paling teliti akan memilih opsi pertama - dan akan salah. Opsi ini tidak berfungsi! - sangat sering ada perubahan yang tidak diumumkan dalam skema, yang arsitek atau pengembang lupa untuk melaporkan, dan dengan pendekatan ini deskripsi format tidak dapat dihindari akan berbeda dari skema. Apa yang mengancam ini? - ketika pengembangan dimulai, perbedaan akan ditemukan yang akan membawa sedikit kekacauan dan, pada tingkat yang berbeda, mempersulit pengembangan semua tim yang terlibat dalam integrasi.

    Mungkinkah ini lebih buruk? - ya, jika jadwal pengembangan untuk tim yang berpartisipasi berbeda. Salah satu tim di awal tahun, sesuai dengan spesifikasi, mengimplementasikan pengiriman pesan dengan data yang salah diisi dan berhasil menutup kontrak. Tim lain di pertengahan tahun menyadari penerimaan pesan-pesan ini dan menemukan perbedaan antara data yang diperlukan dan deskripsi mereka. Kali ini, kekacauan terjadi untuk waktu yang lama dan perbedaan antara format dan deskripsi mereka bisa terlalu mahal.

    Apa solusinya? Alas - satu-satunya pilihan tetap - untuk membuang waktu, semua pola yang berubah. Ini sangat sulit diterima. Sebuah dokumen dengan album format bisa memakan lebih dari seratus lembar dan menaburkannya, itu adalah pekerjaan yang sangat sulit dan melelahkan. Sangat sering, orang yang mengembangkan dokumen ini sangat tertekan oleh urgensi implementasi. Tidak semua orang mengerti mengapa mengubah uraian beberapa elemen dalam beberapa skema bisa "menghabiskan" sepanjang hari kerja atau bahkan lebih.

    Dengan demikian, langkah ini menjadi "penghambat" pembangunan, di mana setiap orang, dengan kemampuan terbaiknya, menentukan apa yang lebih berharga saat ini - kualitas atau waktu.
  • 4. Setuju - persetujuan pada awalnya masuk ke dalam tim mengembangkan format. Ketika koordinasi internal selesai, giliran koordinasi eksternal - untuk semua peserta pertukaran informasi.

Kemacetan yang terdeteksi menimbulkan pilihan yang sangat sulit antara kualitas dan waktu pengembangan. Hampir tidak mungkin untuk memilih di antara mereka karena kedua opsi diperlukan sekaligus!

4. Mendokumentasikan format pesan


Cara paling jelas untuk mendokumentasikan format adalah dengan pena. Buka diagram dan jelaskan elemen per elemennya, yang membutuhkan banyak waktu kerja. Jika skemanya besar atau ada banyak, maka dalam beberapa hari Anda akan mendapatkan warna merah spesifik dari mata seorang programmer profesional dan keengganan yang terus-menerus terhadap pekerjaan ini. Berikutnya datang pemahaman tentang apa yang tidak bisa, sehingga pekerjaan seperti itu tidak otomatis untuk waktu yang lama dan pencarian terus-menerus berikutnya untuk alat jadi.

Sebelum mencari alat otomasi, alangkah baiknya untuk memahami bagaimana Anda ingin menggunakannya dan apa yang harus menjadi hasil dari kerjanya?

Semua pekerjaan mendokumentasikan format pesan cocok dengan skenario penggunaan berikut:

  • Mendokumentasikan struktur elemen satu atau lebih skema XSD dengan "dokumentasi" yang terisi adalah pilihan termudah ketika kita membentuk dokumen dari satu sumber informasi (skema XSD). Biasanya ini adalah skema yang dikembangkan dalam tim sebagai bagian dari pekerjaan saat ini. Idealnya, jika pengembangan dilakukan dengan mempertimbangkan perjanjian tentang pengembangan skema, yang menunjukkan, tidak hanya bahwa elemen skema harus didokumentasikan, tetapi juga dengan konten dan kata-kata apa.
  • Mendokumentasikan struktur elemen dari satu atau lebih skema XSD dengan "dokumentasi" yang tidak terisi, atau terisi sebagian - opsi ini lebih rumit. Ini adalah skema yang dikembangkan oleh tim lain. Seringkali skema semacam itu secara teratur datang dari sisi "Apa adanya" dan kita tidak dapat menuntutnya. Dalam hal ini, hanya struktur yang dapat diambil dari sirkuit itu sendiri, dan deskripsi elemen harus ditambahkan dengan pena.
  • Perbandingan struktur elemen skema XSD versi yang berbeda - kami memiliki skema dan deskripsinya, dan sekarang skema telah berubah dan Anda perlu memperbarui deskripsi atau mendapatkan informasi tentang perubahan tersebut. Skema dapat berubah baik secara signifikan ketika elemen ditambahkan atau dihapus, atau murni secara kosmetik, ketika ruang tambahan dihapus dalam komentar dan file checksum telah berubah. Secara terpisah, harus dicatat kasus ketika skema sedang ditulis ulang menggunakan template lain - dalam hal ini, tidak ada yang berubah dari sudut pandang data, tetapi Anda dapat mengetahui yang lama hanya dengan menghabiskan banyak waktu untuk itu atau menggunakan perangkat lunak khusus. Mempertimbangkan bahwa skema dapat datang dalam paket ratusan, menjadi jelas bahwa membandingkan skema dengan mata adalah pekerjaan yang sangat sulit dan intensif sumber daya.

Adapun hasilnya, selama bertahun-tahun bekerja dengan skema dan dokumentasinya, saya mengembangkan pemahaman saya sendiri tentang apa hasil dari deskripsi format pesan yang seharusnya, yang disebut "dari bajak". Dasar dari konsep ini dapat dijelaskan hanya dalam tiga poin:

  • Rangkaian itu sendiri adalah sekunder - data primer. Selama pengembangan, kita tidak memerlukan deskripsi skema seperti itu - kita perlu deskripsi data yang dijelaskan skema ini. Faktanya, kita membutuhkan deskripsi format elemen dalam bentuk di mana mereka berada dalam pesan XML, atau dalam skema XSD yang dikembangkan menggunakan templat desain Doll Rusia (untuk detail lebih lanjut tentang templat desain, lihat artikel " Templat Desain XSD " ) Dalam bentuk ini adalah mudah untuk membahas skema tersebut baik selama pengembangan maupun setelahnya, selama integrasi atau pemeliharaan. Inilah yang ingin dilihat oleh Pelanggan dalam dokumentasi teknis.
  • Deskripsi format harus berupa tabel sederhana dan dapat dipahami dengan mana baik pengembang profesional dan mereka yang semuanya terkait dengan pengembangan adalah semacam "sihir" dapat bekerja sama dengan mudah. Akan selalu ada seseorang yang, sebagai sumber kritis atau konsumen informasi bagi Anda, menusuk jari di sirkuit XSD dan berkata: "Apa ini ???".
  • Semua item harus dijelaskan dalam format album satu kali. Ini berarti bahwa ketika menggambarkan elemen apa pun yang dikeluarkan dalam skema XSD terpisah, hanya elemen ini yang harus dijelaskan dalam tabel. Tidak perlu menarik seluruh format pesan SOAP di sana, tidak perlu memperluas jenis yang dijelaskan dalam skema yang diimpor. Pendekatan ini akan mencegah dokumen membengkak ke dimensi tidak senonoh dan lebih baik dibaca, dan jika perlu, menambahkan informasi tambahan pada elemen apa pun, Anda perlu melakukan ini di satu tempat!

Apa deskripsi format dalam dokumen? Dalam prosesnya, tabel dengan uraian format elemen skema XSD telah berulang kali berubah, baik oleh kumpulan kolom maupun isinya, hingga saya menerima kolom yang dijelaskan sebagai berikut:

  • "No. p / p" - di sini menunjukkan posisi elemen dalam diagram dalam bentuk daftar multi-level.
  • "Nama elemen dan tipenya" - data yang menunjukkan elemen ditampilkan di sini - nama elemen dan tipenya.
  • “Deskripsi elemen” - data bisnis pada elemen ditampilkan di sini - deskripsinya dari sudut pandang bisnis.
  • "Mengisi aturan" - data teknis ditampilkan di sini: aturan untuk mengisi elemen, format data, contoh nilai, dll.
  • "Mn." - kekuatan suatu elemen ditunjukkan di sini - kewajiban, multiplisitas dan kemungkinan memilih elemen.

Contoh deskripsi format diberikan di bawah ini di bagian "Solusi" ...

5. Menemukan solusi


Berdasarkan skenario penggunaan dan hasil yang diinginkan, persyaratan dasar untuk fungsi-fungsi alat yang seharusnya mengotomatiskan kegiatan ini telah dibentuk:

  • Pembuatan deskripsi format elemen untuk skema XSD yang dipilih.
  • Pembuatan deskripsi format elemen untuk semua skema XSD di folder yang dipilih dan folder turunannya.
  • Perbandingan deskripsi format elemen untuk skema yang dipilih (atau skema dalam folder) dan versi sebelumnya.
  • Memperkaya deskripsi format elemen dalam dokumen keluaran menggunakan deskripsi elemen yang ditentukan dalam file terpisah.
  • Membawa deskripsi format elemen ke tampilan tunggal dalam struktur template Matryoshka, terlepas dari template yang digunakan dalam desain skema XSD.

Meskipun prevalensi penggunaan XSD dan sejumlah besar perangkat lunak yang bekerja dengannya, saya masih tidak menemukan alat yang setidaknya memenuhi sebagian persyaratan ini.

Namun, masalahnya lebih relevan dari sebelumnya dan alat seperti itu dibuat ...

6. Keputusan


Bagi mereka yang tertarik melihat alat ini, saya akan memberikan tautan ke sana di komentar setelah artikel, tetapi dalam kerangka artikel itu lebih menarik untuk melihat hasilnya, sebagai contoh mendokumentasikan format pesan.

6.1. Contoh pemrosesan skema yang terdokumentasi


Berikut ini adalah hasil dari deskripsi format elemen yang diperoleh dari skema XSD dengan diisi dengan "dokumentasi".

6.1.1. Sumber sirkuit


Judul 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. Hasilnya




6.2. Contoh deskripsi eksternal


Berikut adalah hasil deskripsi format elemen yang diperoleh dari skema XSD dengan dokumentasi kosong.

6.2.1. Sumber sirkuit


Judul 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. Deskripsi File Data Eksternal


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


6.2.3. Hasilnya



Harap dicatat bahwa hasil yang diperoleh benar-benar identik dengan hasil pemrosesan skema terdokumentasi!

6.3. Contoh membandingkan dua skema


Berikut adalah deskripsi format elemen yang diperoleh dengan membandingkan berbagai versi skema XSD.

6.3.1. Sumber sirkuit


Judul 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 skema sebelumnya


Judul 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. Hasilnya



Elemen FirstName, LastName, dan Zip yang baru memiliki semua kolom dalam huruf tebal. Posisi elemen "Alamat" telah berubah - hanya kolom pertama yang disorot dalam huruf tebal. Item “Nama Lengkap” dan “Negara” yang dihapus berwarna abu-abu. Latar belakang garis juga membantu untuk "membaca" perubahan.

Presentasi ini membuat perbedaannya mudah dibaca baik di layar maupun di cetak.

7. Ringkasan


Sekarang, untuk membuat versi baru dari album format untuk beberapa ratus rangkaian XSD, hanya perlu beberapa menit. File output dalam format dokumen Word diperoleh dengan ukuran hampir 1.500 lembar. Masalah kesalahan dalam deskripsi menghilang, dan yang paling penting, tidak relevannya deskripsi skema. Dengan demikian, ternyata berhasil mengotomatisasi salah satu bidang yang paling padat karya dalam mengelola pengembangan aplikasi.

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

More articles:


All Articles