MyBatis Generator 完整配置詳解：從入門到精通

MyBatis Generator 完整配置詳解

MyBatis Generator (MBG) 是一款強大的代碼生成工具，能根據資料庫表結構自動生成 MyBatis 所需的實體類、Mapper 接口及 XML 映射文件。掌握其配置細節，能大幅提升開發效率。本文將通過一份詳細的配置範例，深度解析各核心節點的作用與參數設置。

配置文件結構概覽

MBG 的配置文件根節點為 <generatorConfiguration>，主要包含屬性引用、類路徑加載、上下文環境定義等核心區塊。以下為完整配置範例及關鍵點解析：

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE generatorConfiguration 
  PUBLIC "-//mybatis.org//DTD MyBatis Generator Configuration 1.0//EN" 
  "https://mybatis.org/dtd/mybatis-generator-config_1_0.dtd">
<generatorConfiguration>
  <!-- 1. 屬性引用：支持從外部 properties 文件或 URL 加載配置 -->
  <properties resource="com/myproject/generatorConfig.properties" />
  
  <!-- 2. 類路徑條目：指定 JDBC 驅動等依賴包路徑 -->
  <classPathEntry location="/path/to/mysql-connector-java.jar" />

  <!-- 3. 核心上下文環境 -->
  <context id="mysql" defaultModelType="hierarchical" targetRuntime="MyBatis3Simple">
    <!-- 基礎屬性配置 -->
    <property name="autoDelimitKeywords" value="false"/>
    <property name="javaFileEncoding" value="UTF-8"/>
    <property name="beginningDelimiter" value="`"/>
    <property name="endingDelimiter" value="`"/>

    <!-- 4. 資料庫連接配置 -->
    <jdbcConnection driverClass="com.mysql.cj.jdbc.Driver" 
        connectionURL="jdbc:mysql://localhost:3306/your_db?useSSL=false&serverTimezone=UTC" 
        userId="root" password="123456">
    </jdbcConnection>

    <!-- 5. Java 類型解析器：控制數據庫類型到 Java 類型的映射策略 -->
    <javaTypeResolver type="org.mybatis.generator.internal.types.JavaTypeResolverDefaultImpl">
      <property name="forceBigDecimals" value="false"/>
    </javaTypeResolver>

    <!-- 6. Java 模型生成器：生成實體類 -->
    <javaModelGenerator targetPackage="com.example.domain" targetProject="src/main/java">
      <property name="enableSubPackages" value="true"/>
      <property name="trimStrings" value="true"/>
      <property name="rootClass" value="com.example.domain.BaseEntity"/>
    </javaModelGenerator>

    <!-- 7. SQL Map 生成器：生成 Mapper XML 文件 -->
    <sqlMapGenerator targetPackage="com.example.mapper" targetProject="src/main/resources">
      <property name="enableSubPackages" value="true"/>
    </sqlMapGenerator>

    <!-- 8. Java Client 生成器：生成 Mapper 接口 -->
    <javaClientGenerator targetPackage="com.example.mapper" type="XMLMAPPER" targetProject="src/main/java">
      <property name="enableSubPackages" value="true"/>
    </javaClientGenerator>

    <!-- 9. 表配置：指定要生成代碼的表 -->
    <table tableName="user_info" domainObjectName="UserInfo">
      <property name="useActualColumnNames" value="false"/>
      <!-- 主鍵生成策略：MySQL 自增 -->
      <generatedKey column="id" sqlStatement="MySql" />
      <!-- 列名重命名規則：去除前綴 -->
      <columnRenamingRule searchString="^USER_" replaceString=""/>
      <!-- 列覆蓋：自定義屬性名、類型、TypeHandler -->
      <columnOverride column="user_name">
        <property name="property" value="userName"/>
      </columnOverride>
      <!-- 忽略列 -->
      <ignoreColumn column="deleted_flag" />
    </table>
  </context>
</generatorConfiguration>

核心節點深度解析

1. Context 節點：生成環境的核心

• id：唯一標識，用於錯誤提示定位。
• defaultModelType：決定生成模型風格：
  • flat：所有字段（主鍵、Blob、普通字段）生成在同一個類中。
  • hierarchical（推薦）：主鍵生成 XXXKey 類，Blob 字段生成單獨類，其餘字段在 Record 類中。
  • conditional：類似 hierarchical，但若無主鍵或 Blob 則退化為 flat。
• targetRuntime：
  • MyBatis3：生成完整功能，包含 Example 查詢（動態 SQL）。
  • MyBatis3Simple：輕量級，不生成 Example 相關代碼，適合手寫 SQL 場景。

2. JDBC 連接與類型解析

<jdbcConnection> 是連接資料庫的必備配置。<javaTypeResolver> 控制 DECIMAL/NUMERIC 類型映射：forceBigDecimals=true 強制用 BigDecimal；為 false 時，根據精度長度自動選擇 Integer/Long/Short/BigDecimal。

3. 三大生成器：Model、SQL Map、Client

這三個生成器的 targetPackage 和 targetProject 決定輸出路徑。關鍵屬性：

• enableSubPackages：為 true 時，會根據 Schema 再生成一層包結構。
• rootClass（Model）：指定基類，生成的實體類將繼承它，利於統一 id、createTime 等公共字段。
• trimStrings：true 時，Getter 中自動對 String 調用 trim()。
• type（Client）：
  • XMLMAPPER：接口依賴 XML，推薦使用。
  • ANNOTATEDMAPPER：SQL 寫在註解中。
  • MIXEDMAPPER：混合模式。

4. Table 節點：精細控制表級生成行為

除了必填的 tableName，還有大量可選屬性覆蓋 Context 默認值：

• domainObjectName：自定義實體類名，支持帶包名（如 com.example.entity.User）。
• enableInsert/SelectByPrimaryKey/UpdateByPrimaryKey/DeleteByPrimaryKey：控制基礎 CRUD 方法生成。
• enableSelectByExample/DeleteByExample/UpdateByExample/CountByExample：僅在 MyBatis3 運行時生效，控制動態 SQL 相關方法。
• generatedKey：配置主鍵回寫，MySQL 用 MySql（SELECT LAST_INSERT_ID()），PostgreSQL 用 JDBC。
• columnRenamingRule：正則替換列名前綴，如 searchString="^T_" 移除 T_ 前綴。
• columnOverride：針對單列自定義屬性名、Java 類型、JDBC 類型、TypeHandler。
• ignoreColumn：完全忽略某列，不生成屬性、不出現在 SQL 中。

最佳實踐建議

1. 採用 hierarchical 模型：職責清晰，利於擴展。
2. 統一使用 XMLMAPPER：SQL 與代碼分離，便於維護和優化。
3. 配置 rootClass：抽取公共字段（ID、時間戳、版本號），減少冗餘代碼。
4. 善用 columnOverride：處理命名不規範的列，或指定 JSON、枚舉等特殊類型的 TypeHandler。
5. 版本控制生成代碼：將生成代碼納入版本管理，便於追蹤變更。

常見問題排查

• 表名大小寫問題：MySQL 在 Linux 下區分大小寫，若建表用反引號指定大小寫，需設置 delimitIdentifiers="true" 並配合 beginningDelimiter/endingDelimiter。
• 生成代碼編碼亂碼：確保 javaFileEncoding="UTF-8" 且 IDE 文件編碼一致。
• Blob 字段未生成單獨類：確認 defaultModelType="hierarchical" 且表確實有 Blob/Clob 類型列。

掌握上述配置細節，您就能駕馭 MyBatis Generator 產出符合項目規範、高質量的持久層代碼，讓開發事半功倍。