SpringBoot2.x入門：使用MyBatis

2020 年 7 月 19 日
筆記
springboot

這是公眾號《Throwable文摘》發布的第25篇原創文章，收錄於專輯《SpringBoot2.x入門》。

前提

這篇文章是《SpringBoot2.x入門》專輯的第8篇文章，使用的SpringBoot版本為2.3.1.RELEASE，JDK版本為1.8。

SpringBoot項目引入MyBatis一般的套路是直接引入mybatis-spring-boot-starter或者使用基於MyBatis進行二次封裝的框架例如MyBatis-Plus或者tk.mapper等，但是本文會使用一種更加原始的方式，單純依賴org.mybatis:mybatis和org.mybatis:mybatis-spring把MyBatis的功能整合到SpringBoot中，Spring(Boot)使用的是微內核架構，任何第三方框架或者插件都可以按照本文的思路融合到該微內核中。

引入MyBatis依賴

編寫本文的時候（2020-07-18）org.mybatis:mybatis的最新版本是3.5.5，而org.mybatis:mybatis-spring的最新版本是2.0.5，在使用BOM管理SpringBoot版本的前提下，引入下面的依賴：

<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-web</artifactId>
</dependency>
<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-jdbc</artifactId>
</dependency>
<dependency>
    <groupId>org.mybatis</groupId>
    <artifactId>mybatis</artifactId>
    <version>3.5.5</version>
</dependency>
<dependency>
    <groupId>org.mybatis</groupId>
    <artifactId>mybatis-spring</artifactId>
    <version>2.0.5</version>
</dependency>

注意的是低版本的MyBatis如果需要使用JDK8的日期時間API，需要額外引入mybatis-typehandlers-jsr310依賴，但是某個版本之後mybatis-typehandlers-jsr310中的類已經移植到org.mybatis:mybatis中作為內建類，可以放心使用JDK8的日期時間API。

添加MyBatis配置

MyBatis的核心模組是SqlSessionFactory與MapperScannerConfigurer。前者可以使用SqlSessionFactoryBean，功能是為每個SQL的執行提供SqlSession和載入全局配置或者SQL實現的XML文件，後者是一個BeanDefinitionRegistryPostProcessor實現，主要功能是主動通過配置的基礎包（Base Package）中遞歸搜索Mapper介面（這個算是MyBatis獨有的掃描階段，務必指定明確的掃描包，否則會因為效率太低導致啟動階段耗時增加），並且把它們註冊成MapperFactoryBean（簡單理解為介面動態代理實現添加到方法快取中，並且委託到IOC容器，此後可以直接注入Mapper介面），注意這個BeanFactoryPostProcessor的回調優先順序極高，在自動裝配@Autowired族註解或者@ConfigurationProperties屬性綁定處理之前已經回調，因此在處理MapperScannerConfigurer的屬性配置時候絕對不能使用@Value或者自定義前綴屬性Bean進行自動裝配，但是可以從Environment中直接獲取。

這裡添加一個自定義屬性前綴mybatis，用於綁定配置文件中的屬性到MyBatisProperties類中：

@ConfigurationProperties(prefix = "mybatis")
@Data
public class MyBatisProperties {

    private String configLocation;
    private String mapperLocations;
    private String mapperPackages;

    private static final ResourcePatternResolver RESOLVER = new PathMatchingResourcePatternResolver();

    /**
     * 轉化Mapper映射文件為Resource
     */
    public Resource[] getMapperResourceArray() {
        if (!StringUtils.hasLength(mapperLocations)) {
            return new Resource[0];
        }
        List<Resource> resources = new ArrayList<>();
        String[] locations = StringUtils.commaDelimitedListToStringArray(mapperLocations);
        for (String location : locations) {
            try {
                resources.addAll(Arrays.asList(RESOLVER.getResources(location)));
            } catch (IOException e) {
                throw new IllegalArgumentException(e);
            }
        }
        return resources.toArray(new Resource[0]);
    }
}

