4.2 代码生成器文档

代码生成器是基于 MBG 插件的，所以需要配合 MBG 使用。

一个简单的 MBG 配置如下：

  1. <?xml version="1.0" encoding="UTF-8"?>
  2. <!DOCTYPE generatorConfiguration
  3.         PUBLIC "-//mybatis.org//DTD MyBatis Generator Configuration 1.0//EN"
  4.         "http://mybatis.org/dtd/mybatis-generator-config_1_0.dtd">
  6. <generatorConfiguration>
  7.     <context id="Mysql" targetRuntime="MyBatis3Simple" defaultModelType="flat">
  8.         <property name="javaFileEncoding" value="UTF-8"/>
  9.         <!--配置是否使用通用 Mapper 自带的注释扩展，默认 true-->
  10.         <!--<property name="useMapperCommentGenerator" value="false"/>-->
  12.         <!--通用 Mapper 插件，可以生成带注解的实体类-->
  13.         <plugin type="tk.mybatis.mapper.generator.MapperPlugin">
  14.             <property name="mappers" value="tk.mybatis.mapper.common.Mapper,tk.mybatis.mapper.hsqldb.HsqldbMapper"/>
  15.             <property name="caseSensitive" value="true"/>
  16.             <property name="forceAnnotation" value="true"/>
  17.             <property name="beginningDelimiter" value="`"/>
  18.             <property name="endingDelimiter" value="`"/>
  19.         </plugin>
  21.         <!--通用代码生成器插件-->
  22.         <plugin type="tk.mybatis.mapper.generator.TemplateFilePlugin">
  23.             <property name="targetProject" value="src/test/java"/>
  24.             <property name="targetPackage" value="test.mapper"/>
  25.             <property name="templatePath" value="generator/mapper.ftl"/>
  26.             <property name="mapperSuffix" value="Dao"/>
  27.             <property name="fileName" value="${tableClass.shortClassName}${mapperSuffix}.java"/>
  28.         </plugin>
  30.         <jdbcConnection driverClass="com.mysql.jdbc.Driver"
  31.                         connectionURL="jdbc:mysql://localhost:3306/test"
  32.                         userId="root"
  33.                         password="">
  34.         </jdbcConnection>
  36.         <!--MyBatis 生成器只需要生成 Model-->
  37.         <javaModelGenerator targetPackage="test.model" targetProject="./src/test/java"/>
  39.         <table tableName="user%">
  40.             <generatedKey column="id" sqlStatement="JDBC"/>
  41.         </table>
  42.     </context>
  43. </generatorConfiguration>

在这个配置中，我们只关注 tk.mybatis.mapper.generator.TemplateFilePlugin。

4.2.1 基于模板的插件 TemplateFilePlugin

这个插件中除了几个必备的属性外，还可以增加任意的属性，属性完全是为了给模板提供数据。

先看一个基本完整的配置：

  1. <!--测试输出单个文件，每个表都会生成一个对应的文件-->
  2. <plugin type="tk.mybatis.mapper.generator.TemplateFilePlugin">
  3.     <property name="singleMode" value="false"/>
  4.     <property name="targetProject" value="src/test/resources"/>
  5.     <property name="targetPackage" value=""/>
  6.     <property name="templatePath" value="generator/test-one.ftl"/>
  7.     <property name="fileName" value="${tableClass.shortClassName}Test.txt"/>
  8.     <!--默认值是下面这个，可以不配置-->
  9.     <property name="templateFormatter" value="tk.mybatis.mapper.generator.formatter.FreemarkerTemplateFormatter"/>
  10. </plugin>

下面介绍必备的属性。

1. targetProject

用于指定目标项目，一般是 src/main/java 或者 src/main/resource 这样的目录。
还可以是 src/test/java 或者 src/test/resource 这样的目录。

在多模块项目中，还能通过相对路径指定为其他的目录，例如：

  1. <property name="targetProject" value="../myproject-api/src/main/java"/>

这个属性值有一个要求，就是目录必须存在，否则不会生成代码!

2. targetPackage

用于指定包的部分，虽然是这个名字，实际上就是路径。

这个属性指定的路径如果不存在，就会自动创建。

这个属性的值可以为空。

例如 mapper/admin 用于生成 mapper/admin/ 目录，或者 tk.mybatis.mapper 生成包（本质上还是目录）。

这个属性还有一个特殊的地方，它还支持使用模板，就和下面的 fileName 一样，举个简单的使用场景。

