MyBatis 核心配置查阅文档（含详细项目目录，大白话版）本文档把MyBatis核心配置的关键知识点，都改成了大白话，

本文档把MyBatis核心配置的关键知识点，都改成了大白话，包括项目目录怎么放、别名怎么配、数据库连接怎么弄、日志怎么设置，还有需要注意的地方和配置好的验证方法，方便大家日常开发的时候快速查阅，一看就懂。

一、MyBatis 项目详细目录结构（Maven 标准结构）

下面是MyBatis项目最常用的目录结构，不管是代码、配置文件，都按这个标准放，后续维护和扩展都方便。里面会标注出咱们前面提到的db.properties、log4j.properties这些配置文件，具体放哪个位置。

1.1 整体目录框架（分层说明，一看就懂）

mybatis-demo（项目根目录，整个项目的总文件夹）
├─ src（源代码根目录，所有代码和资源都在这里面）
│  ├─ main（主程序目录，项目运行的核心代码和配置都在这）
│  │  ├─ java（Java源代码目录，写Java代码的地方，按包名分文件夹）
│  │  │  ├─ com.msb（项目基础包，你可以改成自己的包名，比如com.xxx）
│  │  │  │  ├─ pojo（实体类包，放和数据库表对应的类，就是别名配置里要用到的类）
│  │  │  │  │  ├─ Book.java（自定义实体类，比如数据库有个图书表，就建这个类对应）
│  │  │  │  │  └─ People.java（自定义实体类，和上面类似，对应数据库的表）
│  │  │  │  ├─ mapper（Mapper接口包，放和SQL语句对应的接口，和后面的XML文件对应）
│  │  │  │  │  ├─ BookMapper.java（Book实体对应的接口，和BookMapper.xml对应）
│  │  │  │  │  └─ PeopleMapper.java（People实体对应的接口，和PeopleMapper.xml对应）
│  │  │  │  ├─ service（业务逻辑层，可选，用来写业务逻辑的，比如判断登录、处理数据）
│  │  │  │  │  ├─ BookService.java（Book相关的业务接口）
│  │  │  │  │  └─ impl（业务实现类，具体实现上面接口的逻辑）
│  │  │  │  │     └─ BookServiceImpl.java（BookService接口的具体实现）
│  │  │  │  ├─ dao（数据访问层，可选，可和mapper包合并，功能差不多）
│  │  │  │  └─ util（工具类包，放常用的工具，比如获取MyBatis连接的工具）
│  │  │  │     └─ MyBatisUtil.java（工具类，用来获取连接、关闭连接，不用每次都写重复代码）
│  │  └─ resources（资源文件目录，放所有配置文件的地方，MyBatis核心配置在这）
│  │     ├─ mybatis-config.xml（MyBatis主配置文件，所有核心配置都在这，是MyBatis的入口）
│  │     ├─ db.properties（数据库连接配置文件，专门放数据库的地址、用户名、密码）
│  │     ├─ log4j.properties（Log4j日志配置文件，控制日志怎么输出，比如打印SQL）
│  │     └─ mapper（Mapper XML映射文件目录，放所有SQL语句的地方，和java里的mapper接口对应）
│  │        ├─ BookMapper.xml（BookMapper接口对应的XML，专门写Book相关的SQL语句）
│  │        └─ PeopleMapper.xml（PeopleMapper接口对应的XML，写People相关的SQL语句）
│  └─ test（测试程序目录，用来测试代码能不能跑通，SQL能不能执行成功）
│     ├─ java（测试代码目录，和main里的java包结构一样，方便对应测试）
│     │  └─ com.msb
│     │     └─ mapper
│     │        ├─ BookMapperTest.java（测试BookMapper里的SQL能不能执行）
│     │        └─ PeopleMapperTest.java（测试PeopleMapper里的SQL能不能执行）
│     └─ resources（测试资源目录，可选，放测试用的配置文件，一般不用改）
├─ pom.xml（Maven项目核心配置文件，用来引入需要的工具，比如MyBatis、Log4j、数据库驱动）
└─ target（编译输出目录，自动生成的，里面是编译后的文件，不用手动操作）

1.2 关键目录/文件说明（和本文档配置对应，直白好懂）

