システム開発でのmybatis-generatorの利用

システム開発における製造工程の前段では、開発メンバの負荷軽減や共通化のために、各テーブルに対するSELECT/INSERT/UPDATE/DELETEを容易に行うための共通クラスを準備することが望まれます。
ここでは、mybatis-generator(MBG)を使って、このような共通クラスを作成するための方法について説明します。（私個人的には、システム開発におけるDB操作フレームワークとしてmybatisをお薦めしていることもあって、mybatis-generatorの話をしています。）

mybatis-generatorの使い方であれば他のサイトの情報で十分だと思いますが、ここでは、実際のシステム開発ででの使用を考慮して説明します。

1 MBGプロジェクトの説明
2 構成内容
- 2.1 pom.xml
- 2.2 generatorConfig.xml

MBGプロジェクトの説明

実際のシステム開発を想定したプロジェクト構成を前提としています。
mavenマルチプロジェクト構成例で、mybatis-generatorを実行するためのmavenプロジェクトzzz-common-mbgを作成して、mybatis-generator(mybatis-generator-plugin)を実行する想定で説明します。
mybatis-generatorプラグインの実装を前提とします。
mybatis-generatorの既定の動作では、暗号化や更新時楽観ロック等の案件固有の要件を満たせない場合があります。ここではそのような状況を想定し、mybatis-generatorが生成するクラスやファイルをカスタマイズするためのmybatis-generatorプラグイン(以後「独自プラグイン」と表記)を実装します。
独自プラグインのビルドとmybatis-generator実行を同一プロジェクトに統合しています。
mybatis-generator-pluginに独自プラグインを組み込むためには、mybatis-generator-pluginの依存関係で独自プラグインを含むパッケージ(jar)を宣言する必要があります。一般的に、独自プラグインを格納するプロジェクトを別途生成する場合がありますが、ここでは自プロジェクト内に独自プラグインを含めてmybatis-generatorを実行できるようにしています。
packageゴールの実行のみでmybatis-generatorを実行できるようにしています。
本来であれば、独自プラグインをパッケージ後(packageゴール)に、mybatis-generator-pluginを実行(mybatis-generator:generateゴール)する必要がありますが、この操作は手間なので一括でできるような構成にしています。

構成内容

独自プラグインやmybatis-generatorの動作を決定するためにpom.xml、mybatis-generatorの構成ファイルとなるgeneratorConfig.xmlについて説明します。
（それぞれ説明が長くなるので先にサンプルを提示して説明します。）

pom.xml

<project xmlns="http://maven.apache.org/POM/4.0.0"
	xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
	xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
	<modelVersion>4.0.0</modelVersion>
	<parent>
		<groupId>jp.mycomp.zzz</groupId>
		<artifactId>zzz-parent</artifactId>
		<version>1.0.0</version>
		<relativePath>..\zzz-parent\</relativePath>
	</parent>
	<artifactId>zzz-common-mbg</artifactId>

	<properties>
		<!-- 本ファイルやgeneratorConfig.xmlで使用する定数 -->
		<zzz.mbg.basedir>C:\jee7devkit\workspace\example-maven-mybatis</zzz.mbg.basedir>
	</properties>

	<!-- 独自プラグインの依存関係 -->
	<!-- (mybatis-generator-pluginのためのものではない) -->
	<dependencies>
		<!-- mybatis-generator -->
		<dependency>
			<groupId>org.mybatis.generator</groupId>
			<artifactId>mybatis-generator-core</artifactId>
			<version>1.4.0</version>
		</dependency>
		<!-- その他共通 -->
		<dependency>
			<groupId>org.apache.commons</groupId>
			<artifactId>commons-lang3</artifactId>
		</dependency>
		<dependency>
			<groupId>org.slf4j</groupId>
			<artifactId>slf4j-api</artifactId>
		</dependency>
	</dependencies>

	<build>

		<plugins>

			<!-- mybatis-generatorプラグイン定義 -->
			<plugin>
				<groupId>org.mybatis.generator</groupId>
				<artifactId>mybatis-generator-maven-plugin</artifactId>
				<version>1.4.0</version>
				<configuration>
					<!-- ★mybatis生成対象のプロジェクト設定を有効にしてください★ -->
					<configurationFile>${basedir}/src/main/resources/generatorConfig_f10.xml</configurationFile>
					<!-- <configurationFile>${basedir}/src/main/resources/generatorConfig_f20.xml</configurationFile> -->
					<!-- <configurationFile>${basedir}/src/main/resources/generatorConfig_z10.xml</configurationFile> -->

					<!-- mybatis生成時、既存クラス・XMLを上書 -->
					<!-- (XMLがマージされるのを防止するためにgeneratorConfig.xmlで -->
					<!-- UnmergeableXmlMappersPluginを宣言) -->
					<overwrite>true</overwrite>
				</configuration>
				<dependencies>
					<!-- プラグインで使用するJDBCドライバ(mariadb) -->
					<dependency>
						<groupId>org.mariadb.jdbc</groupId>
						<artifactId>mariadb-java-client</artifactId>
						<version>2.5.2</version>
					</dependency>
					<!-- 独自プラグイン(自プロジェクト)を依存関係に追加 -->
					<!-- 注意)リポジトリに登録されているとそちらが優先されるので -->
					<!-- installしないこと -->
					<dependency>
						<groupId>jp.mycomp.zzz</groupId>
						<artifactId>zzz-common-mbg</artifactId>
						<version>1.0.0</version>
						<scope>system</scope>
						<!-- installせずに自プロジェクト参照 -->
						<systemPath>${zzz.mbg.basedir}\zzz-common-mbg\target\zzz-common-mbg-1.0.0.jar</systemPath>
					</dependency>
				</dependencies>
				<executions>
					<!-- package時に合わせてmybatis生成 -->
					<execution>
						<phase>package</phase>
						<goals>
							<goal>generate</goal>
						</goals>
					</execution>
				</executions>

			</plugin>

		</plugins>

	</build>