你可能在生成前端代码的时候，希望将表对应的 JSP 生成在自己的一个目录中，此时可以配置为：

<property name="targetPackage" value="WEB-INF/jsp/${tableClass.lowerCaseName}/"/>

模板中可以用到的属性，这里都能用，其他属性后面会介绍。

通过这个路径也能看出来，配置一个插件只能根据模板在一个指定位置(targetProject 和 targetPackage 决定的目录)生成一个文件。

3. templatePath

指定模板路径，可以是任意能够通过 ClassLoader 能够获取的位置，文件类型没有限制。

例如示例中的 generator/test-one.ftl。

这个属性必须指定，否则不会生成代码!

4. fileName

这个属性用于指定生成文件的名字，这个值支持使用模板，例如上面的 ${tableClass.shortClassName}Test.txt，具体可用的属性会在后面介绍。

这个属性必须指定，否则不会生成代码!

5. templateFormatter

这个属性可选，默认使用基于 FreeMarker 的实现!

默认情况下，你需要添加下面的依赖：

  1. <dependency>
  2.     <groupId>org.freemarker</groupId>
  3.     <artifactId>freemarker</artifactId>
  4.     <version>2.3.23</version>
  5. </dependency>

默认的实现类为：tk.mybatis.mapper.generator.formatter.FreemarkerTemplateFormatter。

这个类实现了两个接口 TemplateFormatter, ListTemplateFormatter。

这俩接口分别对应下面 singleMode 参数值的 true 和 false。

也就是一个表生成一个文件，或者多个表生成一个文件。

对于一般情况下，都是第一种情况。但是在配置文件中，可能会用到多个表的信息。

如果你想使用其他模板引擎，可以自己实现上面的接口。

6. singleMode

上面已经提过，默认为 true。

一个表生成一个文件时，可用属性可以参考 generator/test-one.ftl，表的属性在 tableClass 中。

多个表生成一个文件时，可用属性可以参考 generator/test-all.ftl，所有表的属性在 tableClassSet 中，通过遍历可以获取单个的信息。

7. 其他你需要的属性

模板中需要的特殊信息都可以通过 <property> 方法设置，在模板中直接使用这里定义的属性名来使用，后面例子的中的 mapperSuffix 就是这种属性。

4.2.2 TemplateFilePlugin 配置示例

因为模板需要根据业务进行设计，所以这里只提供了两个简单的 mapper 目标和两个完整属性的示例模板。

因为一个模板只能生成一类的文件，所以如果要生成多个不同的文件，就需要配置多个插件。

这种设计很灵活，因为自由度很高，所以代价就是配置的多。

但是正常情况下，根据业务设计的一套模板基本是固定的，不会有太多变化，所以用起来并不麻烦。

例如下面的示例：

  1. <!--通用代码生成器插件-->
  2. <!--mapper接口-->
  3. <plugin type="tk.mybatis.mapper.generator.TemplateFilePlugin">
  4.     <property name="targetProject" value="src/test/java"/>
  5.     <property name="targetPackage" value="test.mapper"/>
  6.     <property name="templatePath" value="generator/mapper.ftl"/>
  7.     <property name="mapperSuffix" value="Dao"/>
  8.     <property name="fileName" value="${tableClass.shortClassName}${mapperSuffix}.java"/>
  9. </plugin>
  10. <!--mapper.xml-->
  11. <plugin type="tk.mybatis.mapper.generator.TemplateFilePlugin">
  12.     <property name="targetProject" value="src/test/resources"/>
  13.     <property name="targetPackage" value="mappers"/>
  14.     <property name="mapperPackage" value="test.mapper"/>
  15.     <property name="templatePath" value="generator/mapperXml.ftl"/>
  16.     <property name="mapperSuffix" value="Dao"/>
  17.     <property name="fileName" value="${tableClass.shortClassName}${mapperSuffix}.xml"/>
  18. </plugin>
  19. <!--测试输出单个文件，每个表都会生成一个对应的文件-->
  20. <plugin type="tk.mybatis.mapper.generator.TemplateFilePlugin">
  21.     <property name="targetProject" value="src/test/resources"/>
  22.     <property name="targetPackage" value=""/>
  23.     <property name="templatePath" value="generator/test-one.ftl"/>
  24.     <property name="fileName" value="${tableClass.shortClassName}Test.txt"/>
  25.     <!--默认值是下面这个，可以不配置-->
  26.     <property name="templateFormatter"
  27.               value="tk.mybatis.mapper.generator.formatter.FreemarkerTemplateFormatter"/>
  28. </plugin>
  29. <!--测试输出整个文件，所有表都可用，一次只生成一个文件，用于聚合所有表使用-->
  30. <plugin type="tk.mybatis.mapper.generator.TemplateFilePlugin">
  31.     <property name="singleMode" value="false"/>
  32.     <property name="targetProject" value="src/test/resources"/>
  33.     <property name="targetPackage" value=""/>
  34.     <property name="templatePath" value="generator/test-all.ftl"/>
  35.     <property name="fileName" value="TestAll.txt"/>
  36. </plugin>

