HasorDB 映射文件

使用 Mapper 文件的好处是便于维护和管理 SQL，这在团队协作时 review sql 代码比起在程序中用代码来拼接要好。

文档结构​

下面是 HasorDB Mapper 文件基本结构：

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE mapper PUBLIC "-//hasor.net//DTD Mapper 1.0//EN" 
                        "https://www.hasor.net/schema/hasordb-mapper.dtd">
<mapper namespace="...">
    ...
</mapper>

提示
​namespace ​通常是配置一个接口类名，这个接口下的每个方法会对应到 mapper 文件中一个具体的 sql 操作上。

在 ​mapper ​根元素下可以使用的顶层 XML 元素有如下几个：

• resultMap 用于描述如何从查询结果集中加载数据。
• sql 用于定义一小段可以复用的 SQL 片段。
• insert 映射 INSERT 语句。
• update 映射 UPDATE 语句。
• delete 映射 DELETE 语句。
• select 映射 SELECT 语句。

select 操作​

select 标签是 HasorDB 中最常用的元素之一。对于简单的情况 select 元素非常简单。例如:

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

select 标签有很多属性下面列出的是每个属性和含义。

insert, update 和 delete 操作​

​insert​、​update​、​delete ​标签本质上是同一个标签，只是通过专门的名字来区分会让人更为容易理解。

一个简单的例子如下：

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

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

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

​insert​、​update​、​delete ​标签都有如下共同的属性。

selectKey​

对于不支持自增列的数据库，HasorDB 可以使用 ​selectKey ​标签来通过 SQL 方式生成它，比较常见用处是使用数据库的 ​sequence​。 例如：下面 Mapper 配置，在执行 ​insert ​之前会先使用数据库函数生成一个随机数作为主键。

<insert id="insertUser">
    <selectKey keyProperty="id" resultType="int" 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>

​selectKey ​标签有如下属性。

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>

结果集映射​

并不是每一个 ​select ​都必须要求配置 ​resultMap ​默认情况下会使用 Map 来承装返回的数据。

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

但通常 Map 并不是一个很好的模型设计，应该使用一些有意义的 pojo 充当数据对象。HasorDB 支持将一个普通的 pojo 映射到一个结果集上。例如下面这个 Bean：

​class net.hasor.db.example.mapper.TestUser​

public class TestUser {
    private Integer id;
    private String  name;
    private Integer age;
    private Date    createTime;

    public Integer getId() {
        return id;
    }
    public void setId(Integer id) {
        this.id = id;
    }
    public String getName() {
        return name;
    }
    public void setName(String name) {
        this.name = name;
    }
    public Integer getAge() {
        return age;
    }
    public void setAge(Integer age) {
        this.age = age;
    }
    public Date getCreateTime() {
        return createTime;
    }
    public void setCreateTime(Date createTime) {
        this.createTime = createTime;
    }
}

可以使用 ​resultType ​属性将查询结果映射到这个 Bean 上。

<select id="queryById" resultType="net.hasor.db.example.mapper.TestUser">
    select 
        id, name, age, create_time
    from
        test_user
    where
        id = #{id}
</select>

使用这种方式，HasorDB 会在加载配置文件的时候自动创建一个 ​resultMap​，根据名称将列自动映射到 pojo 的属性上。如果列名不完全匹配，可以在列名上使用 ​as ​子句来匹配映射。例如:

<select id="queryById" resultType="net.hasor.db.example.mapper.TestUser">
    select 
        id, name, age, create_time as createTime
    from
        test_user
    where
        id = #{id}
</select>

直接使用 ​resultMap ​的好处是可以更加精细化的控制每一个属性映射，以刚才的映射为例。在不通过 ​as ​改变列名的情况下映射这个 pojo：

<resultMap id="testuser_resultMap" type="net.hasor.db.example.mapper.TestUser">
    <id column="id" property="id"/>
    <result column="name" property="name"/>
    <result column="age" property="age"/>
    <result column="create_time" property="createTime"/>
</resultMap>

<select id="queryById" resultMap="testuser_resultMap">
    select
        id, name, age, create_time
    from
        test_user
    where
        id = #{id}
</select>

​resultMap ​标签有如下属性。

id &

​id ​和 ​result ​都是用于映射列和属性之间的映射关系。不同的是 id 可以方便的指出列在数据中是否为主键。

在使用通用 Mapper 时，CURD 操作将会依赖 ​id​、​table​、​schema ​这些属性用以生成 SQL。

它们每个标签都有下面这些属性

多结果映射​

例如，一个 ​select ​配置了两个 查询语句。或者调用的存储过程中执行了两条 查询 SQL。​resultType ​中以逗号作为分割将两个结果分别映射到两个类型上。

提示
使用 ​resultMap ​同样也可以通过逗号作为分割，映射多个结果。

<select id="multipleListByAge" multipleResult="ALL"
        resultType="net.hasor.db.example.mapper.TestUserPojo,net.hasor.db.example.mapper.TestUser">
    select id, name, age, create_time as createTime from `test_user` where age = #{age};
    select * from `test_user`;
</select>

自动映射​

上面已经介绍过 ​resultMap ​和 ​resultType ​的能力，在本节可以了解通过自动映射机制来混合两种操作。

HasorDB 会尝试将结果集中的列名作为属性名进行写入，匹配的时会忽略大小写。 这意味着，如果找到名为 ​ID ​的列和名为 ​ID ​的属性，HasorDB 将使用 ​ID ​列值设置 ​ID ​属性。

<resultMap id="testuser_resultMap" type="net.hasor.db.example.mapper.TestUser">
    <result property="createTime" column="create_time"/>
</resultMap>

<select id="queryById" resultMap="testuser_resultMap">
    select
        id, name, age, create_time
    from
        test_user
    where
        id = #{id}
</select>

通常数据库列的命名使用大写字母和下划线，这与 java 通常遵循驼峰命名约定有一定的差异。 若想使它们之间自定映射需要设置 ​mapUnderscoreToCamelCase ​为 ​true​

<resultMap id="testuser_resultMap" type="net.hasor.db.example.mapper.TestUser" 
           mapUnderscoreToCamelCase="true"/>

<select id="queryById" resultMap="testuser_resultMap">
    select
        id, name, age, create_time
    from
        test_user
    where
        id = #{id}
</select>

提示
默认情况下 HasorDB 是启用自动映射的，如果你不像使用这一特性。则可以通过设置 ​autoMapping ​为 ​false ​来关闭它。