接著添加一個MybatisAutoConfiguration用於配置SqlSessionFactory：

@Configuration
@EnableConfigurationProperties(value = {MyBatisProperties.class})
@ConditionalOnClass({SqlSessionFactory.class, SqlSessionFactoryBean.class})
@RequiredArgsConstructor
public class MybatisAutoConfiguration {

    private final MyBatisProperties myBatisProperties;

    @Bean
    public SqlSessionFactoryBean sqlSessionFactoryBean(DataSource dataSource) {
        SqlSessionFactoryBean bean = new SqlSessionFactoryBean();
        bean.setDataSource(dataSource);
        // 其實核心配置就是這兩項,其他TypeHandlersPackage、TypeAliasesPackage等等自行斟酌是否需要添加
        bean.setConfigLocation(new ClassPathResource(myBatisProperties.getConfigLocation()));
        bean.setMapperLocations(myBatisProperties.getMapperResourceArray());
        return bean;
    }

    /**
     * 事務模板,用於編程式事務 - 可選配置
     */
    @Bean
    @ConditionalOnMissingBean
    public TransactionTemplate transactionTemplate(PlatformTransactionManager platformTransactionManager) {
        return new TransactionTemplate(platformTransactionManager);
    }

    /**
     * 數據源事務管理器 - 可選配置
     */
    @Bean
    @ConditionalOnMissingBean
    public PlatformTransactionManager platformTransactionManager(DataSource dataSource) {
        return new DataSourceTransactionManager(dataSource);
    }
}

一般情況下，啟用事務需要定義PlatformTransactionManager的實現，而TransactionTemplate適用於編程式事務（和聲明式事務@Transactional區別，編程式更加靈活）。上面的配置類中只使用了兩個屬性，而mybatis.mapperPackages將用於MapperScannerConfigurer的載入上。添加MapperScannerRegistrarConfiguration如下：

@Configuration
public class MapperScannerRegistrarConfiguration {

    public static class AutoConfiguredMapperScannerRegistrar implements
            BeanFactoryAware, EnvironmentAware, ImportBeanDefinitionRegistrar {

        private Environment environment;
        private BeanFactory beanFactory;


        @Override
        public void setBeanFactory(@NonNull BeanFactory beanFactory) throws BeansException {
            this.beanFactory = beanFactory;
        }

        @Override
        public void setEnvironment(@NonNull Environment environment) {
            this.environment = environment;
        }

        @Override
        public void registerBeanDefinitions(@NonNull AnnotationMetadata importingClassMetadata,
                                            @NonNull BeanDefinitionRegistry registry) {
            BeanDefinitionBuilder builder = BeanDefinitionBuilder.genericBeanDefinition(MapperScannerConfigurer.class);
            builder.addPropertyValue("processPropertyPlaceHolders", true);
            StringJoiner joiner = new StringJoiner(ConfigurableApplicationContext.CONFIG_LOCATION_DELIMITERS);
            // 這裡使用了${mybatis.mapperPackages},否則會使用AutoConfigurationPackages.get(this.beanFactory)獲取項目中自定義配置的包
            String mapperPackages = environment.getProperty("mybatis.mapperPackages");
            if (null != mapperPackages) {
                String[] stringArray = StringUtils.commaDelimitedListToStringArray(mapperPackages);
                for (String pkg : stringArray) {
                    joiner.add(pkg);
                }
            } else {
                List<String> packages = AutoConfigurationPackages.get(this.beanFactory);
                for (String pkg : packages) {
                    joiner.add(pkg);
                }
            }
            builder.addPropertyValue("basePackage", joiner.toString());
            BeanWrapper beanWrapper = new BeanWrapperImpl(MapperScannerConfigurer.class);
            Stream.of(beanWrapper.getPropertyDescriptors())
                    .filter(x -> "lazyInitialization".equals(x.getName())).findAny()
                    .ifPresent(x -> builder.addPropertyValue("lazyInitialization",
                            "${mybatis.lazyInitialization:false}"));
            registry.registerBeanDefinition(MapperScannerConfigurer.class.getName(), builder.getBeanDefinition());
        }
    }

