MyBatis Generatorの使い方｜2.0.0の設定・Maven実行・生成コードの選び方

MyBatis Generator（MBG）は、既存のデータベーステーブルを読み取って、Javaのモデルクラス・Mapperインターフェイス・SQLを自動生成するコード生成ツールです。2026年4月8日に公開された2.0.0ではJava 17が必須になり、Eclipseなしでのコードマージが可能になりました。一方で、日本語の解説記事の多くは1.3系・1.4系を前提にしており、手元で生成されるファイルが記事と違う、という食い違いが起きやすくなっています。この記事では、生成物がどの設定で決まるのか、Mavenでどう動かすのか、再生成で自作コードを壊さないにはどうするのかを、公式ドキュメントの現行仕様に沿って整理します。

まとめ

最新版は2.0.0（2026年4月8日公開）で、直前の安定版1.4.2（2023年2月20日）から3年ぶりのメジャーリリースです。動作要件はJava 17以上に引き上げられました。

生成されるファイルは<context>のtargetRuntimeで決まります。既定はMyBatis3DynamicSqlで、この場合XMLは生成されず、◯◯Example.javaのような検索条件クラスも作られません。古い記事に出てくるPostExample.javaやPostMapper.xmlを見たいなら、明示的にレガシーのMyBatis3を指定する必要があります。

再生成のたびに自作コードが消える問題は、2.0.0でjavaMergeEnabled（Mavenプラグインのパラメータ、既定false）に一本化されました。旧版で使われていた@mbggeneratedのような非標準コメントによる保護は廃止されています。以下、Mavenでの導入手順と、2.0.0で変わった点を順に見ていきます。

targetRuntime別の生成物の違い

MBGの解説記事を読んで混乱する原因のほとんどは、ここにあります。同じテーブル、同じ設定ファイルでも、targetRuntimeの値が違えば出てくるファイルの数も種類も変わります。

レガシー系の2ランタイムでXMLが出るかどうかは、<clientGenerator>のtype属性で決まります。XMLMAPPERならXMLに依存したMapperインターフェイス、ANNOTATEDMAPPERならアノテーションのみでXMLは生成されません（レガシー系ではこのtype属性は必須です）。この違いを押さえずに設定ファイルをコピーすると、「XMLが出てこない」「Exampleクラスが無い」といった行き違いになります。

既定のMyBatis3DynamicSql

何も指定しなければこのランタイムが使われます。生成されるのはモデルクラス、Mapperインターフェイス、そしてテーブル・カラムをJavaオブジェクトとして表現したサポートクラスの3種類で、SQLはアノテーションとDSLで表現されるためMapper XMLは作られません。生成コードはmybatis-dynamic-sqlライブラリに依存し、MBG 2.0.0が生成するコードは同ライブラリの2.0.0以降を要求します。プロジェクト側の依存に入れ忘れるとコンパイルが通りません。

検索条件はwhere(id, isEqualTo(1))のようなDSLメソッドで組み立てます。動的な条件分岐をJavaのコードとして書けるので、条件が増えるほどレガシーのExampleクラスより読みやすくなります。

レガシーのMyBatis3

2015年前後から日本語記事に登場し続けているのがこのランタイムです。テーブルごとにモデルクラス、主キークラス、◯◯Example.java、Mapperインターフェイス、Mapper XMLが生成されます。公式ドキュメントはこのランタイムについて「生成コード量が非常に多く（the amount of generated code is very large）」「クエリ構築の能力が限定的で拡張が難しい」と明記しています。

既存プロジェクトがこの形式で動いているなら、無理に乗り換える理由はありません。既存のMapper XMLと生成物の形式を揃える必要があるためです。ただしこれから新規に導入するなら、MyBatis3を選ぶ理由はほぼありません。Exampleクラスは複数条件のANDとORをネストさせると可読性が急激に落ち、結局は手書きのMapper XMLに逃げることになるからです。ORマッパー全体の選択肢を検討している段階であれば、Java ORM（O/Rマッパー）の種類と選び方でHibernateやjOOQとの立ち位置の違いも確認しておくと判断しやすくなります。

