Formatuoti ir įtraukti XML

Skydelis
Dokumentacija
API

formatuoja XML kodą struktūrizuotu ir skaitomu būdu, būtinas jūsų duomenų mainų skaitymui

Kodėl formatuoti XML?

XML formatavimas (dar vadinamas XML formatavimu, XML įtrauka arba gražiu spaudiniu) susideda iš pertvarkyti kompaktišką arba sumažintą XML dokumentą į įtrauktą struktūrą, skaitomą eilutę po eilutės. Gerai suformatuotas XML pagerina skaitomumą, o tai labai svarbu skaitant SOAP atsakymą, naršykite RSS kanalą arba patikrinkite konfigūracijos failo turinį.

Konkrečiai, mes formatuojame savo XML dėl keturių pagrindinių priežasčių:

Derinimas: greitai pastebėkite neuždarą žymą, trūkstamą atributą arba nenuoseklią struktūrą.
Rankinis integravimas: aiškiai nukopijuokite fragmentą į konfigūracijos failą nepažeidžiant esamos įtraukos.
Kodo peržiūra: palyginkite dvi XML dokumento versijas Git skirtume, kuris tampa skaitomas, kai kiekviena žyma yra atskiroje eilutėje.
Dokumentacija ir pavyzdžiai: suformatuotas XML yra daug mokomesnis techniniame dokumente arba README.

Tipiški naudojimo atvejai

XML išlieka visur programinės įrangos ekosistemoje. Čia pateikiami formatai, kuriuos naudoja kūrėjai dažniausiai naudojamas XML formatuotojas:

SOAP atsakymai: vokai, kuriuos grąžino SOAP žiniatinklio paslaugos, paprastai pristatomi sumažėję.
RSS ir Atom sklaidos kanalai: sindikavimo sklaidos kanalo apžiūrai arba auditui.
Spring, Maven (pom.xml), Ant, Ivy konfigūracijos: „Java“ kūrimo ir priklausomybės failai.
AndroidManifest.xml ir kiti „Android“ projekto XML ištekliai.
SVG failai: vektorinė grafika, eksportuota iš projektavimo programinės įrangos, dažnai suglaudinama į vieną eilutę.
El. prekybos eksportas: „Google“ apsipirkimo produktų sklaidos kanalai, „Magento“, „Shopify“ arba „PrestaShop“ eksportavimas.
OOXML dokumentai: .docx, .xlsx ir .pptx failai yra ZIP archyvai, kuriuose yra XML failų, kuriuos dažnai reikia tikrinti.
XML svetainių schemos: sitemap.xml pateikiama paieškos sistemoms.

Kaip veikia XML formatavimas

XML formatuotojas ne tik prideda tarpų atsitiktinai. Jis atlieka du veiksmus:

Išanalizavimas: dokumentas nuskaitomas, tada paverčiamas DOM (dokumento objekto modelio) medžiu. Šis veiksmas taip pat patvirtina, kad XML yra gerai suformuotas (tinkamai įdėtos žymos, atributai kabutėse, vienas šakninis elementas).
Serializavimas su įtrauka: DOM medis iš naujo išleidžiamas kaip tekstas su eilučių pertraukomis tarp elementų ir įtrauka, proporcinga medžio gyliui.

Šis medžio metodas užtikrina, kad dokumento loginė struktūra išliktų griežtai identiška: keičiami tik nereikšmingi tarpai tarp žymų. CDATA skyriai, komentarai ir apdorojimo instrukcijos išsaugomos. Pažangesnės transformacijos (XSLT) arba užklausos (XPath) veikia tame pačiame DOM medyje.

Kaip naudotis XML formatu

Procedūra yra sąmoningai paprasta:

Įklijuokite XML dokumentą į teksto laukelį arba įkelkite .xml failą.
Patvirtinkite formą: dokumentas analizuojamas ir įtrauka automatiškai.
Suformatuotas rezultatas rodomas išvesties srityje. Įvykus analizavimo klaidai, pranešimas nurodo problemos pobūdį ir apytikslę padėtį.
Nukopijuokite rezultatą naudodami tam skirtą mygtuką arba atsisiųskite jį, kad integruotumėte tiesiogiai į projektą.

XML įtraukos geriausia praktika

Kai kurios taisyklės, kurių reikia laikytis norint sukurti švarų ir patvarų XML:

Įtrauka: 2 arba 4 tarpai, atsižvelgiant į jūsų komandos susitarimą. Būkite nuoseklūs viso projekto metu.
Eilučių lūžiai: vienas elementas eilutėje, todėl galima naudoti Git skirtumus.
CDATA skiltys: geras formatuotojas išlaiko visus blokus, nepertraukdamas jų turinio, kuris laikomas paprastu tekstu.
Kodavimas: visada nurodykite kodavimą pirmoje eilutėje naudodami . UTF-8 yra de facto standartas.
Atributai: jei elementas turi daug atributų, kai kurios komandos juos apvynioja, kad būtų lengviau perskaityti; kitu atveju jie lieka toje pačioje eilutėje kaip ir pradžios žyma.
Komentarai: treneris turi išlaikyti tokį, koks yra .