    @Configuration
    @Import(AutoConfiguredMapperScannerRegistrar.class)
    @ConditionalOnMissingBean({MapperFactoryBean.class, MapperScannerConfigurer.class})
    public static class MapperScannerRegistrarNotFoundConfiguration {

    }
}

到此基本的配置Bean已經定義完畢，接著需要添加配置項。一般一個項目的MyBatis配置是相對固定的，可以直接添加在主配置文件application.properties中：

server.port=9098
spring.application.name=ch8-mybatis
mybatis.configLocation=mybatis-config.xml
mybatis.mapperLocations=classpath:mappings/base,classpath:mappings/ext
mybatis.mapperPackages=club.throwable.ch8.repository.mapper,club.throwable.ch8.repository

個人喜歡在resource/mappings目錄下定義base和ext兩個目錄，base目錄用於存在MyBatis生成器生成的XML文件，這樣就能在後續添加了表欄位之後直接重新生成和覆蓋base目錄下對應的XML文件即可。同理，在項目的源碼包下建repository/mapper，然後Mapper類直接存放在repository/mapper目錄，DAO類存放在repository目錄，MyBatis生成器生成的Mapper類可以直接覆蓋repository/mapper目錄中對應的類。

resources目錄下添加一個MyBatis的全局配置文件mybatis-config.xml：

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE configuration PUBLIC "-//mybatis.org//DTD Config 3.0//EN" "//mybatis.org/dtd/mybatis-3-config.dtd">
<configuration>
    <settings>
        <!--下劃線轉駝峰-->
        <setting name="mapUnderscoreToCamelCase" value="true"/>
        <!--未知列映射忽略-->
        <setting name="autoMappingUnknownColumnBehavior" value="NONE"/>
    </settings>
</configuration>

項目目前的基本結構如下：

使用Mybatis

為了簡單起見，這裡使用h2記憶體資料庫進行演示。添加h2的依賴：

<dependency>
    <groupId>com.h2database</groupId>
    <artifactId>h2</artifactId>
    <version>1.4.200</version>
</dependency>

resources目錄下添加一個schema.sql和data.sql：

// resources/schema.sql
drop table if exists customer;

create table customer
(
    id            bigint generated by default as identity,
    customer_name varchar(32),
    age           int,
    create_time   timestamp default current_timestamp,
    edit_time     timestamp default current_timestamp,
    primary key (id)
);

// resources/data.sql
INSERT INTO customer(customer_name,age) VALUES ('doge', 22);
INSERT INTO customer(customer_name,age) VALUES ('throwable', 23);

添加對應的實體類club.throwable.ch8.entity.Customer：

@Data
public class Customer {

    private Long id;
    private String customerName;
    private Integer age;
    private LocalDateTime createTime;
    private LocalDateTime editTime;
}

添加Mapper和DAO類：

// club.throwable.ch8.repository.mapper.CustomerMapper
public interface CustomerMapper {

}

// club.throwable.ch8.repository.CustomerDao
public interface CustomerDao extends CustomerMapper {

    Customer queryByName(@Param("customerName") String customerName);
}

添加XML文件resource/mappings/base/BaseCustomerMapper.xml和resource/mappings/base/ExtCustomerMapper.xml：

// BaseCustomerMapper.xml

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE mapper PUBLIC "-//mybatis.org//DTD Mapper 3.0//EN" "//mybatis.org/dtd/mybatis-3-mapper.dtd">
<mapper namespace="club.throwable.ch8.repository.mapper.CustomerMapper">

    <resultMap id="BaseResultMap" type="club.throwable.ch8.entity.Customer">
        <id column="id" jdbcType="BIGINT" property="id"/>
        <result column="customer_name" jdbcType="VARCHAR" property="customerName"/>
        <result column="age" jdbcType="INTEGER" property="age"/>
        <result column="create_time" jdbcType="TIMESTAMP" property="createTime"/>
        <result column="edit_time" jdbcType="TIMESTAMP" property="editTime"/>
    </resultMap>