record生成とテーブル名の変換規則

2.0.0では、Kotlin以外のすべてのランタイムでモデルクラスをJavaのrecordとして生成できます。指定は<context>のdefaultModelType="record"で、テーブル単位で上書きするなら<table>側の属性名はmodelTypeになります（属性名が異なるため取り違えると設定ファイルの検証で落ちます）。ただしrecordは不変であるため、自動採番の生成キーを返すテーブルには使えません（MyBatisが生成キーをセッターで書き戻せないため）。フィールド数の多いテーブルでコンストラクタ呼び出しが長くなる問題には、RecordBuilderPlugin（ビルダーを追加）とRecordWithMethodsPlugin（値を1つ変えた新インスタンスを返すwithメソッドを追加）が用意されています。recordそのものの性質はレコードクラスとは何か？Javaプログラミングにおける基本的な理解で整理しています。

クラス名はテーブル名から自動変換されます。HOGE_PIYOというテーブルからはHogePiyo.javaが生成される、というアンダースコア区切りからパスカルケースへの変換が既定の挙動です。この規則を変えたい場合は<table>のdomainObjectName属性で明示的にクラス名を指定します。生成されるファイル名は他の生成物（Mapper・サポートクラス）の名前の土台にもなるため、途中で変更すると既存の参照が一斉に壊れます。命名はテーブル追加の初回に決め切ってください。

Mavenでの導入と実行

実務での入口はほぼMavenプラグインです。手順は依存の追加、設定ファイルの作成、ゴールの実行の3つに分かれます。

pom.xmlへのプラグイン追加

<build>
  <plugins>
    <plugin>
      <groupId>org.mybatis.generator</groupId>
      <artifactId>mybatis-generator-maven-plugin</artifactId>
      <version>2.0.0</version>
      <executions>
        <execution>
          <id>Generate MyBatis Artifacts</id>
          <goals>
            <goal>generate</goal>
          </goals>
        </execution>
      </executions>
      <dependencies>
        <dependency>
          <groupId>org.postgresql</groupId>
          <artifactId>postgresql</artifactId>
          <version>42.7.4</version>
        </dependency>
      </dependencies>
    </plugin>
  </plugins>
</build>

プラグインのクラスパスは初期状態ではMBG本体しか含みません。JDBCドライバはプロジェクトの依存ではなくプラグインの<dependencies>に書く必要があります。公式ドキュメントのサンプルもドライバをプラグインの<dependencies>側に置いており、ここを取り違えると「ドライバが見つからない」で停止します。プロジェクト側の依存を使い回したい場合は、プラグインパラメータのincludeCompileDependenciesまたはincludeAllDependenciesを有効にします。

generatorConfig.xmlの作成

設定ファイルの既定の置き場所は${basedir}/src/main/resources/generatorConfig.xmlです。別の場所に置くならconfigurationFileパラメータで明示します。

<?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>
  <context id="dsql" targetRuntime="MyBatis3DynamicSql">
    <jdbcConnection
        driverClass="org.postgresql.Driver"
        connectionURL="jdbc:postgresql://localhost:5432/sampledb"
        userId="app"
        password="secret" />
    <modelGenerator targetPackage="com.example.model" targetProject="MAVEN" />
    <!-- MyBatis3DynamicSql では type 属性は不要（指定しても無視される） -->
    <clientGenerator targetPackage="com.example.mapper" targetProject="MAVEN" />
    <table tableName="post" domainObjectName="Post" />
  </context>
</generatorConfiguration>

2.0.0では要素名がjavaModelGeneratorからmodelGeneratorへ、javaClientGeneratorからclientGeneratorへ改称されました（Kotlinも生成するため名称を汎用化したもの）。旧名も警告付きで動作するので、既存の設定ファイルがそのまま止まることはありません。targetProjectにMAVENを指定すると、出力先はビルドディレクトリ配下（既定でtarget/generated-sources/mybatis-generator）になり、生成コードがそのままビルドの対象に組み込まれます。生成物をリポジトリにコミットしたくない場合はこの方式が扱いやすくなります。