Pavyzdys prieš / po

Štai konkretus kompaktiško XML, kurį puošia formatuotojas, pavyzdys.

Prieš (viena eilutė, neįskaitoma):

valval2

Po (suformatuota 2 tarpais):


<šaknis>
  val
  val2

Loginė struktūra griežtai identiška: keičiasi tik vizualinis išdėstymas.

Pilnas pavyzdys

Didesnis XML dokumentas po formatavimo atrodo taip:


<šaknis>
  
    Džonas Doe
    johndoe@example.com
    
      123 Pagrindinė g.
      Springfield
      JIS
      62704
      JAV
    
    
      555-1234
      555-5678
    
    
      tiesa
      tamsi
    
    2024-06-14T09:30:00Z

Dažnai užduodami klausimai

Kas yra gerai suformuotas XML?

Sakoma, kad XML yra gerai suformuotas, kai jis atitinka pagrindines sintaksines taisykles: vienas šakninis elementas, teisingai įdėtos ir uždarytos žymos, atributai kabutėse, atskirti specialieji simboliai (&, <, >). Tai būtina sąlyga norint išanalizuoti dokumentą. Negalima painioti su galiojančiu XML, kuris taip pat atitinka XSD schemą arba DTD.

Kuo skiriasi formatavimas (gražiai atspausdintas) ir XML sumažinimas?

Gražus spausdinimas prideda eilučių pertraukų ir įtraukų, kad galėtų skaityti. Sumažinimas veikia priešingai: pašalina visus nereikšmingus tarpus, kad sumažintų dokumento dydį, o tai naudinga siunčiant tinklą (SOAP atsakymai, XML API). Abu dokumentai semantiškai lygiaverčiai.

Ar formatuojant išsaugomi CDATA komentarai ir skyriai?

Taip. Tinkamas formatuotojas išsaugo komentarus, skyrius ir apdorojimo instrukcijas (). CDATA turinys lieka nepažeistas be pakartotinio įtraukimo, nes jis traktuojamas kaip paprastas tekstas. Patikrinkite rezultatą, jei jūsų komentarai yra dokumentiškai svarbūs.

Ar palaikomos XML vardų erdvės (xmlns)?

Taip. Vardų erdvės deklaracijos (xmlns:soap="...") ir susiję priešdėliai () išsaugomi tokie, kokie yra. Formatuotojas nepervardija priešdėlių ir neperkelia deklaracijų medyje, užtikrindamas, kad dokumento semantika išliktų tokia pati. Numatytosios vardų erdvės (be priešdėlio) taip pat palaikomos jų deklaravimo lygiu.

Ar turėtume įtraukti tarpus ar tabuliavimo ženklus?

Abu veikia, tačiau tarpai yra dominuojantis susitarimas, nes jie visur rodomi vienodai (terminalai, naršyklės, Git skirtumas). 2 arba 4 tarpai, atsižvelgiant į jūsų XML išsamumą: 2 labai įdėtiems dokumentams (SVG, pavasario konfigūracijos), 4 plokštiems dokumentams. Svarbiausia išlieka nuoseklumas viso projekto metu.

Ar formatavimo priemonė pakeičia dokumento semantiką?

Ne. Koreguojami tik tarpai tarp žymų. DOM struktūra, atributų reikšmės ir elementų tekstinis turinys išlieka tie patys. Viena išimtis: prasmingas tekstinis turinys (su xml:space="preserve") turėtų būti paliktas toks, koks yra. Patikrinkite šį aspektą, jei jūsų duomenyse yra prasmingų tarpų.

Ar galime patvirtinti XML tuo pačiu metu, kai jį formatuojame?

Formatuotojas jau atlieka sintaksinį patvirtinimą (gerai suformuotą XML), nes turi išanalizuoti dokumentą. Norint patvirtinti pagal XSD schemą arba DTD, jums reikia tam skirto įrankio: struktūrinis patvirtinimas neapsiriboja paprasto formatavimo sritimi. Šiam papildomam veiksmui tinka xmllint --schema arba xerces.

Užklausos pavyzdys

curl -X POST https://cdrn.fr/api/v1/tools/xml-formatter/execute \
  -H "Content-Type: application/json" \
  -d '{"input":"..."}'

Įvesties schema

Laukas	Tipas	Privalomas	Numatytasis
`input`	text	✓	–

Galiniai taškai

GET https://cdrn.fr/api/v1/tools - išvardija visus galimus įrankius
GET https://cdrn.fr/api/v1/tools/xml-formatter - gauna šio įrankio schemą
POST https://cdrn.fr/api/v1/tools/xml-formatter/execute - vykdo šį įrankį su JSON payload