XML 格式化與驗證：實用指南

你正在盯著一份 500 行的 XML 設定檔，某人在提交時完全沒有縮排。所有元素都擠在同一行。標籤巢狀深達六層，而你根本分不清一個區段在哪裡結束、另一個區段從哪裡開始。聽起來是不是很熟悉？

XML 仍然無處不在——從 Android 清單檔和 Maven 建置檔到 SOAP API 和企業資料串流。儘管 JSON 和 YAML 日益普及，XML 在處理複雜的文件結構、混合內容和嚴格驗證方面仍然優於任何替代方案。但問題是？格式不佳的 XML 確實令人痛苦不堪。

本指南將帶你了解實用的 XML 格式化規則、會導致解析器崩潰的常見錯誤，以及在錯誤進入正式環境之前就能捕獲它們的驗證技術。

為什麼 XML 格式化真的很重要

格式化不僅僅是外觀問題。它直接影響你的能力：

• 除錯問題 —— 在未格式化的 XML 中尋找不匹配的標籤，就像在一整面文字牆中找錯字一樣。適當的縮排可以讓層級結構一目了然。
• 審查變更 —— 當每個元素各佔一行時，版本控制的差異比對才會有意義。單行的 XML 大塊文字會產生無法閱讀的差異比對。
• 有效協作 —— 一致的格式化意味著團隊成員可以瀏覽不熟悉的設定檔，而不需要先費力解讀結構。
• 及早發現錯誤 —— 格式良好的 XML 能夠直觀地暴露結構性問題。當縮排一致時，巢狀層級錯誤的元素會立刻顯而易見。

XML 語法基礎

在深入格式化之前，讓我們先確立每個有效 XML 文件都必須遵守的語法規則。

XML 宣告

每個 XML 文件都應該以宣告開頭：

<?xml version="1.0" encoding="UTF-8"?>

這告訴解析器要使用哪個 XML 版本和字元編碼。雖然在技術上是可選的，但省略它會招來編碼錯誤——尤其是當文件包含非 ASCII 字元時。

元素與巢狀

元素是 XML 的基本構建單元。它們必須正確巢狀並關閉：

<!-- Correct nesting -->
<library>
  <book>
    <title>The Pragmatic Programmer</title>
    <author>David Thomas</author>
  </book>
</library>

<!-- Incorrect — overlapping tags -->
<book><title>Some Title</book></title>

每個開啟標籤都需要一個對應的關閉標籤，或者你可以對空元素使用自閉合語法：

<meta charset="UTF-8" />

屬性

屬性為元素新增中繼資料。值必須始終加上引號（單引號或雙引號）：

<book id="978-0135957059" language="en">
  <title>The Pragmatic Programmer</title>
</book>

當一個元素有許多屬性時，每行放一個屬性以提高可讀性：

<connection
  host="db.example.com"
  port="5432"
  database="production"
  ssl="true"
  timeout="30"
/>

命名空間

命名空間可防止在合併來自不同來源的 XML 時發生元素名稱衝突：

<root xmlns:app="http://example.com/app"
      xmlns:db="http://example.com/db">
  <app:config>
    <db:connection host="localhost" />
  </app:config>
</root>

始終在根元素或第一個使用命名空間的元素上宣告命名空間。避免在多個層級重複宣告相同的命名空間——這在語法上是有效的，但會造成混淆。

CDATA 區段

當你需要包含原本需要跳脫的文字（例如 HTML 或程式碼片段）時，使用 CDATA：

<template>
  <![CDATA[
    <div class="alert">
      Use <strong>bold</strong> for emphasis & special characters.
    </div>
  ]]>
</template>

CDATA 告訴解析器將裡面的所有內容視為純文字，因此 <、> 和 & 不需要跳脫。

註解

XML 註解遵循以下語法：

<!-- Database configuration for production environment -->
<database>
  <host>db.example.com</host>
</database>

註解不能包含雙連字號（--），也不能巢狀。保持註解簡潔且有意義——解釋為什麼，而不是是什麼。

XML 縮排逐步指南

一致的縮排能將不可讀的 XML 轉變為可掃描、可維護的文件。

