0
# MyBatis Spring Boot Starter
1

2
A Spring Boot Starter that provides seamless integration between MyBatis ORM and Spring Boot applications through automatic configuration and dependency management. This starter eliminates boilerplate configuration while providing extensive customization options for database access layers.
3

4
## Package Information
5

6
- **Package Name**: mybatis-spring-boot-starter
7
- **Package Type**: maven
8
- **Language**: Java
9
- **Installation**: Add to `pom.xml` dependencies:
10

11
```xml
12
<dependency>
13
    <groupId>org.mybatis.spring.boot</groupId>
14
    <artifactId>mybatis-spring-boot-starter</artifactId>
15
    <version>3.0.4</version>
16
</dependency>
17
```
18

19
## Core Imports
20

21
```java
22
import org.mybatis.spring.boot.autoconfigure.MybatisProperties;
23
import org.mybatis.spring.boot.autoconfigure.ConfigurationCustomizer;
24
import org.mybatis.spring.boot.autoconfigure.SqlSessionFactoryBeanCustomizer;
25
```
26

27
For testing support:
28

29
```java
30
import org.mybatis.spring.boot.test.autoconfigure.MybatisTest;
31
import org.mybatis.spring.boot.test.autoconfigure.AutoConfigureMybatis;
32
```
33

34
## Basic Usage
35

36
```java
37
// 1. Add starter dependency to pom.xml
38
// 2. Configure database connection in application.properties
39
spring.datasource.url=jdbc:mysql://localhost:3306/mydb
40
spring.datasource.username=user
41
spring.datasource.password=password
42

43
// Configure MyBatis settings
44
mybatis.mapper-locations=classpath:mappers/*.xml
45
mybatis.type-aliases-package=com.example.model
46
mybatis.configuration.map-underscore-to-camel-case=true
47

48
// 3. Create mapper interface with @Mapper annotation
49
@Mapper
50
public interface UserMapper {
51
    @Select("SELECT * FROM users WHERE id = #{id}")
52
    User findById(Long id);
53
    
54
    @Insert("INSERT INTO users (name, email) VALUES (#{name}, #{email})")
55
    @Options(useGeneratedKeys = true, keyProperty = "id")
56
    void insert(User user);
57
}
58

59
// 4. Use in service classes (auto-injected by Spring)
60
@Service
61
public class UserService {
62
    @Autowired
63
    private UserMapper userMapper;
64
    
65
    public User getUser(Long id) {
66
        return userMapper.findById(id);
67
    }
68
}
69
```
70

71
## Architecture
72

73
MyBatis Spring Boot Starter is built around several key components:
74

75
- **Auto-Configuration**: `MybatisAutoConfiguration` automatically configures SqlSessionFactory and SqlSessionTemplate beans based on application properties
76
- **Properties Binding**: `MybatisProperties` maps all `mybatis.*` configuration properties to MyBatis settings
77
- **Mapper Scanning**: Automatic detection and registration of interfaces annotated with `@Mapper`
78
- **Customization Points**: Interfaces like `ConfigurationCustomizer` and `SqlSessionFactoryBeanCustomizer` for advanced customization
79
- **Testing Support**: `@MybatisTest` annotation for focused integration testing of MyBatis components
80
- **Language Driver Support**: Auto-configuration for FreeMarker, Velocity, and Thymeleaf scripting engines
81

82
## Capabilities
83

84
### Configuration Properties
85

86
Core configuration system that maps Spring Boot properties to MyBatis settings, providing type-safe configuration for all MyBatis features including caching, lazy loading, type handling, and database-specific settings.
87

88
```java { .api }
89
import org.apache.ibatis.scripting.LanguageDriver;
90
import org.apache.ibatis.session.ExecutorType;
91
import org.springframework.boot.context.properties.ConfigurationProperties;
92
import org.springframework.core.io.Resource;
93
import java.util.Properties;
94

95
@ConfigurationProperties(prefix = MybatisProperties.MYBATIS_PREFIX)
96
public class MybatisProperties {
97
    public static final String MYBATIS_PREFIX = "mybatis";
98
    
99
    private String configLocation;
100
    private String[] mapperLocations;
101
    private String typeAliasesPackage;
102
    private Class<?> typeAliasesSuperType;
103
    private String typeHandlersPackage;
104
    private boolean checkConfigLocation;
105
    private ExecutorType executorType;
106
    private Class<? extends LanguageDriver> defaultScriptingLanguageDriver;
107
    private Properties configurationProperties;
108
    private CoreConfiguration configuration;
109
    
110
    // All getter and setter methods
111
    public Resource[] resolveMapperLocations();
112
}
113
```
114

115
[Configuration Properties](./configuration-properties.md)
116

117
### Customization Interfaces
118