src/main/resources：核心配置文件的存放地，咱们用到的3个关键配置文件（mybatis-config.xml、db.properties、log4j.properties）都放这，MyBatis会自动找这个目录里的配置，不用额外设置路径。
src/main/resources/mybatis-config.xml：MyBatis的“总开关”，别名配置、数据库连接引入、日志配置、SQL映射文件扫描，都在这个文件里配置，没有它MyBatis没法正常运行。
src/main/resources/db.properties：专门放数据库连接信息的文件，把数据库地址、驱动、用户名、密码单独放这，后续要改数据库，直接改这个文件就行，不用动主配置文件，很方便。
src/main/resources/log4j.properties：控制日志的文件，必须放这个目录，而且文件名不能改，不然MyBatis识别不了，日志就打印不出来了。
src/main/resources/mapper：放SQL语句的目录，每个XML文件对应一个mapper接口，里面写增删改查的SQL，需要在mybatis-config.xml里配置一下，告诉MyBatis去哪里找这些SQL文件（比如写）。
src/main/java/com.msb/pojo：放实体类的目录，就是和数据库表对应的类，后面配置别名的时候，要用到这个目录的路径（比如com.msb.pojo），路径错了别名就失效了。
pom.xml：用来“导入”工具的文件，比如我们需要用MyBatis、Log4j、连接数据库的驱动，都要在这个文件里配置，配置好后，项目才能正常使用这些工具。

1.3 目录配置注意事项（必看，避免踩坑）

db.properties、log4j.properties这些配置文件，必须放在src/main/resources目录下，不然MyBatis找不到，会出现数据库连不上、日志不输出的问题，配置等于白做。
Mapper XML文件和Mapper接口的名字，最好一样（比如BookMapper.java对应BookMapper.xml），而且XML文件里的namespace，必须和接口的全路径一样（比如com.msb.mapper.BookMapper），不然会出现“找不到SQL”“映射失败”的错误。
实体类的目录路径（比如com.msb.pojo），要和别名配置里的路径完全一样，不然别名识别不了，写SQL的时候还是要写长长的全路径，别名就白配了。
test目录的结构，最好和main目录一样，比如main里有com.msb.mapper，test里也建一个com.msb.mapper，这样测试代码好管理，而且能直接用main里的配置文件，不用重复配置。

二、别名配置（typeAlias）

2.1 别名的作用（直白说）

就是为了省事儿，不用每次写SQL的时候，都写长长的类名（比如com.msb.pojo.Book），给这个类起个短名字（比如b、book），写SQL的时候直接用短名字，配置文件也更干净、更好看。

2.2 别名的分类与配置方式（一步一步说，好操作）

2.2.1 内置别名（不用自己配，直接用）

MyBatis早就给常见的Java类型（比如String、int、日期这些）起好短名字了，不用我们自己配置，写SQL的时候直接用就行，不分大小写（比如写string、String都可以）。常用的内置别名如下表，记不住可以随时查：

别名（短名字）	对应的Java类型（长名字）	别名（短名字）	对应的Java类型（长名字）	别名（短名字）	对应的Java类型（长名字）
_byte	byte（基本类型，小字节）	string	String（字符串类型）	date	Date（日期类型）
_long	long（基本类型，长整数）	byte	Byte（包装类型，对应_byte）	decimal	BigDecimal（高精度小数，比如金额）
_short	short（基本类型，短整数）	long	Long（包装类型，对应_long）	bigdecimal	BigDecimal（和上面一样，不分大小写）
_int/_integer	int（基本类型，整数）	short	Short（包装类型，对应_short）	object	Object（所有类的父类）
_double	double（基本类型，小数）	int/integer	Integer（包装类型，对应_int）	map	Map（键值对类型，比如存多个参数）
_float	float（基本类型，小数）	double	Double（包装类型，对应_double）	hashmap	HashMap（Map的常用实现类）
_boolean	boolean（基本类型，true/false）	float	Float（包装类型，对应_float）	list	List（集合类型，存多个对象）
-	-	boolean	Boolean（包装类型，对应_boolean）	arraylist	ArrayList（List的常用实现类）
-	-	-	-	collection	Collection（集合的父类）
-	-	-	-	iterator	Iterator（迭代器，用来遍历集合）

注意：基本类型（比如int、byte）的别名，前面都带一个“_”（比如_int）；包装类型（比如Integer、Byte）的别名，直接写类名小写就行（比如integer）。

2.2.2 自定义别名（自己给实体类起短名字，两种方法）

前面的内置别名，只适用于Java自带的类型，我们自己写的实体类（比如Book、People），需要自己给它们起别名，有两种方法，可单独用，也可以一起用。

方式一：单个类指定别名（实体类少的时候用）

就是给每个实体类，单独起一个短名字，用标签配置，想叫什么就叫什么，很灵活。

<typeAliases>
    <typeAlias type="com.msb.pojo.People" alias="p"/> <!-- type：实体类的全路径；alias：自己起的短名字 -->
    <typeAlias type="com.msb.pojo.Book" alias="b"/>
</typeAliases>

