文档标签

文档标签主要由以下构成：

• <select> 标签，用于配置 SELECT 语句。
• <update> 标签、<delete> 标签，用于配置 UPDATE 和 DELETE 语句。
• <insert> 标签，用于配置 INSERT 语句。
• <selectKey> 标签，在 <insert> 标签内可以使用 <selectKey> 标签获取自增主键，从而避免再次查询数据库。
• <execute> 标签，可以用来执行任意的 SQL 语句。
• <sql> 标签，定义 SQL 片段。

select 标签

<select> 标签等同于 @Query 注解，用于配置 SELECT 语句，对于简单的情况只需要具体的 SQL 语句即可。例如:

例1：简单案例

<select id="queryListByAge">
    select * from users where age = #{age}
</select>

例2：使用 resultType 属性将查询结果映射到类型

<select id="queryById" resultType="com.example.dto.UserBean">
    select 
        id, name, age, create_time
    from
        users
    where
        id = #{id}
</select>

标签属性

属性名	描述
id	必选 用于标识查询命令。
statementType	可选 表示查询类型，表示 JDBC 查询使用何种方式。默认值为 PREPARED - STATEMENT 对应 java.sql.Statement - PREPARED 对应 java.sql.PreparedStatement - CALLABLE 对应 java.sql.CallableStatement
timeout	可选 通过设置一个大于 0 时会被设置到 java.sql.Statement.setQueryTimeout(int) 可以让查询在执行时候设置一个超时时间，单位是秒，默认值为 -1
fetchSize	可选 通过设置一个大于 0 时会被设置到 java.sql.Statement.setFetchSize(int)，用于为 JDBC 驱动程序提供一个提示。它提示此查询生成的 ResultSet 对象需要更多行时应该从数据库获取的行数。默认值是 256
resultMap	可选 引用 <resultMap> 或 <entity> 标签配置的映射。 - 可以使用 resultMap 和 resultType 其中一个属性但不应同时使用它们。如果都没有配置将会参照映射的接口返回值类型决定。
resultType	可选 将返回的预期类型的完全限定类名或 类型别名。提示：在集合的情况下，这应该是集合的元素类型，而不是集合本身的类型。 - 可以使用 resultMap 和 resultType 其中一个属性但不应同时使用它们。如果都没有配置将会参照映射的接口返回值类型决定。
resultSetType	可选 当通过 java.sql.Connection 创建查询 statement 时候，该值决定了 resultSetType 参数的具体值。 - 可选值列表： FORWARD_ONLY、SCROLL_INSENSITIVE、SCROLL_SENSITIVE 和 DEFAULT。默认值为 DEFAULT 相当于未设置。 - statementType 为 STATEMENT 时对应 java.sql.Connection.createStatement(int, int) 方法第一个参数。 - statementType 为 PREPARED 时对应 java.sql.Connection.prepareStatement(java.lang.String, int, int)方法第二个参数。 - statementType 为 CALLABLE 时对应 java.sql.Connection..prepareCall(java.lang.String, int, int)方法第二个参数。
resultSetExtractor	可选 可为查询配置一个 ResultSetExtractor 对象用于结果集处理（如果配置了 bindOut 那么该配置将会失效）
resultRowCallback	可选 可为查询配置一个 RowCallbackHandler 对象用于结果集处理（如果配置了 bindOut 那么该配置将会失效）
resultRowMapper	可选 可为查询配置一个 RowMapper 对象用于结果集处理（如果配置了 bindOut 那么该配置将会失效）
resultTypeHandler	可选 可为该方法配置一个 TypeHandler 对象用于结果集处理（如果配置了 bindOut 那么该配置将会失效）
bindOut	可选 当 Query 中使用了 多值 或者 存储过程调用，使用 bindOut 参数可以绑定其中的输出参数。 请注意：一旦使用了该参数那么接口返回值类型必须为 Map<String,Object> 类型。

update 和 delete 标签

<update> 标签等同于 @Update 注解、<delete> 标签等同于 @Delete 注解。用于配置对应的 UPDATE、DELETE 语句。

<update id="updateAge">
    update users set age = #{age} where id = #{id}
</update>

<delete id="deleteById">
    delete from users where id = #{id}
</delete>

标签属性

属性名	描述
id	必选 用于标识查询命令
statementType	可选 表示查询类型，表示 JDBC 查询使用何种方式。默认值为 PREPARED - STATEMENT 对应 java.sql.Statement - PREPARED 对应 java.sql.PreparedStatement - CALLABLE 对应 java.sql.CallableStatement
timeout	可选 通过设置一个大于 0 时会被设置到 java.sql.Statement.setQueryTimeout(int) 可以让查询在执行时候设置一个超时时间，单位是秒，默认值为 -1

insert 标签

<insert> 标签等同于 @Insert 注解，用于配置对应的 INSERT 语句。

<insert id="insertUser">
    insert into users (
        id,    name,    age,    create_time
    ) values (
        #{id}, #{name}, #{age}, #{createTime}
    )
</insert>

标签属性