規則 1：選擇縮排風格並堅持使用

使用 2 個空格、4 個空格或定位字元。XML 中最常見的慣例是 2 個空格，但一致性比具體的選擇更重要。

<!-- 2-space indentation (most common) -->
<config>
  <database>
    <host>localhost</host>
    <port>5432</port>
  </database>
</config>

規則 2：每個元素獨佔一行

每個元素都應有自己的一行。永遠不要把同級元素堆疊在同一行：

<!-- Bad -->
<name>John</name><age>30</age><role>Developer</role>

<!-- Good -->
<name>John</name>
<age>30</age>
<role>Developer</role>

規則 3：子元素縮排一個層級

每個子元素應比其父元素多縮排一個層級：

<employees>
  <employee id="1">
    <name>
      <first>Jane</first>
      <last>Smith</last>
    </name>
    <department>Engineering</department>
  </employee>
</employees>

規則 4：關閉標籤與開啟標籤對齊

關閉標籤的縮排層級應與開啟標籤相同：

<section>          <!-- Level 0 -->
  <header>         <!-- Level 1 -->
    <title>        <!-- Level 2 -->
      Main Page
    </title>       <!-- Level 2 — matches opening -->
  </header>        <!-- Level 1 — matches opening -->
</section>         <!-- Level 0 — matches opening -->

規則 5：簡短內容保持在同一行

當元素僅包含簡短的文字值時，保持在一行內：

<!-- Fine for short values -->
<city>Berlin</city>
<country>Germany</country>

<!-- Break to multiple lines for long values -->
<description>
  This is a much longer description that would make
  the line uncomfortably wide if kept inline.
</description>

常見 XML 錯誤及修復方法

以下是最常讓開發者踩坑的錯誤。

1. 標籤不匹配

<!-- Error: closing tag doesn't match -->
<Book>The Art of Code</book>

XML 是區分大小寫的。<Book> 和 <book> 是不同的元素。修復方法：確保開啟標籤和關閉標籤之間的大小寫完全一致。

2. 未跳脫的特殊字元

<!-- Error: bare & and < break the parser -->
<query>SELECT * FROM users WHERE age > 18 & active = true</query>

<!-- Fixed: use entity references -->
<query>SELECT * FROM users WHERE age &gt; 18 &amp; active = true</query>

XML 的五個預定義實體：

3. 缺少根元素

每個 XML 文件必須恰好有一個根元素：

<!-- Error: multiple root elements -->
<name>John</name>
<age>30</age>

<!-- Fixed: wrap in a single root -->
<person>
  <name>John</name>
  <age>30</age>
</person>

4. 屬性值未加引號

<!-- Error: unquoted attribute value -->
<item count=5 />

<!-- Fixed -->
<item count="5" />

5. 元素名稱中的無效字元

元素名稱不能以數字開頭，不能包含空格，也不能包含大多數特殊字元：

<!-- Error -->
<2nd-item>value</2nd-item>
<my item>value</my item>

<!-- Fixed -->
<second-item>value</second-item>
<my-item>value</my-item>

XML 驗證：DTD 與 XSD 結構描述

格式化確保可讀性，但驗證確保正確性。XML 支援兩種主要的驗證機制。

文件類型定義（DTD）

DTD 定義了 XML 文件的結構和允許的元素。它們簡單但有限：