适用场景：实体类不多（比如就2、3个），或者想给某个类起个特殊的短名字（比如用p代替People）。

方式二：包扫描批量配置别名（实体类多的时候用，省事儿）

如果实体类很多（比如10个以上），一个个起别名太麻烦，就用这个方法，扫描整个实体类包，自动给所有实体类起别名，不用逐个配置。

<typeAliases>
    <package name="com.msb.pojo"/> <!-- name：实体类所在的包路径，比如所有实体类都在com.msb.pojo下 -->
</typeAliases>

别名规则：自动给每个实体类起别名，默认是类名首字母小写（不分大小写），比如com.msb.pojo.Book类，别名可以写book、Book、BOOK，都能用。

2.2.3 混合使用规则（两种方法一起用，怎么算生效）

单个类配置（）和包扫描配置（），可以一起用，不冲突；
优先级：自己单独起的别名（方式一）> 包扫描自动生成的别名（方式二）> 内置别名（系统自带的），如果有冲突，按这个顺序来，高优先级的覆盖低优先级的。

2.3 常见提示说明（遇到IDE提示不用慌）

配置别名的时候，如果IDE（比如IDEA）提示“XML tag has empty body”，不用管它，这只是IDE的一个格式提醒，不影响代码运行。也可以把标签改成自闭合的形式（比如），提示就会消失。

三、属性文件配置（db.properties）

3.1 配置目的（直白说）

就是把数据库的连接信息（比如数据库地址、用户名、密码），单独放在一个文件里，不和MyBatis主配置文件混在一起。后续要改数据库（比如从开发环境改成测试环境），直接改这个文件就行，不用动主配置文件，方便维护，也不容易出错。

3.2 配置步骤（一步一步来，新手也能会）

步骤1：创建db.properties文件

在项目的resources目录下（路径：src/main/resources），新建一个文件，名字叫db.properties，然后把下面的内容复制进去，改成自己的数据库信息：

# 数据库连接配置（下面的内容，改成自己的数据库信息）
url=jdbc:mysql://localhost:3306/msb?useUnicode=true&characterEncoding=utf-8&useSSL=false&serverTimezone=UTC
driver=com.mysql.cj.jdbc.Driver
username=root（自己的数据库用户名，一般默认是root）
password=root（自己的数据库密码，安装数据库时设置的）

步骤2：在mybatis-config.xml中引入配置

在MyBatis主配置文件（mybatis-config.xml）里，用标签引入刚才创建的db.properties文件，注意：这个标签必须放在标签的最前面，不然会报错。

<configuration>
    <!-- 引入数据库配置文件，这样就能用到里面的用户名、密码了 -->
    <properties resource="db.properties"/>
    
    <!-- 其他配置（别名、环境等），放在下面 -->
</configuration>

步骤3：在数据源中引用属性

在mybatis-config.xml的数据源配置里，用 ${key}的形式，引用db.properties里的配置（比如$ {username}就是引用里面的用户名），不用再手动写用户名、密码了。

<environments default="mysql">
    <environment id="mysql">
        <transactionManager type="JDBC"/>
        <dataSource type="POOLED">
            <property name="driver" value="${driver}"/>（引用db里的驱动）
            <property name="url" value="${url}"/>（引用db里的数据库地址）
            <property name="username" value="${username}"/>（引用db里的用户名）
            <property name="password" value="${password}"/>（引用db里的密码）
        </dataSource>
    </environment>
</environments>

四、日志功能配置（Log4j）

4.1 MyBatis支持的日志框架（不用记，了解就行）

MyBatis自带日志功能，能自动识别项目里配置的日志工具，常用的有SLF4J、Log4j 2、Log4j（1.x版本已经过时了）、JDK logging，我们这里主要说Log4j 1.x，方便旧项目兼容。

注意：MyBatis 3.5.9版本以后，Log4j 1.x已经被标记为“过时”了，新项目建议用Log4j 2或者SLF4J + Logback，功能更全、更稳定。

4.2 配置步骤（Log4j 1.x，旧项目可用，一步一步来）

步骤1：引入Log4j依赖

在pom.xml文件里，添加Log4j 1.2.17版本的依赖（这个版本最常用，兼容性好），添加后，项目才能使用Log4j日志功能。

<!-- Log4j 1.x 依赖（复制到pom.xml里即可） -->
<dependency>
    <groupId>log4j</groupId>
    <artifactId>log4j</artifactId>
    <version>1.2.17</version>
</dependency>

同时要确保，项目里已经引入了MyBatis和MySQL驱动的依赖，不然日志配置好了，也没法连接数据库、执行SQL。

步骤2：创建Log4j配置文件