属性名	描述
id	必选 用于标识查询命令
statementType	可选 表示查询类型，表示 JDBC 查询使用何种方式。默认值为 PREPARED - STATEMENT 对应 java.sql.Statement - PREPARED 对应 java.sql.PreparedStatement - CALLABLE 对应 java.sql.CallableStatement
timeout	可选 通过设置一个大于 0 时会被设置到 java.sql.Statement.setQueryTimeout(int) 可以让查询在执行时候设置一个超时时间，单位是秒，默认值为 -1
useGeneratedKeys	可选 是否使用自增属性。如果同时配置了 SelectKey 标签该配置将会失效。
keyProperty	可选 当 useGeneratedKeys 设置为 true 后，用于回填自增后属性值的 Bean 属性名。如果同时配置了 SelectKey 注解该属性将会失效。
keyColumn	可选 当 useGeneratedKeys 设置为 true 后，回填自增属性值时候选择的查询结果列名。如果同时配置了 SelectKey 注解该属性将会失效。

selectKey 标签

<selectKey> 标签需要和 <insert> 标签一起才能工作，它等同于 @SelectKeySql 注解。

有时候新增一条数据不仅仅要知道是否插入成功，因为后面的逻辑可能还需要这条新增数据的主键。 这时候可以使用 <selectKey> 标签获取自增主键从而避免再次查询数据库。 另外有些业务需要自定义数据表的主键，这个时候也可以使用 <selectKey> 标签来实现，它可以随意的设置生成主键的方式。

<insert id="insertUser">
    <selectKey keyProperty="id" order="BEFORE">
        SELECT CONCAT('1', CEILING(RAND() * 1000 + 1000))
    </selectKey>
    insert into `test_user` (
        `id`, `name`, `age`, `create_time`
    ) values (
        #{id}, #{name}, #{age}, #{createTime}
    )
</insert>

标签属性

属性名	描述
keyProperty	必选 用于回填自增后属性值的 Bean 属性名。
keyColumn	可选 用于回填自增属性值时候选择的查询结果列名。
order	必选 可以选择 Before 或者 After，表示用于获取自增主键的 SQL 执行时机是在 INSERT 操作之前还是之后。
statementType	可选 表示查询类型，表示 JDBC 查询使用何种方式。默认值为 PREPARED - STATEMENT 对应 java.sql.Statement - PREPARED 对应 java.sql.PreparedStatement - CALLABLE 对应 java.sql.CallableStatement
timeout	可选 通过设置一个大于 0 时会被设置到 java.sql.Statement.setQueryTimeout(int) 可以让查询在执行时候设置一个超时时间，单位是秒，默认值为 -1
fetchSize	可选 通过设置一个大于 0 时会被设置到 java.sql.Statement.setFetchSize(int)，用于为 JDBC 驱动程序提供一个提示。它提示此查询生成的 ResultSet 对象需要更多行时应该从数据库获取的行数。默认值是 256
resultSetType	可选 当通过 java.sql.Connection 创建查询 statement 时候，该值决定了 resultSetType 参数的具体值。 - 可选值列表： FORWARD_ONLY、SCROLL_INSENSITIVE、SCROLL_SENSITIVE 和 DEFAULT。默认值为 DEFAULT 相当于未设置。 - statementType 为 STATEMENT 时对应 java.sql.Connection.createStatement(int, int) 方法第一个参数。 - statementType 为 PREPARED 时对应 java.sql.Connection.prepareStatement(java.lang.String, int, int)方法第二个参数。 - statementType 为 CALLABLE 时对应 java.sql.Connection..prepareCall(java.lang.String, int, int)方法第二个参数。

execute 标签

<execute> 标签等同于 @Execute 注解。用于配置任意 SQL 语句。

<execute id="updateAge">
    update users set age = #{age} where id = #{id}
</execute>

标签属性

属性名	描述
id	必选 用于标识查询命令
statementType	可选 表示查询类型，表示 JDBC 查询使用何种方式。默认值为 PREPARED - STATEMENT 对应 java.sql.Statement - PREPARED 对应 java.sql.PreparedStatement - CALLABLE 对应 java.sql.CallableStatement
timeout	可选 通过设置一个大于 0 时会被设置到 java.sql.Statement.setQueryTimeout(int) 可以让查询在执行时候设置一个超时时间，单位是秒，默认值为 -1
bindOut	可选 对输出参数进行过滤，用来确定哪些结果参数会被接收，如果不指定将会接收所有参数。 请注意：一旦使用了该参数那么接口返回值类型必须为 Map<String,Object> 类型。

sql 标签

此标签可用于定义一段 SQL 并在同一个 Mapper 文件内进行引用，从而减少重复的 SQL 片段，例如：定义列名。

<sql id="testuser_columns">
    name,age,create_time
</sql>

<insert id="insertUser">
    insert into `test_user` (
        <include refid="testuser_columns"/>
    ) values (
        #{name}, #{age}, now()
    )
</insert>

标签属性

属性名	描述
id	必选 用于标识片段名称。