</project>

pom.xmlや後述のgeneratorConfig.xmlで共通の定数(プロパティ)を使用するためにproperties要素でzzz.mbg.basedirを定義しています。
独自プラグインのビルドのためにdependencies要素で、mybatis-generator-core, org.apache.commons, org.slf4jを宣言しています。commonsとslf4jのバージョン宣言ですが、システム全体で使用するので親プロジェクトzzz-parentで宣言しています。
pluginsのplugin要素でmybatis-generator-pluginを定義します。mybatis-generatorに関する設定は、基本的にこの要素内で行います。指定可能な要素は、mybatis-generatorのリファレンスを参照のこと。
configuration要素内では次の設定を行います。
- configurationFile要素で、使用するmybatis-generator設定ファイルを指定します。
  サブシステム毎に独立してmybatis-generator設定を管理する想定であり、実行前に対象サブシステムの設定ファイルの宣言を有効化する必要があります。
- overwrite要素で、上書きオプションを有効化します。
  既定でmybatis-generatorは既存ファイルがあると”*.java.2″, “*.java.3″等の名前でファイルを作成します。この動作を回避するために本設定を有効にします。ただし、この設定だけではファイル作成時にマージ（変更箇所が追加）されてしまうので、mybatis-generatorのUnmergeableXmlMappersPluginを有効化します。
generatorConfig.xml(classPathEntry要素)でJDBCドライバの指定を行うこともできますが、パッケージ(jar)管理は可能な限りmavenで行う想定であるため、dependencies要素でJDBCドライバ(mariadb-java-client)を宣言しています。
mybatis-generator-pluginの依存関係として独自プラグイン(jar)を参照するためには、通常はリポジトリへのインストール(maven install)が必要です。独自プラグインは、mybatis-generatorの実行にしか使わないため、リポジトリへのインストールは行わず、relativePath要素で直接参照しています。
mavenのpackageゴールでmybatis-generatorを実行できるよう、execution要素にて、packageゴール時にgenerateゴールを実行するよう宣言しています。

generatorConfig.xml

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE generatorConfiguration
  PUBLIC "-//mybatis.org//DTD MyBatis Generator Configuration 1.0//EN"
  "http://mybatis.org/dtd/mybatis-generator-config_1_0.dtd">