在resources目录下（路径：src/main/resources），新建一个文件，名字必须叫log4j.properties（文件名和后缀都不能改，不然MyBatis识别不了），下面给两种常用的配置方案，选一种就行。

方案1：基础配置（输出所有日志到控制台，适合开发调试）

这种配置会打印所有日志，包括MyBatis的运行过程、数据库连接、SQL执行细节，适合开发的时候调试，能清楚看到哪里出问题了。

# 日志级别：fatal（最严重，致命错误）> error（错误）> warn（警告）> info（普通信息）> debug（调试信息）> trace（最详细）
# 根日志：级别设为DEBUG，所有调试信息都打印，输出到控制台
log4j.rootLogger = DEBUG, console

### 控制台输出配置（不用改，复制就行） ###
log4j.appender.console = org.apache.log4j.ConsoleAppender
log4j.appender.console.Target = System.out
log4j.appender.console.layout = org.apache.log4j.PatternLayout
# 日志输出格式：[级别] [时间] 类名.方法名(行号) | 日志内容（能清楚看到日志来源和内容）
log4j.appender.console.layout.ConversionPattern = [%p] [%-d{yyyy-MM-dd HH:mm:ss}] %C.%M(%L) | %m%n

方案2：优化配置（只输出SQL执行细节，避免冗余日志）

如果不想看太多无关日志，只想看SQL有没有执行、执行的是什么SQL、参数是什么，就用这种配置，只打印SQL相关的日志，更简洁。

# 全局日志级别：ERROR，只打印错误信息，减少冗余日志
log4j.rootLogger = ERROR, console

# 针对Mapper命名空间（替换成自己的）设为TRACE，只打印这个命名空间下的SQL细节
log4j.logger.a.b = TRACE

说明：把上面的“a.b”，改成自己Mapper XML文件里的namespace值（比如com.msb.mapper.BookMapper），这样就能精准打印出这个Mapper里的SQL执行细节，其他无关日志不会显示。

4.3 日志效果验证（配置好后，怎么判断生效了）

运行MyBatis的测试代码（比如BookMapperTest.java），如果控制台能输出下面这些内容，说明日志配置生效了：

日志初始化信息（比如“Logging initialized using 'log4j'”，意思是Log4j日志已经初始化好了）；
数据库连接信息（比如连接建立、连接关闭的日志，说明数据库能连上）；
SQL执行细节（如果配置了TRACE级别，会打印出完整的SQL语句、传入的参数、查询到的结果，能清楚看到SQL有没有执行成功）。

五、核心注意事项汇总（必看，避免踩坑）

配置顺序：标签（引入db.properties的标签），必须放在mybatis-config.xml的最前面，不然会报错，这个一定要记牢。
文件名约束：log4j.properties必须放在resources根目录，而且文件名不能改，改了MyBatis识别不了；db.properties建议也放在resources根目录，方便查找和引用。
别名优先级：自己单独起的别名 > 包扫描自动生成的别名 > 系统内置别名，有冲突的话，按这个顺序来。
日志级别：开发的时候，用DEBUG或TRACE级别，能看到详细的调试信息，方便找问题；上线（生产环境）的时候，用INFO或ERROR级别，减少日志冗余，避免影响项目运行速度。
版本兼容：Log4j 1.x已经过时了，新项目尽量用Log4j 2；如果用的是MySQL 8.0及以上版本，驱动类必须写com.mysql.cj.jdbc.Driver，还要在数据库地址后面加serverTimezone参数（比如UTC），不然连不上数据库。
资源路径：db.properties、log4j.properties这些配置文件，必须放在resources目录下，不然MyBatis找不到，配置等于白做，会出现连不上数据库、日志不输出的问题。
Mapper XML和接口的对应：Mapper XML文件和Mapper接口的名字，最好一样，而且XML里的namespace，必须和接口的全路径一样（比如com.msb.mapper.BookMapper），不然会找不到SQL，出现映射失败的错误。
实体类路径：实体类的包路径（比如com.msb.pojo），要和别名配置里的路径完全一样，不然别名识别不了，写SQL的时候还是要写长长的全路径，别名就白配了。

六、配置效果验证总结（配置好后，怎么判断没问题）

当所有配置都做好后，运行测试代码，如果能看到下面这些效果，说明所有配置都正确，能正常使用了：

数据库能成功连接，没有“连接失败”“密码错误”之类的报错；
控制台能打印出完整的SQL语句（比如select * from t_book，就是你写的查询语句）；
能看到SQL执行的参数（比如传入的图书ID）和查询结果（比如图书名称、作者，一行一行的具体数据）；
日志里会显示数据库连接的开启和关闭，说明数据源配置正常，MyBatis能自动管理连接。