前两个会生成 Dao 后缀的 Mapper 接口和 XML，其中有个针对性的参数 mapperSuffix 用于配置后缀，
还有个 mapperPackage 在生成 XML 时获取接口的包名（因为和这里的 targetPackage 可以不同）。

后两个插件用于演示所有可用的属性，而且是两种不同的模式。

在表和实体上可用的所有属性如下：

  1. 特殊：targetPackage值在 ${package} 中。
  3. <!-- 详细日期用法参考：http://freemarker.apache.org/docs/ref_builtins_date.html -->
  4. 当前时间：
  5. <#assign dateTime = .now>
  6. 日期：${dateTime?date}
  7. 时间：${dateTime?time}
  8. 格式化：${dateTime?string["yyyy-MM-dd HH:mm:ss"]}
  11. 所有配置的属性信息:
  12. <#list props?keys as key>
  13. ${key} - ${props[key]}
  14. </#list>
  16. 实体和表的信息：
  17. 表名：${tableClass.tableName}
  18. 变量名：${tableClass.variableName}
  19. 小写名：${tableClass.lowerCaseName}
  20. 类名：${tableClass.shortClassName}
  21. 全名：${tableClass.fullClassName}
  22. 包名：${tableClass.packageName}
  24. 列的信息：
  25. =====================================
  26. <#if tableClass.pkFields??>
  27. 主键：
  28.     <#list tableClass.pkFields as field>
  29.     -------------------------------------
  30.     列名：${field.columnName}
  31.     列类型：${field.jdbcType}
  32.     字段名：${field.fieldName}
  33.     注释：${field.remarks}
  34.     类型包名：${field.typePackage}
  35.     类型短名：${field.shortTypeName}
  36.     类型全名：${field.fullTypeName}
  37.     是否主键：${field.identity?c}
  38.     是否可空：${field.nullable?c}
  39.     是否为BLOB列：${field.blobColumn?c}
  40.     是否为String列：${field.stringColumn?c}
  41.     是否为字符串列：${field.jdbcCharacterColumn?c}
  42.     是否为日期列：${field.jdbcDateColumn?c}
  43.     是否为时间列：${field.jdbcTimeColumn?c}
  44.     是否为序列列：${field.sequenceColumn?c}
  45.     列长度：${field.length?c}
  46.     列精度：${field.scale}
  47.     </#list>
  48. </#if>
  50. <#if tableClass.baseFields??>
  51. 基础列：
  52.     <#list tableClass.baseFields as field>
  53.     -------------------------------------
  54.     列名：${field.columnName}
  55.     列类型：${field.jdbcType}
  56.     字段名：${field.fieldName}
  57.     注释：${field.remarks}
  58.     类型包名：${field.typePackage}
  59.     类型短名：${field.shortTypeName}
  60.     类型全名：${field.fullTypeName}
  61.     是否主键：${field.identity?c}
  62.     是否可空：${field.nullable?c}
  63.     是否为BLOB列：${field.blobColumn?c}
  64.     是否为String列：${field.stringColumn?c}
  65.     是否为字符串列：${field.jdbcCharacterColumn?c}
  66.     是否为日期列：${field.jdbcDateColumn?c}
  67.     是否为时间列：${field.jdbcTimeColumn?c}
  68.     是否为序列列：${field.sequenceColumn?c}
  69.     列长度：${field.length?c}
  70.     列精度：${field.scale}
  71.     </#list>
  72. </#if>
  74. <#if tableClass.blobFields??>
  75. Blob列：
  76.     <#list tableClass.blobFields as field>
  77.     -------------------------------------
  78.     列名：${field.columnName}
  79.     列类型：${field.jdbcType}
  80.     字段名：${field.fieldName}
  81.     注释：${field.remarks}
  82.     类型包名：${field.typePackage}
  83.     类型短名：${field.shortTypeName}
  84.     类型全名：${field.fullTypeName}
  85.     是否主键：${field.identity?c}
  86.     是否可空：${field.nullable?c}
  87.     是否为BLOB列：${field.blobColumn?c}
  88.     是否为String列：${field.stringColumn?c}
  89.     是否为字符串列：${field.jdbcCharacterColumn?c}
  90.     是否为日期列：${field.jdbcDateColumn?c}
  91.     是否为时间列：${field.jdbcTimeColumn?c}
  92.     是否为序列列：${field.sequenceColumn?c}
  93.     列长度：${field.length?c}
  94.     列精度：${field.scale}
  95.     </#list>
  96. </#if>
  98. =====================================
  99. 全部列（包含了pk,base,blob 字段，可用的属性和上面的一样）：
  100. <#if tableClass.allFields??>
  101. 列名 - 字段名
  102.     <#list tableClass.allFields as field>
  103.     ${field.columnName} - ${field.fieldName}
  104.     </#list>
  105. </#if>