119
Functional interfaces that provide extension points for customizing MyBatis configuration and SqlSessionFactory creation during the auto-configuration process.
120

121
```java { .api }
122
@FunctionalInterface
123
public interface ConfigurationCustomizer {
124
    void customize(Configuration configuration);
125
}
126

127
@FunctionalInterface
128
public interface SqlSessionFactoryBeanCustomizer {
129
    void customize(SqlSessionFactoryBean factoryBean);
130
}
131
```
132

133
[Customization](./customization.md)
134

135
### Auto-Configuration Classes
136

137
Spring Boot auto-configuration classes that automatically set up MyBatis components based on classpath detection and configuration properties, including support for multiple scripting language drivers.
138

139
```java { .api }
140
import org.apache.ibatis.session.SqlSessionFactory;
141
import org.mybatis.spring.SqlSessionFactoryBean;
142
import org.mybatis.spring.SqlSessionTemplate;
143
import org.springframework.beans.factory.InitializingBean;
144
import org.springframework.boot.autoconfigure.condition.ConditionalOnClass;
145
import org.springframework.boot.autoconfigure.condition.ConditionalOnMissingBean;
146
import org.springframework.boot.autoconfigure.condition.ConditionalOnSingleCandidate;
147
import org.springframework.boot.context.properties.EnableConfigurationProperties;
148
import org.springframework.context.annotation.Bean;
149
import org.springframework.context.annotation.Configuration;
150
import javax.sql.DataSource;
151

152
@Configuration(proxyBeanMethods = false)
153
@ConditionalOnClass({SqlSessionFactory.class, SqlSessionFactoryBean.class})
154
@ConditionalOnSingleCandidate(DataSource.class)
155
@EnableConfigurationProperties(MybatisProperties.class)
156
public class MybatisAutoConfiguration implements InitializingBean {
157
    
158
    public MybatisAutoConfiguration(
159
        MybatisProperties properties,
160
        ObjectProvider<Interceptor[]> interceptorsProvider,
161
        ObjectProvider<TypeHandler[]> typeHandlersProvider,
162
        ObjectProvider<LanguageDriver[]> languageDriversProvider,
163
        ResourceLoader resourceLoader,
164
        ObjectProvider<DatabaseIdProvider> databaseIdProvider,
165
        ObjectProvider<List<ConfigurationCustomizer>> configurationCustomizersProvider,
166
        ObjectProvider<List<SqlSessionFactoryBeanCustomizer>> sqlSessionFactoryBeanCustomizers
167
    );
168
    
169
    @Bean
170
    @ConditionalOnMissingBean
171
    public SqlSessionFactory sqlSessionFactory(DataSource dataSource) throws Exception;
172
    
173
    @Bean
174
    @ConditionalOnMissingBean
175
    public SqlSessionTemplate sqlSessionTemplate(SqlSessionFactory sqlSessionFactory);
176
    
177
    @Override
178
    public void afterPropertiesSet();
179
}
180
```
181

182
[Auto-Configuration](./auto-configuration.md)
183

184
### Testing Support
185

186
Testing annotations and configuration classes designed for slice testing, allowing focused testing of MyBatis components without loading the full Spring application context.
187

188
```java { .api }
189
import org.springframework.boot.test.autoconfigure.OverrideAutoConfiguration;
190
import org.springframework.boot.test.autoconfigure.filter.TypeExcludeFilters;
191
import org.springframework.boot.test.autoconfigure.jdbc.AutoConfigureTestDatabase;
192
import org.springframework.context.annotation.ComponentScan.Filter;
193
import org.springframework.core.annotation.AliasFor;
194
import org.springframework.test.context.BootstrapWith;
195
import org.springframework.test.context.junit.jupiter.SpringExtension;
196
import org.springframework.transaction.annotation.Transactional;
197
import java.lang.annotation.*;
198

199
@Target(ElementType.TYPE)
200
@Retention(RetentionPolicy.RUNTIME)
201
@Documented
202
@Inherited
203
@BootstrapWith(MybatisTestContextBootstrapper.class)
204
@ExtendWith(SpringExtension.class)
205
@OverrideAutoConfiguration(enabled = false)
206
@TypeExcludeFilters(MybatisTypeExcludeFilter.class)
207
@Transactional
208
@AutoConfigureCache
209
@AutoConfigureMybatis
210
@AutoConfigureTestDatabase
211
@ImportAutoConfiguration
212
public @interface MybatisTest {
213
    String[] properties() default {};
214
    boolean useDefaultFilters() default true;
215
    Filter[] includeFilters() default {};
216
    Filter[] excludeFilters() default {};
217
    @AliasFor(annotation = ImportAutoConfiguration.class, attribute = "exclude")
218
    Class<?>[] excludeAutoConfiguration() default {};
219
}
220
```
221

222
[Testing Support](./testing-support.md)