<!DOCTYPE library [
  <!ELEMENT library (book+)>
  <!ELEMENT book (title, author, year)>
  <!ELEMENT title (#PCDATA)>
  <!ELEMENT author (#PCDATA)>
  <!ELEMENT year (#PCDATA)>
]>
<library>
  <book>
    <title>Clean Code</title>
    <author>Robert C. Martin</author>
    <year>2008</year>
  </book>
</library>

DTD 的限制： 不支援資料型別、不支援命名空間、表達能力有限。

XML 結構描述定義（XSD）

XSD 是現代的做法——它支援資料型別、命名空間和複雜的約束條件：

<xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema">
  <xs:element name="library">
    <xs:complexType>
      <xs:sequence>
        <xs:element name="book" maxOccurs="unbounded">
          <xs:complexType>
            <xs:sequence>
              <xs:element name="title" type="xs:string" />
              <xs:element name="author" type="xs:string" />
              <xs:element name="year" type="xs:gYear" />
            </xs:sequence>
            <xs:attribute name="id" type="xs:string" use="required" />
          </xs:complexType>
        </xs:element>
      </xs:sequence>
    </xs:complexType>
  </xs:element>
</xs:schema>

何時使用哪種：

• DTD —— 舊有系統、簡單的文件結構、向後相容性
• XSD —— 新專案、複雜的資料型別、命名空間支援、嚴格驗證

XML 與 JSON：何時選擇哪個

JSON 已成為 Web API 的預設選擇，但 XML 在特定場景中仍然勝出。我們在 CSV vs JSON vs XML 指南 中撰寫了詳細的比較，以下是簡要版本：

在以下情況選擇 XML：

• 需要混合內容（文字 + 元素）的文件標記
• 格式內建結構描述驗證
• 需要命名空間支援以合併不同詞彙
• 使用 XSLT 的轉換管線
• 強制使用 XML 的產業標準（SOAP、SVG、XHTML）

在以下情況選擇 JSON：

• Web API 的輕量級資料交換
• 簡單的鍵值對和陣列結構
• JavaScript 原生解析
• 更小的傳輸量

如需更深入了解資料格式的選擇，請參閱我們的資料序列化格式比較。

正式環境中 XML 的最佳實踐

設定檔

XML 在設定檔（Spring、Android、.NET）中仍然很受歡迎。保持它們的可維護性：

<?xml version="1.0" encoding="UTF-8"?>
<!-- Application configuration — Production -->
<config environment="production" version="2.1">
  <!-- Database settings -->
  <database>
    <connection
      host="${DB_HOST}"
      port="5432"
      name="app_production"
      pool-size="20"
    />
    <timeouts>
      <connect>5000</connect>
      <query>30000</query>
    </timeouts>
  </database>

  <!-- Cache settings -->
  <cache enabled="true">
    <ttl>3600</ttl>
    <max-entries>10000</max-entries>
  </cache>
</config>

建議：

• 對敏感值使用環境變數
• 將相關設定歸類在描述性的父元素下
• 為不明顯的設定選擇新增註解
• 包含版本屬性以追蹤設定結構描述的變更

API 資料交換

在使用 XML API 時，保持請求和回應的格式一致：

<?xml version="1.0" encoding="UTF-8"?>
<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
  <soap:Header>
    <auth:Token xmlns:auth="http://example.com/auth">
      Bearer abc123
    </auth:Token>
  </soap:Header>
  <soap:Body>
    <GetUserRequest xmlns="http://example.com/users">
      <UserId>42</UserId>
    </GetUserRequest>
  </soap:Body>
</soap:Envelope>

資料串流與整合

對於系統之間的資料交換，建立格式化契約：

• 在團隊之間統一縮排風格
• 記錄命名空間慣例
• 使用 XSD 結構描述作為資料結構的權威來源
• 在處理前驗證傳入的 XML 是否符合結構描述

專業 XML 格式化工具

手動格式化適用於小型檔案，但正式環境的 XML 需要適當的工具。在處理結構化資料時，專業格式化工具會自動處理縮排、驗證和語法高亮。

如果你經常處理資料格式，我們的 JSON 格式化工具 可處理 JSON 的美化和驗證。對於設定檔，YAML 工具套件 涵蓋 YAML 的格式化、轉換和驗證。

關於與你的 XML 工作流程互補的 JSON 格式化最佳實踐，請閱讀我們的 JSON 格式化最佳實踐指南。

總結

XML 格式化不僅僅是美觀的問題——它關乎讓文件可除錯、可比對差異和可維護。規則很簡單明瞭：一致的縮排、每個元素獨佔一行、正確的巢狀結構，以及跳脫特殊字元。

將良好的格式化與結構描述驗證（新專案建議使用 XSD）搭配使用，你就能在結構性錯誤導致正式環境問題之前很早就發現它們。無論你是在維護舊有的 SOAP 服務、撰寫 Android 佈局，還是建置資料管線，這些實踐都能保持你的 XML 整潔，並縮短除錯時間。