4.2.3 测试执行

上面示例就是本项目的测试代码，在 src/test/resources/generator/generatorConfig.xml 中。

还提供了一种 Java 编码方式运行的类，src/test/java/ 中的 tk.mybatis.mapper.generator.Generator，配置上面 xml 中的数据库信息就可以生成。

测试生成的部分结果如下。

实体：

  1. @Table(name = "`user_info`")
  2. public class UserInfo {
  3.     @Id
  4.     @Column(name = "`Id`")
  5.     @GeneratedValue(generator = "JDBC")
  6.     private Integer id;

Dao：

  1. package test.mapper;
  3. import test.model.UserInfo;
  5. /**
  6. * 通用 Mapper 代码生成器
  7. *
  8. * @author mapper-generator
  9. */
  10. public interface UserInfoDao extends tk.mybatis.mapper.common.Mapper<UserInfo> {
  12. }

XML：

  1. <?xml version="1.0" encoding="UTF-8"?>
  2. <!DOCTYPE mapper
  3.         PUBLIC "-//mybatis.org//DTD Mapper 3.0//EN"
  4.         "http://mybatis.org/dtd/mybatis-3-mapper.dtd">
  5. <mapper namespace="test.mapper.UserInfoDao">
  7. </mapper>

test-one.ftl 生成的信息如下：

  1. 目标package: 
  3. 当前时间：
  4. 2017-11-6
  5. 22:00:45
  6. 2017-11-06 22:00:45
  8. 所有配置的属性信息:
  9. targetPackage - 
  10. templateFormatter - tk.mybatis.mapper.generator.formatter.FreemarkerTemplateFormatter
  11. templatePath - generator/test-one.ftl
  12. targetProject - src/test/resources
  13. fileName - ${tableClass.shortClassName}Test.txt
  15. 实体和表的信息：
  16. 表名：user_info
  17. 变量名：userInfo
  18. 小写名：userinfo
  19. 类名：UserInfo
  20. 全名：test.model.UserInfo
  21. 包名：test.model
  23. 列的信息：
  24. =====================================
  25. 主键：
  26.     -------------------------------------
  27.     列名：Id
  28.     列类型：INTEGER
  29.     字段名：id
  30.     注释：
  31.     类型包名：java.lang
  32.     类型短名：Integer
  33.     类型全名：java.lang.Integer
  34.     是否主键：true
  35.     是否可空：false
  36.     是否为BLOB列：false
  37.     是否为String列：false
  38.     是否为字符串列：false
  39.     是否为日期列：false
  40.     是否为时间列：false
  41.     是否为序列列：false
  42.     列长度：10
  43.     列精度：0
  45. 基础列：
  46.     -------------------------------------
  47.     列名：username
  48.     列类型：VARCHAR
  49.     字段名：username
  50.     注释：用户名
  51.     类型包名：java.lang
  52.     类型短名：String
  53.     类型全名：java.lang.String
  54.     是否主键：false
  55.     是否可空：false
  56.     是否为BLOB列：false
  57.     是否为String列：true
  58.     是否为字符串列：true
  59.     是否为日期列：false
  60.     是否为时间列：false
  61.     是否为序列列：false
  62.     列长度：32
  63.     列精度：0
  64.     -------------------------------------
  65.     列名：password
  66.     列类型：VARCHAR
  67.     字段名：password
  68.     注释：密码
  69.     类型包名：java.lang
  70.     类型短名：String
  71.     类型全名：java.lang.String
  72.     是否主键：false
  73.     是否可空：true
  74.     是否为BLOB列：false
  75.     是否为String列：true
  76.     是否为字符串列：true
  77.     是否为日期列：false
  78.     是否为时间列：false
  79.     是否为序列列：false
  80.     列长度：32
  81.     列精度：0
  82.     -------------------------------------
  83.     列名：usertype
  84.     列类型：VARCHAR
  85.     字段名：usertype
  86.     注释：用户类型
  87.     类型包名：java.lang
  88.     类型短名：String
  89.     类型全名：java.lang.String
  90.     是否主键：false
  91.     是否可空：true
  92.     是否为BLOB列：false
  93.     是否为String列：true
  94.     是否为字符串列：true
  95.     是否为日期列：false
  96.     是否为时间列：false
  97.     是否为序列列：false
  98.     列长度：2
  99.     列精度：0
  100.     -------------------------------------
  101.     列名：enabled
  102.     列类型：INTEGER
  103.     字段名：enabled
  104.     注释：是否可用
  105.     类型包名：java.lang
  106.     类型短名：Integer
  107.     类型全名：java.lang.Integer
  108.     是否主键：false
  109.     是否可空：true
  110.     是否为BLOB列：false
  111.     是否为String列：false
  112.     是否为字符串列：false
  113.     是否为日期列：false
  114.     是否为时间列：false
  115.     是否为序列列：false
  116.     列长度：10
  117.     列精度：0
  118.     -------------------------------------
  119.     列名：realname
  120.     列类型：VARCHAR
  121.     字段名：realname
  122.     注释：真实姓名
  123.     类型包名：java.lang
  124.     类型短名：String
  125.     类型全名：java.lang.String
  126.     是否主键：false
  127.     是否可空：true
  128.     是否为BLOB列：false
  129.     是否为String列：true
  130.     是否为字符串列：true
  131.     是否为日期列：false
  132.     是否为时间列：false
  133.     是否为序列列：false
  134.     列长度：32
  135.     列精度：0
  136.     -------------------------------------
  137.     列名：qq
  138.     列类型：VARCHAR
  139.     字段名：qq
  140.     注释：QQ
  141.     类型包名：java.lang
  142.     类型短名：String
  143.     类型全名：java.lang.String
  144.     是否主键：false
  145.     是否可空：true
  146.     是否为BLOB列：false
  147.     是否为String列：true
  148.     是否为字符串列：true
  149.     是否为日期列：false
  150.     是否为时间列：false
  151.     是否为序列列：false
  152.     列长度：14
  153.     列精度：0
  154.     -------------------------------------
  155.     列名：email
  156.     列类型：VARCHAR
  157.     字段名：email
  158.     注释：
  159.     类型包名：java.lang
  160.     类型短名：String
  161.     类型全名：java.lang.String
  162.     是否主键：false
  163.     是否可空：true
  164.     是否为BLOB列：false
  165.     是否为String列：true
  166.     是否为字符串列：true
  167.     是否为日期列：false
  168.     是否为时间列：false
  169.     是否为序列列：false
  170.     列长度：100
  171.     列精度：0
  172.     -------------------------------------
  173.     列名：tel
  174.     列类型：VARCHAR
  175.     字段名：tel
  176.     注释：联系电话
  177.     类型包名：java.lang
  178.     类型短名：String
  179.     类型全名：java.lang.String
  180.     是否主键：false
  181.     是否可空：true
  182.     是否为BLOB列：false
  183.     是否为String列：true
  184.     是否为字符串列：true
  185.     是否为日期列：false
  186.     是否为时间列：false
  187.     是否为序列列：false
  188.     列长度：255
  189.     列精度：0
  191. Blob列：
  193. =====================================
  194. 全部列：
  195. 列名 - 字段名
  196.     Id - id
  197.     username - username
  198.     password - password
  199.     usertype - usertype
  200.     enabled - enabled
  201.     realname - realname
  202.     qq - qq
  203.     email - email
  204.     tel - tel

4.2.4 最后

基础的代码生成器是很简单的，和 Java 拼字符串输出很像，这里只是使用了模板。

几乎所有人都在 JSP 中用过的 EL 就是一种模板，可能你会 <c:forEach 这种，但是联想不到这里的代码生成器而已。

后续会在 https://github.com/abel533/Mybatis-Spring 项目中提供一套模板做为示例。