Skip to content

Commit 117dbee

Browse files
kazuki43zookazuki43zoo
authored
Merge pull request #651 from awxiaoxian2020/zh-doc
Support Chinese translations on autoconfigure reference doc
2 parents 52252a2 + 92683a8 commit 117dbee

File tree

1 file changed

+350
-0
lines changed
  • mybatis-spring-boot-autoconfigure/src/site/markdown/zh

1 file changed

+350
-0
lines changed

‎mybatis-spring-boot-autoconfigure/src/site/markdown/zh/index.md‎

Lines changed: 350 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,350 @@
1+
# 简介
2+
3+
## 什么是 MyBatis-Spring-Boot-Starter?
4+
5+
MyBatis-Spring-Boot-Starter 可以帮助你更快地在 [Spring Boot](https://spring.io/projects/spring-boot) 之上构建 MyBatis 应用。
6+
7+
你将通过使用这个模块实现以下目的：
8+
9+
* 构建单体应用程序
10+
* 将几乎不需要样板配置
11+
* 使用更少的 XML 配置
12+
13+
## 要求
14+
15+
MyBatis-Spring-Boot-Starter 要求以下版本:
16+
17+
| MyBatis-Spring-Boot-Starter | MyBatis-Spring | Spring Boot | Java |
18+
| --------------------------- | -------------------- | ------------- | --------- |
19+
| **2.3** | 2.1 | 2.5 或更高 | 8 或更高 |
20+
| **2.2** | 2.0（2.0.6 以上可开启所有特性） | 2.5 - 2.7 | 8 或更高 |
21+
| **2.1** | 2.0（2.0.6 以上可开启所有特性） | 2.1 - 2.4 | 8 或更高 |
22+
| **~~2.0 (EOL)~~** | ~~2.0~~ | ~~2.0 或 2.1~~ | ~~8 或更高~~ |
23+
| **~~1.3 (EOL)~~** | ~~1.3~~ | ~~1.5~~ | ~~6 或更高~~ |
24+
| **~~1.2 (EOL)~~** | ~~1.3~~ | ~~1.4~~ | ~~6 或更高~~ |
25+
| **~~1.1 (EOL)~~** | ~~1.3~~ | ~~1.3~~ | ~~6 或更高~~ |
26+
| **~~1.0 (EOL)~~** | ~~1.2~~ | ~~1.3~~ | ~~6 或更高~~ |
27+
28+
## 安装
29+
30+
要使用 MyBatis-Spring-Boot-Starter 模块，你只需要将 `mybatis-spring-boot-autoconfigure.jar` 文件以及它的依赖（ `mybatis.jar`, `mybatis-spring.jar` 等） 放在类路径下。
31+
32+
### Maven
33+
34+
如果你使用 Maven，只需要在你的 `pom.xml` 添加以下依赖：
35+
36+
```xml
37+
<dependency>
38+
<groupId>org.mybatis.spring.boot</groupId>
39+
<artifactId>mybatis-spring-boot-starter</artifactId>
40+
<version>${project.version}</version>
41+
</dependency>
42+
```
43+
44+
### Gradle
45+
46+
如果使用 gradle，请在你的 `build.gradle` 中加入以下内容：
47+
48+
```groovy
49+
dependencies {
50+
compile("org.mybatis.spring.boot:mybatis-spring-boot-starter:${project.version}")
51+
}
52+
```
53+
54+
## 快速开始
55+
56+
正如你已经知道的， 要与 Spring 一起使用 MyBatis，你至少需要一个 `SqlSessionFactory` 和一个 mapper 接口。
57+
58+
MyBatis-Spring-Boot-Starter 将会：
59+
60+
* 自动探测存在的 `DataSource`
61+
* 将使用 `SqlSessionFactoryBean` 创建并注册一个 `SqlSessionFactory` 的实例，并将探测到的 `DataSource` 作为数据源
62+
* 将创建并注册一个从 `SqlSessionFactory` 中得到的 `SqlSessionTemplate` 的实例。
63+
* 自动扫描你的 mapper，将它们与 `SqlSessionTemplate` 相关联，并将它们注册到Spring 的环境（context）中去，这样它们就可以被注入到你的 bean 中
64+
65+
假设我们有下面的 mapper ：
66+
67+
```java
68+
@Mapper
69+
public interface CityMapper {
70+
71+
@Select("SELECT * FROM CITY WHERE state = #{state}")
72+
City findByState(@Param("state") String state);
73+
74+
}
75+
```
76+
77+
你只需要创建一个 Spring boot 应用，像下面这样，将 mapper 注入进去（ Spring 4.3 以上可用）。
78+
79+
```java
80+
@SpringBootApplication
81+
public class SampleMybatisApplication implements CommandLineRunner {
82+
83+
private final CityMapper cityMapper;
84+
85+
public SampleMybatisApplication(CityMapper cityMapper) {
86+
this.cityMapper = cityMapper;
87+
}
88+
89+
public static void main(String[] args) {
90+
SpringApplication.run(SampleMybatisApplication.class, args);
91+
}
92+
93+
@Override
94+
public void run(String... args) throws Exception {
95+
System.out.println(this.cityMapper.findByState("CA"));
96+
}
97+
98+
}
99+
```
100+
101+
这就是你需要做的所有事情了。 你的 Spring boot 应用可以正常运行了。
102+
103+
## “扫描”的进阶用法
104+
105+
MyBatis-Spring-Boot-Starter 将默认搜寻带有 `@Mapper` 注解的 mapper 接口。
106+
107+
你可能想指定一个自定义的注解或接口来扫描，如果那样的话，你就必须使用 `@MapperScan` 注解了。在 [MyBatis-Spring 参考页面](http://www.mybatis.org/spring/mappers.html#scan) 中查看更多信息。
108+
109+
如果 MyBatis-Spring-Boot-Starter 发现至少有一个 `SqlSessionFactoryBean` ，它将不会开始扫描。 所以如果你想停止扫描，你应该用 `@Bean` 方法明确注册你的 mapper。
110+
111+
## 使用 SqlSession
112+
113+
一个 `SqlSessionTemplate` 的实例被创建并添加到 Spring 的环境中，因此你可以使用 MyBatis API，让它像下面一样被注入到你的 bean 中（Spring 4.3 以上可用）。
114+
115+
```java
116+
@Component
117+
public class CityDao {
118+
119+
private final SqlSession sqlSession;
120+
121+
public CityDao(SqlSession sqlSession) {
122+
this.sqlSession = sqlSession;
123+
}
124+
125+
public City selectCityById(long id) {
126+
return this.sqlSession.selectOne("selectCityById", id);
127+
}
128+
129+
}
130+
```
131+
132+
## 配置
133+
134+
像其他的 Spring Boot 应用一样，配置参数在 `application.properties` （或 `application.yml` )。
135+
136+
MyBatis 在它的配置项中，使用 `mybatis` 作为前缀。
137+
138+
可用的配置项如下：
139+
140+
| 配置项（properties） | 描述 |
141+
|:---------------------------------------- |:------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
142+
| `config-location` | MyBatis XML 配置文件的路径。 |
143+
| `check-config-location` | 指定是否对 MyBatis XML 配置文件的存在进行检查。 |
144+
| `mapper-locations` | XML 映射文件的路径。 |
145+
| `type-aliases-package` | 搜索类型别名的包名。（包使用的分隔符是 "`,; \t\n`"） |
146+
| `type-aliases-super-type` | 用于过滤类型别名的父类。如果没有指定，MyBatis会将所有从 `type-aliases-package` 搜索到的类作为类型别名处理。 |
147+
| `type-handlers-package` | 搜索类型处理器的包名。（包使用的分隔符是 "`,; \t\n`"） |
148+
| `executor-type` | SQL 执行器类型： `SIMPLE`, `REUSE`, `BATCH` |
149+
| `default-scripting-language-driver` | 默认的脚本语言驱动（模板引擎），此功能需要与 mybatis-spring 2.0.2 以上版本一起使用。 |
150+
| `configuration-properties` | 可在外部配置的 MyBatis 配置项。指定的配置项可以被用作 MyBatis 配置文件和 Mapper 文件的占位符。更多细节 见 [MyBatis 参考页面](https://mybatis.org/mybatis-3/zh/configuration.html#properties)。 |
151+
| `lazy-initialization` | 是否启用 mapper bean 的延迟初始化。设置 `true` 以启用延迟初始化。此功能需要与 mybatis-spring 2.0.2 以上版本一起使用。 |
152+
| `mapper-default-scope` | 通过自动配置扫描的 mapper 组件的默认作用域。该功能需要与 mybatis-spring 2.0.6 以上版本一起使用。 |
153+
| `inject-sql-session-on-mapper-scan` | 设置是否注入 `SqlSessionTemplate` 或  `SqlSessionFactory` 组件 （如果你想回到 2.2.1 或之前的行为，请指定 `false` ）。如果你和 spring-native 一起使用，应该设置为 `true` （默认）。 |
154+
| `configuration.*` | MyBatis Core 提供的`Configuration` 组件的配置项。有关可用的内部配置项，请参阅[MyBatis 参考页面](http://www.mybatis.org/mybatis-3/zh/configuration.html#settings)。注：此属性不能与 `config-location` 同时使用。 |
155+
| `scripting-language-driver.thymeleaf.*` | MyBatis `ThymeleafLanguageDriverConfig` 组件的 properties keys。有关可用的内部配置项，请参阅 [MyBatis Thymeleaf 参考页面](http://www.mybatis.org/thymeleaf-scripting/user-guide.html#_configuration_properties)。 |
156+
| `scripting-language-driver.freemarker.*` | MyBatis `FreemarkerLanguageDriverConfig` 组件的 properties keys。有关可用的内部配置项，请参阅 [MyBatis FreeMarker 参考页面](http://www.mybatis.org/freemarker-scripting/#Configuration)。这个特性需要与 mybatis-freemarker 1.2.0 以上版本一起使用。 |
157+
| `scripting-language-driver.velocity.*` | MyBatis `VelocityLanguageDriverConfig` 组件的  properties keys。有关可用的内部属性，请参阅 [MyBatis Velocity 参考页面](http://www.mybatis.org/velocity-scripting/#Configuration)。这个特性需要与 mybatis-velocity 2.1.0 以上版本一起使用。 |
158+
159+
例如：
160+
161+
```properties
162+
# application.properties
163+
mybatis.type-aliases-package=com.example.domain.model
164+
mybatis.type-handlers-package=com.example.typehandler
165+
mybatis.configuration.map-underscore-to-camel-case=true
166+
mybatis.configuration.default-fetch-size=100
167+
mybatis.configuration.default-statement-timeout=30
168+
...
169+
```
170+
171+
```yaml
172+
# application.yml
173+
mybatis:
174+
type-aliases-package: com.example.domain.model
175+
type-handlers-package: com.example.typehandler
176+
configuration:
177+
map-underscore-to-camel-case: true
178+
default-fetch-size: 100
179+
default-statement-timeout: 30
180+
...
181+
```
182+
183+
## 使用 ConfigurationCustomizer
184+
185+
MyBatis-Spring-Boot-Starter 提供了使用 Java Config 来自定义 MyBatis 配置的可能。
186+
187+
MyBatis-Spring-Boot-Starter 将自动寻找实现了 `ConfigurationCustomizer` 接口的组件，调用自定义 MyBatis 配置的方法。( 1.2.1 及以上的版本可用）
188+
189+
例如：
190+
191+
```java
192+
@Configuration
193+
public class MyBatisConfig {
194+
@Bean
195+
ConfigurationCustomizer mybatisConfigurationCustomizer() {
196+
return new ConfigurationCustomizer() {
197+
@Override
198+
public void customize(Configuration configuration) {
199+
// customize ...
200+
}
201+
};
202+
}
203+
}
204+
```
205+
206+
## 使用 SqlSessionFactoryBeanCustomizer
207+
208+
MyBatis-Spring-Boot-Starter 提供了使用 Java Config 来自定义自动配置生成的 `SqlSessionFactoryBean` 。
209+
210+
MyBatis-Spring-Boot-Starter 将自动寻找实现了 `SqlSessionFactoryBeanCustomizer` 接口的组件，调用自定义 `SqlSessionFactoryBean` 的方法。( 2.2.2 及以上的版本可用）
211+
212+
For example:
213+
214+
```java
215+
@Configuration
216+
public class MyBatisConfig {
217+
@Bean
218+
SqlSessionFactoryBeanCustomizer sqlSessionFactoryBeanCustomizer() {
219+
return new SqlSessionFactoryBeanCustomizer() {
220+
@Override
221+
public void customize(SqlSessionFactoryBean factoryBean) {
222+
// customize ...
223+
}
224+
};
225+
}
226+
}
227+
```
228+
229+
## 使用 SpringBootVFS
230+
231+
MyBatis-Spring-Boot-Starter 提供了 `SpringBootVFS` 作为 `VFS` 的实现类。
232+
`VFS` 用于从应用或应用服务器中寻找类 （例如： 类型别名的目标类，类型处理器类） 。
233+
如果你使用可执行的 jar 文件来运行 Spring boot 应用，你需要使用 `SpringBootVFS` 。
234+
由于拥有自动配置的特性，MyBatis-Spring-Boot-Starter 会自动启用它。
235+
但在你手动配置（MyBatis-Spring-Boot-Starter）的时候 (例如： 当你使用多个 `DataSource` 的时候）。
236+
237+
在手动配置（MyBatis-Spring-Boot-Starter）的时候，这样使用 `SpringBootVFS` ：
238+
239+
```java
240+
@Configuration
241+
public class MyBatisConfig {
242+
@Bean
243+
public SqlSessionFactory masterSqlSessionFactory() throws Exception {
244+
SqlSessionFactoryBean factoryBean = new SqlSessionFactoryBean();
245+
factoryBean.setDataSource(masterDataSource());
246+
factoryBean.setVfs(SpringBootVFS.class); // Sets the SpringBootVFS class into SqlSessionFactoryBean
247+
// ...
248+
return factoryBean.getObject();
249+
}
250+
}
251+
```
252+
253+
## 探测 MyBatis 组件
254+
255+
The MyBatis-Spring-Boot-Starter 将检测实现以下由 MyBatis 提供的接口的组件。
256+
257+
* [`Interceptor`](http://www.mybatis.org/mybatis-3/zh/configuration.html#plugins) (拦截器)
258+
* [`TypeHandler`](http://www.mybatis.org/mybatis-3/zh/configuration.html#typeHandlers) (类型处理器)
259+
* [`LanguageDriver`](http://www.mybatis.org/mybatis-3/zh/dynamic-sql.html#Pluggable_Scripting_Languages_For_Dynamic_SQL) （插入脚本语言）(需要 mybatis-spring 2.0.2 以上配合使用)
260+
* [`DatabaseIdProvider`](http://www.mybatis.org/mybatis-3/zh/configuration.html#databaseIdProvider)
261+
262+
```java
263+
@Configuration
264+
public class MyBatisConfig {
265+
@Bean
266+
MyInterceptor myInterceptor() {
267+
return MyInterceptor();
268+
}
269+
@Bean
270+
MyTypeHandler myTypeHandler() {
271+
return MyTypeHandler();
272+
}
273+
@Bean
274+
MyLanguageDriver myLanguageDriver() {
275+
return MyLanguageDriver();
276+
}
277+
@Bean
278+
VendorDatabaseIdProvider databaseIdProvider() {
279+
VendorDatabaseIdProvider databaseIdProvider = new VendorDatabaseIdProvider();
280+
Properties properties = new Properties();
281+
properties.put("SQL Server", "sqlserver");
282+
properties.put("DB2", "db2");
283+
properties.put("H2", "h2");
284+
databaseIdProvider.setProperties(properties);
285+
return databaseIdProvider;
286+
}
287+
}
288+
```
289+
290+
<span class="label important">注意</span>: 如果只有一个 `LangaugeDriver` ，它将自动地将其作为默认的脚本语言。
291+
292+
如果你想自定义 `LangaugeDriver` 的配置，请注册用户定义的组件。
293+
294+
### ThymeleafLanguageDriver
295+
296+
```java
297+
@Configuration
298+
public class MyBatisConfig {
299+
@Bean
300+
ThymeleafLanguageDriverConfig thymeleafLanguageDriverConfig() {
301+
return ThymeleafLanguageDriverConfig.newInstance(c -> {
302+
// ... 自定义代码
303+
});
304+
}
305+
}
306+
```
307+
308+
### FreeMarkerLanguageDriverConfig
309+
310+
```java
311+
@Configuration
312+
public class MyBatisConfig {
313+
@Bean
314+
FreeMarkerLanguageDriverConfig freeMarkerLanguageDriverConfig() {
315+
return FreeMarkerLanguageDriverConfig.newInstance(c -> {
316+
// ... 自定义代码
317+
});
318+
}
319+
}
320+
```
321+
322+
### VelocityLanguageDriver
323+
324+
```java
325+
@Configuration
326+
public class MyBatisConfig {
327+
@Bean
328+
VelocityLanguageDriverConfig velocityLanguageDriverConfig() {
329+
return VelocityLanguageDriverConfig.newInstance(c -> {
330+
// ... customization code
331+
});
332+
}
333+
}
334+
```
335+
336+
### 可以运行的样例
337+
338+
项目（为每个分类）提供了至少两个样例，可以为你所用。
339+
340+
| 分类 | 样例 | 描述 |
341+
|:-------------- |:----------------------------------------------------------------------------------------------------------------------------------- |:--------------------------------------------------------------------- |
342+
| 核心组件 | [样例1](https://github.com/mybatis/spring-boot-starter/tree/master/mybatis-spring-boot-samples/mybatis-spring-boot-sample-annotation) | 展示了最简单的场景，只有一个 mapper 和一个注入 mapper 的组件。这就是我们在“快速入门”部分看到的例子。 |
343+
| | [样例2](https://github.com/mybatis/spring-boot-starter/tree/master/mybatis-spring-boot-samples/mybatis-spring-boot-sample-xml) | 展示了如何在 XML 文件中使用一个带有语句的 Mapper，并且也有使用 `SqlSessionTemplate` 的 DAO 的示例。 |
344+
| LangaugeDriver | [样例3](https://github.com/mybatis/spring-boot-starter/tree/master/mybatis-spring-boot-samples/mybatis-spring-boot-sample-thymeleaf) | 展示了如何在 mybatis-thymeleaf 的帮助下，使用 Thymeleaf。 |
345+
| | [样例4](https://github.com/mybatis/spring-boot-starter/tree/master/mybatis-spring-boot-samples/mybatis-spring-boot-sample-freemarker) | 展示了如何在 mybatis-freemarker 的帮助下，使用 Freemarker。 |
346+
| | [样例5](https://github.com/mybatis/spring-boot-starter/tree/master/mybatis-spring-boot-samples/mybatis-spring-boot-sample-velocity) | 展示了如何在 mybatis-velocity 的帮助下，使用 Velocity。 |
347+
| JVM 语言 | [样例6](https://github.com/mybatis/spring-boot-starter/tree/master/mybatis-spring-boot-samples/mybatis-spring-boot-sample-kotlin) | 展示了如何和 kotlin 一同使用。 |
348+
| | [样例7](https://github.com/mybatis/spring-boot-starter/tree/master/mybatis-spring-boot-samples/mybatis-spring-boot-sample-groovy) | 展示了如何和 groovy 一同使用。 |
349+
| Web | [样例8](https://github.com/mybatis/spring-boot-starter/tree/master/mybatis-spring-boot-samples/mybatis-spring-boot-sample-web) | 展示了如何在 web 环境中使用。 |
350+
| | [样例9](https://github.com/mybatis/spring-boot-starter/tree/master/mybatis-spring-boot-samples/mybatis-spring-boot-sample-war) | 展示了如何在 web 环境中使用并且让 war 文件部署在应用程序服务器上。 |

0 commit comments

Comments
 (0)