実行とコマンドラインからの起動

ゴールはmybatis-generator:generateの1つだけで、generate-sourcesフェーズにバインドされているためコンパイル前に自動実行されます。単体で走らせるなら次のコマンドです。

mvn mybatis-generator:generate
mvn -Dmybatis.generator.overwrite=true mybatis-generator:generate

overwriteは既定でfalseです。falseのまま同名ファイルが存在すると、MBGは上書きせずPost.java.1のような連番付きのファイルを別に書き出します。生成したはずの変更が反映されない、という現象の多くはこれです（なおXMLファイルは設定にかかわらず常にマージ・上書きされます）。Mavenを使わない場合は、配布JARを直接起動できます。

java -jar mybatis-generator-core-2.0.0.jar -configfile generatorConfig.xml -overwrite

javaMergeEnabledによる再生成時のコード保護

MBGの運用で最大の痛点は、テーブル変更のたびに走る再生成が、生成ファイルに手で足したメソッドを消してしまうことです。1.x系では、生成部分に付く非標準のJavaDocタグを目印にJDTでマージする仕組みがEclipseプラグイン側にあり、Eclipse以外の環境ではマージができませんでした。そのためMavenビルドでは「生成物には一切手を入れず、自作SQLは別のMapperインターフェイスとXMLに分ける」という回避策が定番になっていました。

2.0.0では、このJavaマージがコアライブラリに入り、Eclipseが不要になりました。有効化には2つの手当てが要ります。1つはプラグインパラメータjavaMergeEnabled（既定false）をtrueにすること。もう1つは、マージ実装が使うJavaParserをランタイムのクラスパスへ追加することです。

<dependency>
  <groupId>com.github.javaparser</groupId>
  <artifactId>javaparser-core</artifactId>
  <version>3.28.0</version>
</dependency>

バージョンは公式サンプルが挙げる3.28.0以降であれば構いません。

マージの目印は、2.0.0ではjakarta.annotation.Generatedアノテーションに一本化されました。旧版の@mbggeneratedのような非標準JavaDocタグはもう生成されません。ここに落とし穴があります。suppressAllCommentsをtrueにすると、コメントもアノテーションも一切出力されなくなり、Java・XMLのマージ機能が事実上無効になります。生成コードのコメントを抑えたい場合は、2.0.0で新設されたminimizeCommentsを指定してください。タイムスタンプなどを省き、マージに必要な最小限のアノテーションだけを残します。

なお、コア版のマージはJavaParserベースであるためEclipse版とは出力整形が異なり（importやメソッドの並び順、空白）、生成物に後付けした独自アノテーションは保持されません。生成クラスにアノテーションを足したい場合は、プラグインを実装して生成時に付与する方式に切り替える必要があります。

2.0.0への移行チェックリスト

1.4.2から2.0.0へ上げる際に、設定ファイルとビルドの見直しが要る箇所を挙げます。公式が「破壊的変更を最小限に抑えた」としているとおり大半のプロジェクトはバージョン番号の差し替えで動きますが、次の項目は黙って挙動が変わるため事前に確認してください。

実務で最初に効いてくるのは日付型です。useJSR310Typesプロパティは削除され、DATE・TIME・TIMESTAMPは常にLocalDate・LocalTime・LocalDateTimeにマッピングされます。1.4系でjava.util.Dateのまま運用していたプロジェクトは、生成モデルのフィールド型が変わるため、DTO変換やテストが一斉にコンパイルエラーになります。既存の型を維持したい場合は、<javaTypeResolver>のtypeにorg.mybatis.generator.internal.types.DateForcingJavaTypeResolverを指定して従来の挙動へ戻せます。まずこれを入れて既存コードを通し、型の移行はスケジュールを分けるのが安全です。

Java 17必須という要件は、実行するJVMに対するものです。Spring Boot 3系・4系を使っているなら前提を満たしていますが、Java 8のままのレガシー資産にMBGだけ新版を持ち込むことはできません。その場合は1.4.2に留めるのが妥当な判断です（Spring Boot 4とは？最新バージョン4.1の変更点でランタイム要件の全体像を確認できます）。

