Formatuj i wcinaj XML

Formatowanie XML (zwane też formatowaniem XML, wcięciem XML lub pretty print) polega na reorganizacji zwartego lub zminifikowanego dokumentu XML w wciętą strukturę, czytelną linia po linii. Dobrze sformatowany XML poprawia czytelność, co jest niezbędne, gdy trzeba przeczytać odpowiedź SOAP, przejrzeć kanał RSS lub sprawdzić zawartość pliku konfiguracyjnego.

Konkretnie formatujemy XML z czterech głównych powodów:

• Debugowanie: szybkie zlokalizowanie niezamkniętego tagu, brakującego atrybutu lub niespójnej struktury.
• Ręczna integracja: czyste skopiowanie fragmentu do pliku konfiguracyjnego bez psucia istniejącego wcięcia.
• Code review: porównanie dwóch wersji dokumentu XML w diffie Git staje się czytelne, gdy każdy tag jest na własnej linii.
• Dokumentacja i przykłady: sformatowany XML jest znacznie bardziej dydaktyczny w dokumentacji technicznej lub README.

XML pozostaje wszechobecny w ekosystemie oprogramowania. Oto formaty, na których programiści najczęściej używają formatera XML:

• Odpowiedzi SOAP: koperty <soap:Envelope> zwracane przez usługi sieciowe SOAP zazwyczaj przychodzą zminifikowane.
• Kanały RSS i Atom: do sprawdzenia lub audytu kanału syndykacji.
• Konfiguracje Spring, Maven (pom.xml), Ant, Ivy: pliki budowania i zależności Java.
• AndroidManifest.xml i inne zasoby XML projektu Android.
• Pliki SVG: grafika wektorowa wyeksportowana z oprogramowania projektowego jest często skompresowana w jednej linii.
• Eksporty e-commerce: kanały produktów Google Shopping, eksporty Magento, Shopify lub PrestaShop.
• Dokumenty OOXML: pliki .docx, .xlsx i .pptx to archiwa ZIP zawierające pliki XML, które często trzeba sprawdzić.
• Sitemapy XML: pliki sitemap.xml serwowane wyszukiwarkom.

Formater XML nie ogranicza się do dodawania spacji na chybił trafił. Wykonuje dwa kroki:

1. Parsowanie: dokument jest czytany, a następnie przekształcany w drzewo DOM (Document Object Model). Ten krok również waliduje, że XML jest poprawnie sformowany (tagi prawidłowo zagnieżdżone, atrybuty w cudzysłowach, jeden element główny).
2. Wcięta serializacja: drzewo DOM jest ponownie emitowane jako tekst ze znakami nowej linii między elementami i wcięciem proporcjonalnym do głębokości w drzewie.

To podejście drzewiaste gwarantuje, że logiczna struktura dokumentu pozostaje ściśle identyczna: modyfikowane są tylko nieznaczące spacje między tagami. Sekcje CDATA, komentarze i instrukcje przetwarzania są zachowywane. Bardziej zaawansowane transformacje (XSLT) lub zapytania (XPath) zresztą operują na tym samym drzewie DOM.

Procedura jest celowo prosta:

1. Wklej swój dokument XML w polu tekstowym lub prześlij plik .xml.
2. Wyślij formularz: dokument jest analizowany i automatycznie wcinany.
3. Sformatowany wynik pojawia się w obszarze wyjścia. W przypadku błędu parsowania komunikat wskaże naturę i przybliżoną pozycję problemu.
4. Skopiuj wynik dedykowanym przyciskiem lub pobierz go, aby bezpośrednio zintegrować w swoim projekcie.

Kilka konwencji do przestrzegania, aby produkować czysty i trwały XML:

• Wcięcie: 2 lub 4 spacje zgodnie z konwencją twojego zespołu. Bądź spójny w całym projekcie.
• Znaki nowej linii: jeden element na linię, co czyni diffy Git użytecznymi.
• Sekcje CDATA: dobry formater w pełni zachowuje bloki <![CDATA[ ... ]]> bez ponownego wcinania ich zawartości, która jest traktowana jako surowy tekst.
• Kodowanie: zawsze deklaruj kodowanie w pierwszej linii za pomocą <?xml version="1.0" encoding="UTF-8"?>. UTF-8 to standard de facto.
• Atrybuty: jeśli element ma wiele atrybutów, niektóre zespoły przenoszą je do nowej linii dla czytelności, w przeciwnym razie pozostają na tej samej linii co tag otwierający.
• Komentarze: <!-- ... --> muszą być zachowane bez zmian przez formater.

Oto konkretny przykład zwartego XML uładnionego przez formater.

Przed (jedna linia, nieczytelne):

<root><item id="1">val</item><item id="2">val2</item></root>

Po (sformatowane z 2 spacjami):

<?xml version="1.0" encoding="UTF-8"?>
<root>
  <item id="1">val</item>
  <item id="2">val2</item>
</root>

Logiczna struktura jest ściśle identyczna: zmienia się tylko wizualne ułożenie.

Bardziej obszerny dokument XML po formatowaniu wygląda tak:

<?xml version="1.0" encoding="UTF-8"?>
<root>
  <user id="12345">
    <name>John Doe</name>
    <email>johndoe@example.com</email>
    <address>
      <street>123 Main St</street>
      <city>Springfield</city>
      <state>IL</state>
      <postalCode>62704</postalCode>
      <country>USA</country>
    </address>
    <phoneNumbers>
      <phoneNumber type="home">555-1234</phoneNumber>
      <phoneNumber type="work">555-5678</phoneNumber>
    </phoneNumbers>
    <preferences>
      <newsletter>true</newsletter>
      <theme>dark</theme>
    </preferences>
    <lastLogin>2024-06-14T09:30:00Z</lastLogin>
  </user>
</root>