</mapper>

// ExtCustomerMapper.xml
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE mapper PUBLIC "-//mybatis.org//DTD Mapper 3.0//EN" "//mybatis.org/dtd/mybatis-3-mapper.dtd">
<mapper namespace="club.throwable.ch8.repository.CustomerDao">

    <resultMap id="BaseResultMap" type="club.throwable.ch8.entity.Customer"
               extends="club.throwable.ch8.repository.mapper.CustomerMapper.BaseResultMap">
    </resultMap>

    <select id="queryByName" resultMap="BaseResultMap">
        SELECT *
        FROM customer
        WHERE customer_name = #{customerName}
    </select>

</mapper>

細心的夥伴會發現，DAO和Mapper類是繼承關係，而ext和base下對應的Mapper文件中的BaseResultMap也是繼承關係

配置文件中增加h2數據源的配置：

// application.properties
spring.datasource.url=jdbc:h2:mem:db_customer;MODE=MYSQL;DB_CLOSE_DELAY=-1;DATABASE_TO_UPPER=FALSE
spring.datasource.username=root
spring.datasource.password=123456
spring.datasource.driver-class-name=org.h2.Driver
spring.h2.console.enabled=true
spring.h2.console.path=/h2-console
spring.h2.console.settings.web-allow-others=true
spring.datasource.schema=classpath:schema.sql
spring.datasource.data=classpath:data.sql

添加一個啟動類進行驗證：

public class Ch8Application implements CommandLineRunner {

    @Autowired
    private CustomerDao customerDao;

    @Autowired
    private ObjectMapper objectMapper;

    public static void main(String[] args) {
        SpringApplication.run(Ch8Application.class, args);
    }

    @Override
    public void run(String... args) throws Exception {
        Customer customer = customerDao.queryByName("doge");
        log.info("Query [name=doge],result:{}", objectMapper.writeValueAsString(customer));
        customer = customerDao.queryByName("throwable");
        log.info("Query [name=throwable],result:{}", objectMapper.writeValueAsString(customer));
    }
}

執行結果如下：

使用Mybatis生成器生成Mapper文件

有些時候為了提高開發效率，更傾向於使用生成器去預生成一些已經具備簡單CRUD方法的Mapper文件，這個時候可以使用mybatis-generator-core。編寫本文的時候（2020-07-18）mybatis-generator-core的最新版本為1.4.0，mybatis-generator-core可以通過編程式使用或者Maven插件形式使用。

這裡僅僅簡單演示一下Maven插件形式下使用mybatis-generator-core的方式，關於mybatis-generator-core後面會有一篇數萬字的文章詳細介紹此生成器的使用方式和配置項的細節。在項目的resources目錄下添加一個generatorConfig.xml：

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE generatorConfiguration
        PUBLIC "-//mybatis.org//DTD MyBatis Generator Configuration 1.0//EN"
        "//mybatis.org/dtd/mybatis-generator-config_1_0.dtd">
