当前位置：首页 > news >正文

从零吃透XML映射文件｜零基础入门完整学习指南（附实操案例）

news 2026/7/23 0:47:21

哈喽大家好！今天给大家带来一篇纯零基础、保姆级的 XML 映射文件学习教程。很多初学开发的小伙伴，都会被 MyBatis、框架配置中的 XML 映射文件搞懵：标签看不懂、语法不会写、报错找不到原因。

其实 XML 映射文件没有想象中复杂，它的核心本质只有一句话：用XML文件，实现「代码与底层操作的映射绑定」，替代硬编码配置，让程序更灵活、易维护。

本文不堆砌晦涩理论，从零讲解XML映射文件的作用、基础语法、核心标签、完整实操案例和常见坑点，看完就能独立编写、读懂项目中的XML映射文件。

一、先搞懂：什么是XML映射文件？

1.1 基础概念

XML（可扩展标记语言）是一种结构化标记语言，专注于数据存储、配置描述、关系映射。

而我们开发中常说的XML映射文件，是指用于建立两层数据/逻辑关联的XML配置文件，最典型、使用最多的场景就是MyBatis Mapper映射文件（本文核心实操场景）。

1.2 核心作用（为什么要用它？）

在没有映射文件时，我们操作数据库需要在Java代码中硬写SQL，存在两大痛点：

代码耦合严重：SQL语句嵌在Java代码里，修改SQL需要改代码、重启项目
维护成本极高：大量SQL散落代码中，排查问题、统一管理极其麻烦

XML映射文件的出现，完美解决了以上问题，核心价值：

解耦分离：Java业务代码和 SQL语句完全分离，各司其职
统一管理：一张表对应一个Mapper映射文件，所有增删改查操作集中存放
灵活适配：支持动态SQL、参数映射、结果封装，适配复杂业务场景
简化开发：无需手动封装数据库结果集，自动完成字段与实体类属性映射

二、前置基础：XML必须遵守的语法规则（零基础必看）

XML映射文件基于标准XML语法，语法容错率极低，一个符号错误就会导致项目报错，新手务必牢记以下核心规则：

2.1 基础语法规范

所有标签必须成对出现，有开始标签就必须有结束标签（如<mapper></mapper>），自闭合标签除外
标签名称严格大小写敏感，<Select>和<select>是完全不同的标签
属性值必须用引号包裹（单/双引号均可，推荐双引号）
标签嵌套必须规范，禁止交叉嵌套
文件第一行必须声明XML文档头，固定格式不可修改

2.2 标准XML文件头部（固定模板）

所有MyBatis XML映射文件，开头必须添加以下声明，用于定义文档版本和编码格式：

<?xml version="1.0" encoding="UTF-8"?> <!DOCTYPE mapper PUBLIC "-//mybatis.org//DTD Mapper 3.0//EN" "http://mybatis.org/dtd/mybatis-3-mapper.dtd">

简单解释：第二行是引入MyBatis的DTD约束，作用是校验当前XML文件的标签合法性，写错标签、非法属性会直接提示报错。

三、XML映射文件核心结构与核心标签（重点）

以开发最常用的MyBatis Mapper映射文件为例，完整文件结构分为：根标签 + 映射语句标签 + 辅助标签，下面逐个拆解必学标签。

3.1 根标签：mapper（全局核心）

<mapper>是整个映射文件的根标签，所有SQL语句、映射规则都需要写在该标签内部。

核心属性：namespace（唯一核心）

作用：绑定对应的Java Mapper接口，实现「接口方法」和「XML SQL」的映射关联
要求：必须和Mapper接口的全类名完全一致（包名+类名）
示例：namespace="com.example.demo.mapper.UserMapper"

3.2 四大基础CRUD标签

对应数据库增删改查四种操作，是日常开发使用最多的标签：

1. <select> 查询语句

用于数据库查询操作，核心属性：

id：对应Mapper接口中的抽象方法名，必须完全一致
parameterType：传入参数的类型（基本类型、实体类、集合），可省略
resultType：SQL查询结果封装的类型（实体类、基本类型），简单查询必备
resultMap：自定义结果映射规则，复杂字段映射必备（优先级高于resultType）

2. <insert> 新增语句

用于数据新增，支持返回自增主键、批量插入。

3. <update> 修改语句

用于数据库数据更新操作。

4. <delete> 删除语句

用于数据库数据删除操作。

3.3 核心映射标签（解决字段不匹配问题）

开发中最常见的问题：数据库字段名和 Java实体类属性名不一致（如数据库user_name，实体类userName），此时需要自定义映射。

1. resultMap 自定义结果映射

作用：手动绑定数据库字段与实体类属性，支持复杂映射、嵌套映射，是企业级开发首选。

核心子标签：

<id>：映射主键字段（提升查询效率）
<result>：映射普通字段

四、从零手写完整XML映射文件（实操案例）

理论看完直接上手实操！我们以User用户表为例，从零完成「实体类-Mapper接口-XML映射文件」全套配置，实现基础增删改查。

4.1 准备工作

1. 数据库user表字段：id（主键）、user_name、user_age、user_email

2. Java实体类User属性：id、userName、userAge、userEmail（驼峰命名，与数据库下划线命名不一致）

4.2 完整XML映射文件代码

创建UserMapper.xml映射文件，完整可直接运行代码如下：

<?xml version="1.0" encoding="UTF-8"?> <!DOCTYPE mapper PUBLIC "-//mybatis.org//DTD Mapper 3.0//EN" "http://mybatis.org/dtd/mybatis-3-mapper.dtd"> <!-- 根标签：绑定对应Mapper接口全类名 --> <mapper namespace="com.example.demo.mapper.UserMapper"> <!-- 自定义结果映射：解决数据库下划线字段与实体类驼峰属性不匹配 --> <resultMap id="UserResultMap" type="com.example.demo.entity.User"> <!-- 主键映射 --> <id column="id" property="id"/> <!-- 普通字段映射：column=数据库字段，property=实体类属性 --> <result column="user_name" property="userName"/> <result column="user_age" property="userAge"/> <result column="user_email" property="userEmail"/> </resultMap> <!-- 1. 根据ID查询用户 --> <select id="getUserById" parameterType="Long" resultMap="UserResultMap"> SELECT id,user_name,user_age,user_email FROM user WHERE id = #{id} </select> <!-- 2. 新增用户 --> <insert id="addUser" parameterType="com.example.demo.entity.User"> INSERT INTO user (user_name,user_age,user_email) VALUES (#{userName},#{userAge},#{userEmail}) </insert> <!-- 3. 修改用户信息 --> <update id="updateUser" parameterType="com.example.demo.entity.User"> UPDATE user SET user_name = #{userName},user_age = #{userAge},user_email = #{userEmail} WHERE id = #{id} </update> <!-- 4. 根据ID删除用户 --> <delete id="deleteUser" parameterType="Long"> DELETE FROM user WHERE id = #{id} </delete> </mapper>

4.3 配套Mapper接口（对应XML映射）

XML中的id必须和接口方法名一一对应，配套接口代码：

package com.example.demo.mapper; import com.example.demo.entity.User; import org.apache.ibatis.annotations.Param; public interface UserMapper { // 对应XML getUserById User getUserById(Long id); // 对应XML addUser int addUser(User user); // 对应XML updateUser int updateUser(User user); // 对应XML deleteUser int deleteUser(Long id); }