第一部分 简介

JMapper是基于mybatis通用Mapper的扩展实现，可以让您在使用Mybatis的时候可以像JPA那样通过方法名称定义相关的操作。

第二部分 开始使用

使用JMapper可以直接下载源代码编译或者下载已经编译的jar文件

<!-- http://mvnrepository.com/artifact/com.jianggujin/JMapper -->
<dependency>
    <groupId>com.jianggujin</groupId>
    <artifactId>JMapper</artifactId>
    <version>最新版本</version>
</dependency>

最新的版本可以从Maven仓库或者码云获取。

2.1 集成JMapper

如果您已经了解通用Mapper的用法，使用JMapper则非常容易，只需要将MapperHelper替换为JMethodExecutorMapperHelper即可。

2.1.1 Java编码方式集成

使用 Java 编码方式时，正常情况下您都会有构建 SqlSessionFactory 的代码。

在创建 SqlSessionFactory 对象前或者后对应两种配置通用 Mapper 的方法，由于没有提供mybatis-config.xml文件的解析类，这里会推荐使用 创建后 的方式来创建。

2.1.1.1 创建后

//从刚刚创建的 sqlSessionFactory 中获取 session
session = sqlSessionFactory.openSession();
//创建一个MapperHelper
JMethodExecutorMapperHelper mapperHelper = new JMethodExecutorMapperHelper();
mapperHelper.processConfiguration(session.getConfiguration());

2.1.1.2 创建前

创建前就是通过使用 tk.mybatis.mapper.session.Configuration 替换MyBatis中的 org.apache.ibatis.session.Configuration来实现。配置代码如下：

Configuration configuration = new Configuration();
//这里可以参考上面的方式来配置 MapperHelper
configuration.setMapperHelper(new JMethodExecutorMapperHelper());
sqlSessionFactory = new SqlSessionFactoryBuilder().build(configuration);

2.1.2 Spring方式集成

和Spring进行集成时，分为XML和注解配置两种方式，每种方式又有不同的配置方式。

2.1.2.1 XML配置

使用MapperScannerConfigurer

<bean class="tk.mybatis.spring.mapper.MapperScannerConfigurer">
    <property name="basePackage" value="扫描包名"/>
    <property name="mapperHelper">
        <bean class="com.jianggujin.mybatis.mapper.JMethodExecutorMapperHelper" />
    </property>
</bean>

使用 Configuration

如果某些第三方也需要特殊的 MapperScannerConfigurer 时，就不能用上面的方式进行配置了，此时可以选择下面这种方式，这种方式要求使用MyBatis (3.4.0+) 和 mybatis-spring (1.3.0+)，配置方式如下：

<!--使用 Configuration 方式进行配置-->
<bean id="mybatisConfig" class="tk.mybatis.mapper.session.Configuration">
    <property name="mapperHelper">
        <bean class="com.jianggujin.mybatis.mapper.JMethodExecutorMapperHelper" />
    </property>
</bean>

<bean id="sqlSessionFactory" class="org.mybatis.spring.SqlSessionFactoryBean">
    <property name="dataSource" ref="dataSource"/>
    <property name="configuration" ref="mybatisConfig"/>
</bean>

<!-- 不需要考虑下面这个，注意这里是 org 的 -->
<bean class="org.mybatis.spring.mapper.MapperScannerConfigurer">
    <property name="basePackage" value="tk.mybatis.mapper.configuration"/>
    <property name="sqlSessionFactoryBeanName" value="sqlSessionFactory"/>
</bean>

2.1.2.2 @MapperScan注解

如果要使用该注解进行配置，请确认选择的是 tk.mybatis.spring.annotation.MapperScan 注解（必须使用官方的注解时，看下面其他配置方式）。

tk 提供的这个注解相比官方的多了下面两个属性：

/**
 * 通用 Mapper 的配置，一行一个配置
 *
 * @return
 */
String[] properties() default {};

/**
 * 还可以直接配置一个 MapperHelper bean
 *
 * @return
 */
String mapperHelperRef() default "";

使用 mapperHelperRef 配置

@Configuration
@MapperScan(value = "tk.mybatis.mapper.annotation", mapperHelperRef = "mapperHelper")
public static class MyBatisConfigRef {
    @Bean
    public MapperHelper mapperHelper() {
        return new JMethodExecutorMapperHelper();
    }
}

使用 Configuration 配置

这里可以使用 tk 或者 MyBatis 官方的 @MapperScan 注解。

@Configuration
@MapperScan(value = "tk.mybatis.mapper.annotation")
public static class MyBatisConfigRef {