<generatorConfiguration>

	<!-- JDBCドライバはpom.xmlで定義済のため、ここで宣言不要 -->
	<!-- <classPathEntry /> -->

	<!-- サブシステム: f10用の定義 -->
	<context id="f10" targetRuntime="MyBatis3">

		<!-- プラグイン -->
		<!-- * CDIでMapperを参照できるよう"@Mapper"を追加するプラグイン -->
		<plugin
			type="org.mybatis.generator.plugins.MapperAnnotationPlugin" />
		<!-- * XMLをマージしない(mybatis-generator-pluginのoverwrite設定も参考のこと) -->
		<plugin
			type="org.mybatis.generator.plugins.UnmergeableXmlMappersPlugin" />
		<!-- * 排他制御 -->
		<plugin
			type="jp.mycomp.zzz.common.mbg.plugin.OptimisticLockPlugin" />
		<!-- * 暗号化/復号化 -->
		<plugin
			type="jp.mycomp.zzz.common.mbg.plugin.EncryptColumnPlugin">
			<!-- 対象カラム(カンマ区切りで複数指定可) -->
			<property name="columns" value="" />
			<!-- 対象テーブル.カラム(カンマ区切りで複数指定可) -->
			<property name="tableColumns" value="mst_employee.name_enc" />
			<!-- INSERT/UPDATE時に使用される書式(@@はカラム名で置換) -->
			<property name="encryptFormat"
				value="aes_encrypt(@@, SHA2(@enckey))" />
			<!-- SELECT時に使用される書式(@@はカラム名で置換) -->
			<property name="decryptFormat"
				value="aes_decrypt(@@, SHA2(@enckey))" />
		</plugin>
		<!-- * 共通Entity追加 -->
		<plugin
			type="jp.mycomp.zzz.common.mbg.plugin.AddBaseEntityPlugin">
			<property name="baseClass"
				value="jp.mycomp.zzz.common.entity.BaseEntity" />
			<property name="excludeProperties"
				value="createdTimestamp,createdUserid,
				updatedTimestamp,updatedUserid,version" />
		</plugin>

		<!-- コメント生成の抑制 -->
		<commentGenerator>
			<property name="suppressDate" value="true" />
			<property name="addRemarkComments" value="false" />
		</commentGenerator>

		<!-- DB接続 -->
		<jdbcConnection driverClass="org.mariadb.jdbc.Driver"
			connectionURL="jdbc:mariadb://192.168.220.3/mybatis_example"
			userId="appuser" password="appuserpass" />

		<!-- モデル生成 -->
		<javaModelGenerator
			targetPackage="jp.mycomp.zzz.f10.common.entity"
			targetProject="${zzz.mbg.basedir}\zzz-f10-common\src\main\java" />

		<!-- Mapper XML生成 -->
		<sqlMapGenerator
			targetPackage="jp.mycomp.zzz.f10.common.mapper"
			targetProject="${zzz.mbg.basedir}\zzz-f10-common\src\main\resources" />

		<!-- Mapper生成 -->
		<javaClientGenerator type="XMLMAPPER"
			targetPackage="jp.mycomp.zzz.f10.common.mapper"
			targetProject="${zzz.mbg.basedir}\zzz-f10-common\src\main\java" />

		<!-- 対象テーブル -->
		<table schema="mybatis_example" tableName="%" modelType="flat" />

	</context>
</generatorConfiguration>

構成ファイルの詳細については、mybatis-generatorのマニュアルを参照のこと。なお、DTDで定義されている順番で定義しないとXMLバリデーションエラーになるので注意。
mybatis-generatorが出力するクラスやクエリ(XML)をカスタマイズできるよう、従来のモデル／マッパークラス／マッパーXMLファイルを使用します。(context要素のtargetRuntime属性にMyBatis3を指定)
plugin要素で、mybatis-generatorで提供されるプラグインや独自プラグインを指定します。独自プラグインについては、別途説明記事を追加予定です。
XMLマッパーファイルにXMLコメントが出力されると独自プラグインの実装(コメント除外)が複雑になるため、commentGenerator要素でコメント出力を抑制します。
javaModelGenerator, sqlMapGenerator, javaClientGenerator要素で参照している${zzz.mbg.basedir}は前述のpom.xmlで定義しています。
上記のAddBaseEntityPluginプラグインで、各モデルに対してシステム共通のEntityを継承できるよう、table要素のmodelType属性でflatを指定しています。(flat以外だとmybatis-generatorが自動生成したPKクラスが継承される場合があるため。)