Basic Structure of Mapper XML Files

In the MyBatis framework, Mapper XML files serve as the critical bridge connecting the Java code layer with low-level database interactions. They are responsible for defining and persisting SQL statements, dynamic parameter mappings, and result set processing logic in text form. A standard Mapper XML file is typically composed of multiple core child elements wrapped within a root <mapper> node, including namespace declarations, SQL fragment libraries (<sql>), primary query/insert/update/delete method interfaces (<select>, <insert>, <update>, <delete>), and result set mapping tags (<resultMap>).

Understanding the basic structure of Mapper XML is crucial for writing maintainable, high-performance persistence layer code. The following sections will provide a detailed analysis of its core components and their practical application in development.
Every Mapper XML file must contain a root <mapper> node, where the most important attribute is namespace. The value of this attribute should uniquely identify the corresponding Mapper interface, typically matching the specific class path under the Java package name (e.g., com.example.mapper.UserMapper). MyBatis automatically locates the corresponding Java Interface method using reflection based on this namespace, thereby establishing an association between XML configuration and code interfaces.

In addition to the root node, the XML file can define one or more <sql> tags to encapsulate generic SQL fragments. This design pattern significantly enhances code reusability and flexibility. Developers can extract common WHERE, ORDER BY, or complex nested query logic and reference them through ${} placeholders in multiple Mapper XML files for combination purposes.

<!-- Example: Define a general sorting statement -->
<sql id="commonOrderBy">
    ORDER BY create_time DESC, id ASC
</sql>

Detailed Explanation of Core SQL Mapping Tags

The core functionality of Mapper XML is described through specific tags that define different database operation behaviors. MyBatis provides four primary result set or execution style tags: <select>, <insert>, <update> and <delete>. These tags internally contain an id (unique identifier), a resultMap (optional, used to define column-to-object mapping relationships), and the core SQL statement content.

• Query Operation (<select>):
  This is the most commonly used tag type, typically located at the top or middle of the Mapper XML file. It defines the logic for retrieving data from the database. Inside a <select>, you can use parameterType to specify the input parameter type (e.g., Java Bean) and perform string concatenation via ${} or implement conditional filtering using dynamic SQL syntax such as <if> or <choose>.

• Insert Operation (<insert>):
  Used for adding new records to the database. This tag typically includes a keyProperty attribute to specify the primary key field, allowing automatic back-writing of the primary key value into Java objects after transaction submission. Additionally, you can configure useGeneratedKeys="true" to enable the mechanism for generating auto-increment IDs.

• Update and Delete Operations:
  The <update> and <delete> tags follow a similar logical structure, primarily used to modify existing data or remove specified records. They also support dynamic SQL to construct complex conditional expressions (e.g., handling AND/OR connections in multi-table join queries).

Result Set Mapping and Parameter Type Configuration

To enable MyBatis to accurately fill raw row data returned by the database into Java objects, it is often necessary to define <resultMap>. When column names in tables do not match property names in Java Beans (e.g., user_name in the database versus userName in code), or when result set structures from multi-table join queries are complex, using ResultMap becomes particularly essential.

ResultMap establishes mapping relationships between database columns and Java properties through child elements such as <column>, <property> and <association>/<collection>. Simultaneously, configuring parameterType="com.example.User" within each SQL method tag simplifies the parameter passing process; MyBatis will automatically deconstruct the passed-in argument object and populate it into the generated PreparedStatement statement.

<!-- Example: Define a result set mapping for User objects -->
<resultMap id="BaseResultMap" type="com.example.mapper.User">
    <id column="user_id" property="userId"/>
    <column property="username"/>
    <column property="email"/>
</resultMap>

<!-- Example: Query statement using ResultMap -->
<select id="selectUserById" resultMap="BaseResultMap">
    SELECT user_id, username, email FROM users WHERE user_id = #{userId}
</select>

Best Practices and Performance Optimization Suggestions

When writing Mapper XML files, in addition to following the basic structure, attention should also be paid to code readability and execution efficiency. First, keeping SQL statements concise is crucial; avoiding overly long single-line strings prevents maintenance difficulties. Second, fully utilize dynamic tags like <if> and <where> to handle complex business logic judgments. This ensures that generated SQL syntax remains correct (e.g., automatically removing excess ANDs) while improving code readability.

Furthermore, for scenarios involving multi-table join queries, it is recommended to prioritize using ResultMap rather than manually parsing JSON or string streams to construct objects. This approach significantly reduces memory consumption and improves serialization efficiency. Finally, common complex SQL logic should be modularly encapsulated within <sql> fragments and managed through a unified namespace, ensuring consistency in the data access layer style across the entire project.

In summary, while Mapper XML files are merely one form of configuration file, reasonable design of their structure directly determines the performance ceiling of MyBatis applications and the development experience. Mastering its basic structure, flexibly utilizing dynamic SQL, and correctly handling result set mapping is a core skill that every backend developer must be proficient in.