    @Bean
    public SqlSessionFactory sqlSessionFactory() throws Exception {
        SqlSessionFactoryBean sessionFactory = new SqlSessionFactoryBean();
        sessionFactory.setDataSource(dataSource());
        //tk.mybatis.mapper.session.Configuration
        Configuration configuration = new Configuration();
        //可以对 MapperHelper 进行配置后
        configuration.setMapperHelper(new JMethodExecutorMapperHelper());
        //设置为 tk 提供的 Configuration
        sessionFactory.setConfiguration(configuration);
        return sessionFactory.getObject();
    }
}

2.1.3 SpringBoot集成

使用SpringBoot方式集成需要使用 @MapperScan注解，具体配置详见2.1.2.2章节。

2.2 方法命名规则

默认情况下，JMapper不会开启方法解析，如果需要启用该功能，只需要使相关Mapper接口实现JMethodExecutorMapper<T>，这样JMapper才会处理自定义的方法，另外，为了让Mybatis扫描时正常识别接口方法，在需要解析的方法上依然需要使用Mybatis的注解，目前JMapper支持@SelectProvider和@DeleteProvider注解，对应查询和删除，注解中的type固定为：com.jianggujin.mybatis.mapper.JMethodExecutorProvider.class，method固定值为：dynamicSQL。

public interface CountryMapper extends Mapper<Country>, JMethodExecutorMapper<Country> {
    @SelectProvider(type = JMethodExecutorProvider.class, method = "sql")
    Country findById(Integer id);
}

在执行查询的方法上需要使用@SelectProvider注解，方法名格式为：[(select|find|read|get|query)[Distinct][Exclude][selectProperties]By][whereProperties][OrderBy(orderProperties)]。在执行删除的方法上需要使用@DeleteProvider注解，方法名格式为：(delete|remove)By[whereProperties]。

JMapper同样支持通用Mapper的逻辑删除

• ()：表示必选项
• []：表示可选项
• Distinct：存在该关键词将为查询语句添加DISTINCT
• Exclude：存在该关键词表示后面的查询属性为需要排除的
• selectProperties：该表达式表示需要查询的属性，不存在该部分则默认查询全部属性，属性首字母大写且属性与属性之间需要使用And分隔
• whereProperties：该表达式表示where条件需要使用的属性，分段条件之间通过Or或And拼接，Or优先级大于And，分段条件格式为:peoperty[Keyword]，属性首字母大写，需要注意的是对应方法形参数量必须与拆分后的条件参数数量一致
• orderProperties：该表达式表示Order by部分需要使用的属性，属性首字母大写，多个排序条件之间使用Asc或Desc分隔，如果该部分表达式不存在则是使用通用Mapper默认的排序配置

作为条件可用关键词：

关键词	示例	代码段
IsNotNull、 NotNull	findByIdIsNotNull、 findByIdNotNull	id is not null
IsNull、 Null	findByIdIsNull、 findByIdNull	id is null
IsNot、 Not、 NotEquals	findByIdIsNot、 findByIdNot、 findByIdNotEquals	id <> ?1
Is、 Equals	findByIdIs、 findByIdEquals	id = ?1
IsGreaterThan、 GreaterThan	findByIdIsGreaterThan、 findByIdGreaterThan	id > ?1
IsGreaterThanEqual、 GreaterThanEqual	findByIdIsGreaterThanEqual、 findByIdGreaterThanEqual	id >= ?1
IsLessThan、 LessThan	findByIdIsLessThan、 findByIdLessThan	id < ?1
IsLessThanEqual、 LessThanEqual	findByIdIsLessThanEqual、 findByIdLessThanEqual	id <= ?1
IsBefore、 Before	findByIdIsBefore、 findByIdBefore	id < ?1
IsBeforeEqual、 BeforeEqual	findByIdIsBeforeEqual、 findByIdBeforeEqual	id <= ?1
IsAfter、 After	findByIdIsAfter、 findByIdAfter	id > ?1
IsAfterEqual、 AfterEqual	findByIdIsAfterEqual、 findByIdAfterEqual	id >= ?1
IsNotIn、 NotIn	findByIdIsNotIn、 findByIdNotIn	id not in (?1)
IsIn、 In	findByIdIsIn、 findByIdIn	id in (?1)
IsBetween、 Between	findByIdIsBetween、 findByIdBetween	id between ?1 and ?2
IsNotBetween、 NotBetween	findByIdIsNotBetween、 findByIdNotBetween	id not between ?1 and ?2
IsLike、 Like	findByIdIsLike、 findByIdLike	id like ?1
IsNotLike、 NotLike	findByIdIsNotLike、 findByIdNotLike	id not like ?1

在使用方法名称解析的时候，在某些情况下可能会导致方法名称冗长，我们可以在方法上面搭配注解来缩短我们的方法名称。存在注解优先级大于方法名称解析结果且不同部分之间互不影响。