<generatorConfiguration>
    <context id="H2Tables" targetRuntime="MyBatis3">
        <property name="autoDelimitKeywords" value="true"/>
        <property name="javaFileEncoding" value="UTF-8"/>
        <property name="beginningDelimiter" value="`"/>
        <property name="endingDelimiter" value="`"/>

        <commentGenerator>
            <property name="suppressDate" value="true"/>
            <!-- 是否去除自動生成的注釋 true：是 ： false:否 -->
            <property name="suppressAllComments" value="true"/>
            <property name="suppressDate" value="true"/>
        </commentGenerator>

        <jdbcConnection driverClass="org.h2.Driver"
                        connectionURL="jdbc:h2:mem:db_customer;MODE=MYSQL;DB_CLOSE_DELAY=-1;DATABASE_TO_UPPER=FALSE"
                        userId="root"
                        password="123456"/>

        <javaTypeResolver>
            <property name="forceBigDecimals" value="false"/>
        </javaTypeResolver>

        <!-- 生成模型的包名和位置(實體類)-->
        <javaModelGenerator targetPackage="club.throwable.ch8.entity"
                            targetProject="src/main/java">
            <property name="enableSubPackages" value="true"/>
            <property name="trimStrings" value="false"/>

        </javaModelGenerator>

        <!-- 生成映射XML文件的包名和位置-->
        <sqlMapGenerator targetPackage="mappings.base"
                         targetProject="src/main/resources">
            <property name="enableSubPackages" value="true"/>
        </sqlMapGenerator>

        <!-- 生成DAO的包名和位置-->
        <javaClientGenerator type="XMLMAPPER"
                             targetPackage="club.throwable.ch8.repository.mapper"
                             targetProject="src/main/java">
            <property name="enableSubPackages" value="true"/>
        </javaClientGenerator>

        <table tableName="customer"
               enableCountByExample="false"
               enableUpdateByExample="false"
               enableDeleteByExample="false"
               enableSelectByExample="false">
        </table>

    </context>
</generatorConfiguration>

然後再項目的POM文件添加一個Maven插件：

<plugins>
    <plugin>
        <groupId>org.mybatis.generator</groupId>
        <artifactId>mybatis-generator-maven-plugin</artifactId>
        <version>1.4.0</version>
        <executions>
            <execution>
                <id>Generate MyBatis Artifacts</id>
                <goals>
                    <goal>generate</goal>
                </goals>
            </execution>
        </executions>
        <configuration>
            <jdbcURL>jdbc:h2:mem:db_customer;MODE=MYSQL;DB_CLOSE_DELAY=-1;DATABASE_TO_UPPER=FALSE</jdbcURL>
            <jdbcDriver>org.h2.Driver</jdbcDriver>
            <jdbcUserId>root</jdbcUserId>
            <jdbcPassword>123456</jdbcPassword>
            <sqlScript>${basedir}/src/main/resources/schema.sql</sqlScript>
        </configuration>
        <dependencies>
            <dependency>
                <groupId>com.h2database</groupId>
                <artifactId>h2</artifactId>
                <version>1.4.200</version>
            </dependency>
        </dependencies>
    </plugin>
</plugins>

筆者發現這裡必須要在插件的配置中重新定義資料庫連接屬性和schema.sql，因為插件跑的時候無法使用項目中已經啟動的h2實例，具體原因未知。

配置完畢之後，執行Maven命令：

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

然後resource/mappings/base目錄下新增了一個帶有基本CRUD方法實現的CustomerMapper.xml，同時CustoemrMapper介面和Customer實體也被重新覆蓋生成了。

這裡把前面手動編寫的BaseCustomerMapper.xml注釋掉，預防衝突。另外，CustomerMapper.xml的insertSelective標籤需要加上keyColumn=”id” keyProperty=”id” useGeneratedKeys=”true”屬性，用於實體insert後的主鍵回寫。

最後，修改並重啟啟動一下Ch8Application驗證結果：

小結

這篇文章相對詳細地介紹了SpringBoot項目如何使用MyBatis，如果需要連接MySQL或者其他資料庫，只需要修改數據源配置和MyBatis生成器的配置文件即可，其他配置類和項目骨架可以直接復用。

本文demo倉庫：

Github：//github.com/zjcscut/spring-boot-guide/tree/master/ch8-mybatis

（本文完 c-2-d e-a-20200719 封面來自《秒速五厘米》）

公眾號《Throwable文摘》（id：throwable-doge），不定期推送架構設計、並發、源碼探究相關的原創文章：

Tags: springboot