您现在的位置：程式碼之家 >> 編程語言 > >> Java 程式設計 >> Java 相關知識

JAXB 實戰：Java 對象與 XML 雙向綁定完整指南（註解、上下文、序列化/反序列化）

編輯：Java 相關知識

前言：為什麼選 JAXB？

JAXB (Java Architecture for XML Binding) 是 Java 標準庫（Java 6-10）內置的對象-XML 映射框架，無需第三方依賴（Java 11+ 需額外引入 jaxb-api 與實現）。通過註解聲明式映射，實現 Java 對象與 XML 的雙向轉換，適合配置文件、報文交換、數據持久化等場景。

核心註解速查表

註解	作用目標	核心屬性	說明
`@XmlRootElement`	Class	name, namespace	標識 XML 根元素，類名默認
`@XmlElement`	Field/Getter	name, required, nillable	映射為 XML 子元素，字段名默認
`@XmlAttribute`	Field/Getter	name, required	映射為 XML 屬性
`@XmlAccessorType`	Class	value (FIELD/PROPERTY/PUBLIC_MEMBER/NONE)	控制默認映射策略，推薦 FIELD
`@XmlTransient`	Field/Getter	-	忽略該字段，不參與序列化
`@XmlType`	Class	propOrder, name, namespace	定義元素順序、類型名
`@XmlElementWrapper`	Field/Getter	name	為集合添加包裹元素
`@XmlJavaTypeAdapter`	Field/Class/Package	value	自定義類型轉換器

實體類建模示例

@XmlRootElement(name = "company")
@XmlAccessorType(XmlAccessType.FIELD) // 直接綁定字段，無需 Getter
public class Company {
    @XmlElementWrapper(name = "employees")
    @XmlElement(name = "employee")
    private List<Employee> employees = new ArrayList<>();

    public void addEmployee(Employee e) { employees.add(e); }
    // Getter/Setter 可省略（FIELD 模式）
}

@XmlAccessorType(XmlAccessType.FIELD)
@XmlType(propOrder = {"id", "name"}) // 指定輸出順序
public class Employee {
    @XmlElement(name = "id")
    private String id;

    @XmlElement(name = "name")
    private String name;
    // Getter/Setter
}

核心 API：JAXBContext、Marshaller、Unmarshaller

// 1. 創建上下文（線程安全，建議單例緩存）
JAXBContext ctx = JAXBContext.newInstance(Company.class); // 或包名 "com.example.model"

// 2. 序列化：對象 → XML
Marshaller marshaller = ctx.createMarshaller();
marshaller.setProperty(Marshaller.JAXB_FORMATTED_OUTPUT, true); // 縮進美化
marshaller.setProperty(Marshaller.JAXB_ENCODING, "UTF-8");
marshaller.marshal(company, System.out); // 輸出到 OutputStream/Writer/File/Node

// 3. 反序列化：XML → 對象
Unmarshaller unmarshaller = ctx.createUnmarshaller();
Company company = (Company) unmarshaller.unmarshal(new File("company.xml")); // 支持 InputStream/Reader/URL/Node

進階技巧

1. 命名空間處理

@XmlRootElement(name = "order", namespace = "https://example.com/ns")
@XmlSchema(namespace = "https://example.com/ns", elementFormDefault = XmlNsForm.QUALIFIED)
package com.example.model;
// package-info.java 中聲明 @XmlSchema

2. 自定義類型適配器（如 LocalDate → String）

public class LocalDateAdapter extends XmlAdapter<String, LocalDate> {
    private static final DateTimeFormatter FMT = DateTimeFormatter.ISO_LOCAL_DATE;
    public LocalDate unmarshal(String v) { return LocalDate.parse(v, FMT); }
    public String marshal(LocalDate v) { return v.format(FMT); }
}

// 使用
@XmlJavaTypeAdapter(LocalDateAdapter.class)
private LocalDate createDate;

3. 循環引用處理

使用 @XmlID / @XmlIDREF 或 @XmlTransient 打破循環，或配合 CycleRecoverable 自定義恢復邏輯。

4. 生成 Schema / 從 Schema 生成類

// 類 → XSD
marshaller.setSchema(schema); // 驗證輸出
ctx.generateSchema(new SchemaOutputResolver() { ... });

// XSD → 類 (xjc 命令或 maven-jaxb2-plugin)
xjc -d src/main/java -p com.example.model schema.xsd

常見坑點與最佳實踐

上下文復用：JAXBContext.newInstance 開銷大，必須緩存單例；
字段 vs Getter：統一使用 @XmlAccessorType(FIELD)，避免重複註解與邏輯不一致；
集合初始化：字段聲明處初始化 new ArrayList<>()，防止反序列化為 null；
異常處理：捕獲 JAXBException，區分驗證錯誤與映射錯誤；
大文件流式處理：超大 XML 改用 StAX + JAXB 片段解析，避免 OOM。

總結

JAXB 以註解驅動、零配置、標準庫內置三大優勢，成為 Java XML 綁定首選。掌握核心註解、上下文管理、Marshaller/Unmarshaller 配置，即可輕鬆實現對象與 XML 的高效雙向轉換。對於高性能、流式、複雜 Schema 場景，可搭配 StAX 或遷移至 Jackson XML 模塊。