iBATIS 3 新特性深度解析：註解映射、XML 配置與遷移指南

iBATIS 3 (beta 9, 2010/01/23) 為完全重寫版，引入 Java 5 註解映射、簡化 XML 配置、新增遷移工具。本文通過 Automobile 實例展示註解與 XML 雙配置模式、API 變更及遷移要點。

核心模型與數據庫

// POJO
public class Automobile {
  private int id, year;
  private String make, model;
  // getter/setter/toString...
}

// Derby 建表
CREATE TABLE automobiles (
  id INT NOT NULL,
  make VARCHAR(255) NOT NULL,
  model VARCHAR(255) NOT NULL,
  model_year INT NOT NULL
);

XML 配置模式 (傳統)

映射文件 automobile-mapper.xml

<mapper namespace="com.example.model.Automobile">
  <resultMap type="Automobile" id="automobileResult">
    <result column="id" property="id" />
    <result column="make" property="make" />
    <result column="model" property="model" />
    <result column="model_year" property="year" />
  </resultMap>

  <select id="select" parameterType="int" resultType="Automobile" resultMap="automobileResult">
    select * from automobiles where id = #{id}
  </select>

  <insert id="insert" parameterType="Automobile">
    insert into automobiles (id, model, make, model_year)
    values (#{id}, #{model}, #{make}, #{year})
  </insert>

  <delete id="delete" parameterType="int">
    delete from automobiles where id = #{id}
  </delete>

  <delete id="deleteAll">
    delete from automobiles
  </delete>
</mapper>

主配置 ibatis-config.xml

<configuration>
  <typeAliases>
    <typeAlias type="com.example.model.Automobile" alias="Automobile" />
  </typeAliases>
  <environments default="development">
    <environment id="development">
      <transactionManager type="JDBC" />
      <dataSource type="POOLED">
        <property name="driver" value="org.apache.derby.jdbc.EmbeddedDriver" />
        <property name="url" value="jdbc:derby:/tmp/MyDB" />
      </dataSource>
    </environment>
  </environments>
  <mappers>
    <mapper resource="automobile-mapper.xml" />
  </mappers>
</configuration>

啟動代碼

Reader reader = Resources.getResourceAsReader("ibatis-config.xml");
SqlSessionFactory factory = new SqlSessionFactoryBuilder().build(reader);
SqlSession session = factory.openSession();
session.insert("com.example.model.Automobile.insert", new Automobile(1, "Toyota", "Tercel", 1993));
session.commit();

Java 5 註解配置模式 (新特性)

Mapper 接口替代 XML 映射

public interface AutomobileMapper {
  @Select("select id, make, model, model_year as \"year\" from automobiles where id = #{id}")
  Automobile selectAutomobile(int id);

  @Insert("insert into automobiles(id,make,model,model_year) values (#{id}, #{make}, #{model}, #{year})")
  void insertAutomobile(Automobile arg);

  @Delete("delete from automobiles")
  void deleteAll();
}

優勢：編譯期類型檢查、IDE 重構支持、接口繼承復用、中小項目更簡潔。局限：複雜映射 (ResultMap、動態 SQL) 仍需 XML。

程序化配置啟動

DataSource ds = new EmbeddedDataSource(); ds.setDatabaseName("/tmp/MyDB");
TransactionFactory txFactory = new JdbcTransactionFactory();
Configuration config = new Configuration(new Environment("development", txFactory, ds));
config.addMapper(AutomobileMapper.class);
SqlSessionFactory factory = new SqlSessionFactoryBuilder().build(config);

// 使用
SqlSession session = factory.openSession();
AutomobileMapper mapper = session.getMapper(AutomobileMapper.class);
mapper.insertAutomobile(new Automobile(1, "Toyota", "Tercel", 1993));
session.commit();

XML 配置關鍵變更 (從 2.x 遷移)

• 廢除 parameterMap：改用 `parameterType` + `#{property}` 直接訪問對象屬性
• DTD 升級：`ibatis-3-mapper.dtd`、`ibatis-3-config.dtd`
• 元素重組：結構更清晰，部分元素位置調整
• 遷移文檔 beta 9 尚在編寫中

iBATIS Schema Migrations (遷移工具)

非配置遷移，而是數據庫版本演進管理：生成可應用的 SQL 腳本，支持版本化、回滾、團隊協作，減少手工腳本錯誤。

總結

iBATIS 3 以映射為核心，平衡對象模型與關係設計。雙配置模式：

• 註解：中小項目、簡單映射、類型安全優先
• XML：複雜映射、動態 SQL、DBA 友好、存儲過程場景

配合遷移工具管理數據庫演進，構建可維護持久層。