プラグインを自作している場合は影響が大きくなります。Contextクラスは設定情報だけを保持する形に整理されgetConnection()が削除（代替はConnectionUtility.getConnection(Context)）、contextGenerateAdditionalFiles()の戻り値型はList<GenericGeneratedFile>に変更、IntrospectedTable.getTargetRuntime()はgetKnownRuntime()へ置き換わっています。CommentGeneratorとJavaTypeResolverのインターフェイスも簡素化されたため、独自実装は書き換えが必要です。

生成対象テーブルの指定と実行時エラーの切り分け

テーブルを追加したのに生成されない場合は、<table>要素の指定漏れか、スキーマ名の不一致を疑ってください。<table tableName="%"/>と書けばスキーマ内の全テーブルが対象になりますが、監査テーブルや一時テーブルまで生成対象に入ります。実務では対象を明示列挙し、除外したいカラムは<ignoreColumn>で落とすほうが差分を追いやすくなります。

それ以外のトラブルは、既定値の思い込みが原因です。症状から原因へ引ける形でまとめます。

症状のうち「生成物が更新されない」は、エラーも警告も出ないままPost.java.1が横に置かれるだけなので気づきにくい種類の失敗です。ビルドが成功しているのに変更が反映されない、と感じたら真っ先にここを見てください。

よくある質問

MyBatis Generatorの最新バージョンは？

2026年7月時点の最新は2.0.0（2026年4月8日公開）です。Maven Centralのメタデータでもreleaseは2.0.0で、直前の安定版は1.4.2（2023年2月20日）でした。3年ぶりのメジャー更新なので、追随する日本語情報はまだ少なく、記事を読む際は前提バージョンを確認してください。

mybatis-generator-coreとmybatis-generator-maven-pluginの違いは？

mybatis-generator-coreが生成エンジン本体で、コマンドラインやJavaコードから直接呼び出すときに使います。mybatis-generator-maven-pluginはそれをMavenビルドに組み込むためのラッパーで、内部でcoreを使います。Mavenを使うならプラグインだけを追加すれば足り、coreを個別に宣言する必要はありません。バージョン番号は両者で揃えます。

generatorConfig.xmlはどこに置く？

Mavenプラグインの既定はsrc/main/resources/generatorConfig.xmlです。他の場所に置く場合はconfigurationFileパラメータ（${mybatis.generator.configurationFile}）でパスを指定します。DB接続情報を書くファイルなので、パスワードは<properties>要素で外部ファイル化するか、Mavenのプロパティ経由で渡してリポジトリにコミットしない運用にします。

Exampleクラスが生成されないのはなぜ？

既定のtargetRuntimeがMyBatis3DynamicSqlで、このランタイムはExampleクラスもMapper XMLも生成しないためです。<context targetRuntime="MyBatis3">と明示すれば◯◯Example.javaが生成されます。XMLまで欲しい場合は、レガシー系で必須の<clientGenerator type="XMLMAPPER">を併せて指定してください（ANNOTATEDMAPPERを指定するとXMLは生成されません）。ただし新規プロジェクトでは、条件構築の柔軟性で優る既定のDynamic SQL版を選ぶほうが後々楽になります。

生成コードに自分で書いたメソッドを残すには？

2.0.0ならjavaMergeEnabled=trueを指定し、JavaParserをクラスパスに追加すれば、再生成時に自作メソッドを保持したままマージされます。1.4.2以前でEclipseを使っていない場合はマージ機能が使えないため、生成物には手を入れず、自作SQLは別のMapperインターフェイス（および別XML）に分離してください。

関連記事

• Java ORM（O/Rマッパー）の種類と選び方｜Hibernate・MyBatis・jOOQを比較【2026年版】
• レコードクラスとは何か？Javaプログラミングにおける基本的な理解
• Spring Boot 4とは？最新バージョン4.1の変更点・新機能とSpring Boot 3との違いを解説【2026年最新】
• Spring Bootの主要なアノテーション一覧と基本的な役割