settings 全局设置
settings 是 MyBatis 中最复杂的配置之一，用于调整框架的运行时行为。了解每个参数的作用，可以在性能和功能之间做出合适的选择。
settings 基本结构
XML
<configuration>
<settings>
<setting name="cacheEnabled" value="true"/>
<setting name="lazyLoadingEnabled" value="true"/>
<!-- 更多设置 -->
</settings>
</configuration>
注意：
settings元素必须出现在configuration中properties之后、typeAliases之前。
缓存相关设置
cacheEnabled
| 参数 | 默认值 | 说明 |
|---|---|---|
| cacheEnabled | true | 全局开启或关闭所有映射器中配置的二级缓存 |
XML
<setting name="cacheEnabled" value="true"/>
关闭二级缓存：
XML
<setting name="cacheEnabled" value="false"/>
注意：此设置仅影响二级缓存（Mapper 级别），一级缓存（SqlSession 级别）始终开启。关闭二级缓存适用于对数据实时性要求极高的场景。
localCacheScope
| 参数 | 默认值 | 说明 |
|---|---|---|
| localCacheScope | SESSION | 一级缓存作用域，可选 SESSION/STATEMENT |
XML
<!-- 默认：同一 SqlSession 内共享一级缓存 -->
<setting name="localCacheScope" value="SESSION"/>
<!-- 每次 SQL 执行后清空一级缓存 -->
<setting name="localCacheScope" value="STATEMENT"/>
| 值 | 说明 | 适用场景 |
|---|---|---|
| SESSION | 同一 SqlSession 内的查询共享缓存 | 默认值，适合大多数场景 |
| STATEMENT | 每次 SQL 执行后清空缓存 | 需要实时读取外部数据变更的场景 |
懒加载相关设置
lazyLoadingEnabled
| 参数 | 默认值 | 说明 |
|---|---|---|
| lazyLoadingEnabled | false | 全局开启或关闭延迟加载 |
XML
<setting name="lazyLoadingEnabled" value="true"/>
aggressiveLazyLoading
| 参数 | 默认值 | 说明 |
|---|---|---|
| aggressiveLazyLoading | false | agresive 懒加载开关 |
XML
<!-- 关闭：只有在调用懒加载属性的方法时才加载 -->
<setting name="aggressiveLazyLoading" value="false"/>
| 值 | 说明 |
|---|---|
| true | 调用对象的任何方法都会触发懒加载 |
| false | 仅调用懒加载属性自身的方法时才触发加载 |
lazyLoadTriggerMethods
| 参数 | 默认值 | 说明 |
|---|---|---|
| lazyLoadTriggerMethods | equals,clone,hashCode,toString | 触发懒加载的方法列表 |
XML
<setting name="lazyLoadTriggerMethods" value="equals,clone,hashCode,toString"/>
映射相关设置
mapUnderscoreToCamelCase
| 参数 | 默认值 | 说明 |
|---|---|---|
| mapUnderscoreToCamelCase | false | 是否开启数据库下划线字段到 Java 驼峰字段的自动映射 |
XML
<setting name="mapUnderscoreToCamelCase" value="true"/>
开启后，数据库字段 user_name 会自动映射到 Java 字段 userName。
推荐：现代项目中基本都应开启此设置，避免编写冗余的 resultMap。
autoMappingBehavior
| 参数 | 默认值 | 说明 |
|---|---|---|
| autoMappingBehavior | PARTIAL | 自动映射策略 |
XML
<setting name="autoMappingBehavior" value="PARTIAL"/>
| 值 | 说明 |
|---|---|
| NONE | 禁用自动映射 |
| PARTIAL | 默认，自动映射没有嵌套 resultMap 的列 |
| FULL | 自动映射所有列，包括嵌套 resultMap |
autoMappingUnknownColumnBehavior
| 参数 | 默认值 | 说明 |
|---|---|---|
| autoMappingUnknownColumnBehavior | NONE | 发现未映射列时的行为 |
| 值 | 说明 |
|---|---|
| NONE | 不处理（默认） |
| WARNING | 输出警告日志 |
| FAILING | 抛出异常 |
XML
<!-- 开发阶段推荐设置为 WARNING，及时发现字段不匹配问题 -->
<setting name="autoMappingUnknownColumnBehavior" value="WARNING"/>
日志相关设置
logImpl
| 参数 | 默认值 | 说明 |
|---|---|---|
| logImpl | 自动检测 | 指定 MyBatis 使用的日志实现 |
XML
<!-- 使用 SLF4J 日志 -->
<setting name="logImpl" value="SLF4J"/>
<!-- 使用 Log4j2 -->
<setting name="logImpl" value="LOG4J2"/>
<!-- 使用 StdOut（控制台输出，仅开发调试用） -->
<setting name="logImpl" value="STDOUT_LOGGING"/>
| 日志实现 | 说明 |
|---|---|
| SLF4J | 推荐，配合 Logback/Log4j2 使用 |
| LOG4J2 | 直接使用 Log4j2 |
| JDK_LOGGING | JDK 内置日志 |
| STDOUT_LOGGING | 标准输出，仅调试 |
| NO_LOGGING | 禁用日志 |
logPrefix
| 参数 | 默认值 | 说明 |
|---|---|---|
| logPrefix | 无 | 日志输出前缀 |
XML
<setting name="logPrefix" value="[MyBatis]"/>
其他常用设置
defaultExecutorType
| 参数 | 默认值 | 说明 |
|---|---|---|
| defaultExecutorType | SIMPLE | 默认执行器类型 |
XML
<setting name="defaultExecutorType" value="SIMPLE"/>
| 执行器类型 | 说明 |
|---|---|
| SIMPLE | 默认，每次执行创建新预处理语句 |
| REUSE | 复用预处理语句 |
| BATCH | 批量执行模式，适合批量操作 |
defaultStatementTimeout
| 参数 | 默认值 | 说明 |
|---|---|---|
| defaultStatementTimeout | null（无限制） | SQL 执行超时时间（秒） |
XML
<!-- 设置 30 秒超时 -->
<setting name="defaultStatementTimeout" value="30"/>
推荐：生产环境务必设置超时时间，防止慢 SQL 拖垮连接池。
defaultFetchSize
| 参数 | 默认值 | 说明 |
|---|---|---|
| defaultFetchSize | null | 结果集抓取行数提示 |
XML
<!-- 每次从数据库拉取 100 行 -->
<setting name="defaultFetchSize" value="100"/>
适用场景：查询大量数据时，设置合理的 fetchSize 可以减少内存消耗。
useGeneratedKeys
| 参数 | 默认值 | 说明 |
|---|---|---|
| useGeneratedKeys | false | 全局开启 JDBC getGeneratedKeys 获取自增主键 |
XML
<setting name="useGeneratedKeys" value="true"/>
开启后，INSERT 语句可以自动回填自增主键到实体对象中。
useColumnLabel
| 参数 | 默认值 | 说明 |
|---|---|---|
| useColumnLabel | true | 使用列标签代替列名 |
XML
<setting name="useColumnLabel" value="true"/>
保持默认值即可，不同数据库驱动对列名和列标签的支持有差异。
safeRowBoundsEnabled
| 参数 | 默认值 | 说明 |
|---|---|---|
| safeRowBoundsEnabled | false | 是否在嵌套语句中使用 RowBounds |
XML
<setting name="safeRowBoundsEnabled" value="false"/>
safeResultHandlerEnabled
| 参数 | 默认值 | 说明 |
|---|---|---|
| safeResultHandlerEnabled | true | 是否在嵌套语句中使用 ResultHandler |
XML
<setting name="safeResultHandlerEnabled" value="true"/>
完整配置示例
XML
<settings>
<!-- 缓存 -->
<setting name="cacheEnabled" value="true"/>
<setting name="localCacheScope" value="SESSION"/>
<!-- 懒加载 -->
<setting name="lazyLoadingEnabled" value="false"/>
<setting name="aggressiveLazyLoading" value="false"/>
<!-- 映射 -->
<setting name="mapUnderscoreToCamelCase" value="true"/>
<setting name="autoMappingBehavior" value="PARTIAL"/>
<setting name="autoMappingUnknownColumnBehavior" value="WARNING"/>
<!-- 日志 -->
<setting name="logImpl" value="SLF4J"/>
<!-- 执行器 -->
<setting name="defaultExecutorType" value="SIMPLE"/>
<setting name="defaultStatementTimeout" value="30"/>
<setting name="defaultFetchSize" value="100"/>
<!-- 其他 -->
<setting name="useGeneratedKeys" value="true"/>
<setting name="useColumnLabel" value="true"/>
</settings>
要点总结
cacheEnabled控制二级缓存开关，一级缓存始终开启lazyLoadingEnabled控制懒加载，配合aggressiveLazyLoading实现按需加载mapUnderscoreToCamelCase实现下划线到驼峰的自动映射，推荐开启logImpl指定日志实现，生产推荐 SLF4J + Logback/Log4j2defaultStatementTimeout设置 SQL 超时，生产环境必须配置useGeneratedKeys开启后可自动回填自增主键
📝 发现内容有误？点击此处直接编辑