Welcome to `jade-plugin-sql`

jade-plugin-sql是一个 paoding-rose-jade 插件。它能够根据 DAO 方法，自动生成 SQL 语句，减少手动拼写SQL工作量。

（jade原生的@SQL方式和本插件使用的方式默认同时有效，互相不冲突）

User Guide

Maven Dependency

<dependency>
    <groupId>net.paoding</groupId>
    <artifactId>jade-plugin-sql</artifactId>
    <!-- A young boy! Hahaha~~ -->
    <version>0.0.1</version>
</dependency>

通过Spring配置jade-plugin-sql

    <context:annotation-config />

    <bean id="dataSource"
        class="org.springframework.jdbc.datasource.DriverManagerDataSource">
        <property name="driverClassName" value="org.hsqldb.jdbc.JDBCDriver" />
        <property name="url" value="jdbc:hsqldb:mem:jade_plugin_sql_db" />
    </bean>

    <!-- 启用Jade配置 -->
    <bean class="net.paoding.rose.jade.context.spring.JadeBeanFactoryPostProcessor" />

    <!-- 启用jade-plugin-sql插件 -->
    <bean class="net.paoding.rose.jade.plugin.sql.PlumSQLInterpreter">
        <property name="dialect">
            <bean class="net.paoding.rose.jade.plugin.sql.dialect.MySQLDialect" />
        </property>
    </bean>

一个基本CRUD

首先我们需要一个实体类对数据进行封装。

/*
 *  当类名完全符合驼峰到下划线转换规则，可不使用@Table注解。
 *  即：User -> user。
 */
@Table
public class User implements Serializable {

    /**
     * 
     */
    private static final long serialVersionUID = 7106854911318965104L;

    // 设置主键列
    @Column(pk = true)
    private Long id;

    // 完全符合规则的字段也必须声明Column，告诉插件将其映射为表中的列。
    @Column
    private String name;

    @Column
    private Integer age;

    /*
     *  实体默认排序规则：当某个对于该实体的查询操作不设定任何排序条件则按createTime降序。
     */
    @Column(order = Direction.DESC)
    private Date createTime;

    /*
     *  指定列名：当列名不符合驼峰转下划线规则使用Annotation标记。
     */
    @Column("last_update_time")
    private Date lstUpdTime;

    // 未标注@Column的属性将不被映射为表字段。
    private Object other;

    // Getter & Setter

}

编写一个DAO。

/*
 * 继承GenericDAO并使用泛型标注对应的实体类型，即拥有了基本的CRUD操作。
 * 你并不需要一个实现类，在Service层中直接使用：
 * @Resource
 * private UserDAO userDAO;
 * spring框架将为之注入一个自动生成的实现。
 */
@DAO
public interface UserDAO extends GenericDAO<UserDO, Long> {
}

如此以来，我们从GenericDAO上继承得到了基本的CRUD操作，但这在日常的开发工作中显然不够满足需求，本插件提供了一系列的约定，让你仅仅在接口中声明出方法，即可获得该方法的实际功能。

按指定字段查询：

    /**
     * 指定字段查询
     * @param age
     * @return
     */
    // 无需@SQL注解手写sql语句，实际的SQL语句由jade-plugin-sql动态生成
    public List<UserDO> findByAge(@SQLParam("age") Integer age);

如上，当你定义了这样一个方法，则会自动在该方法被调用时生成一条SQL，并执行它，自动封装为返回值指定的结果类型：

    SELECT
        id,
        name,
        age,
        create_time,
        last_update_time
    FROM
        user 
    WHERE
        age = :age 
    ORDER BY
        -- 来自DO中的默认排序
        create_time DESC

字符串Like查询：

    /**
     * 字符串Like查询
     * @param name 传进来的name参数自己负责百分号的拼接，比如传入"zhang%"
     * @return
     */
    public List<UserDO> findByName(@SQLParam("name") @Like String name);

值区间查询：

    /**
     * 值区间查询
     * @param min
     * @param max
     * @return
     */
    public List<UserDO> findByAgeBwteen(
            @SQLParam("age") @Ge Long min,
            @SQLParam("age") @Le Long max);

指定排序条件查询：

    /**
     * 排序查询
     * @param name
     * @param order
     * @return
     */
    public List<UserDO> findByNameLikeWithOrder(
            @SQLParam("name") @Like String name,
            Order order);

我们也简单做了一些语法糖使Order对象的创建变得方便。

    userDAO.findByNameLikeWithOrder("Plum%", Plum.asc("name", "age").desc("createTime"));

如上所示，该方法执行时，将自动生成SQL：

    SELECT
        id,
        name,
        age,
        create_time,
        last_update_time 
    FROM
        user 
    WHERE
        name like :name 
    ORDER BY
        -- 当指定了排序条件时，将不会使用DO中的默认排序。
        name ASC,
        age ASC,
        create_time DESC

查询记录区间：

    /**
     * Range查询
     * @param name
     * @param range
     * @return
     */
    public List<UserDAO> findWithLimit(
            @SQLParam("name") @Like String name,
            @Offset Integer start,
            @Limit Integer limit);

    userDAO.findWithLimit("Plum%", 0, 2);

    SELECT
        id,
        name,
        age,
        create_time,
        last_update_time 
    FROM
        user 
    WHERE
        name like :name 
    ORDER BY
        create_time DESC
    LIMIT 0, 2

IN查询

    /**
     * In查询
     * @param groupIds
     * @return
     */
    public List<UserInfoDO> findByGroupIds(
            @SQLParam("groupId") @In List<Integer> groupIds);

    List<UserInfoDO> userInfos = userInfoDAO.findByGroupIds(groupIds);

    SELECT
        id,
        name,
        group_id,
        birthday,
        age,
        money,
        create_time,
        last_update_time,
        status,
        editable 
    FROM
        user_info 
    WHERE
        group_id IN (
            :groupId
        ) 
    ORDER BY
        create_time DESC

指定条件更新指定字段

    /**
     * 通过指定字段条件更新
     * @param name
     * @param group
     */
    public void updateByGroupIds(
            @SQLParam("name") String name,
            @SQLParam("age") int age,
            @Where
            @SQLParam("groupId") @In List<Integer> group);

在被@Where标记前的所有参数被应用到WHERE子句，否则被应用到UPDATE子句。

    userInfoDAO.updateByGroupIds("Alan.Geng", 29, groupIds);

    UPDATE
        user_info 
    SET
        name = :name,
        age = :age 
    WHERE
        group_id IN (
            :groupId
        )

用于参数的一些Annotation：

Eq: 运算符"="
Ne: 运算符"!="
Ge: 运算符">="
Gt: 运算符">"
Le: 运算符"<="
Lt: 运算符"<"
Like: SQL关键字"LIKE"
In: SQL关键字"IN"
Offset: 查询记录偏移量
Limit: 最大返回记录数

上述的内容不同的数据库需要在方言中实现，默认给出MySQL的实现。

你只要记住几个预定义的注解，不用写一条SQL，即可完成单表操作90%以上的需求，在这里需要特别注意的是，使用本插件时，@SQLParam中的串应该是Bean的属性名，不能写成表的列名。 例如:

这是对的：@SQLParam("userName")；

这是错的：@SQLParam("user_name")

尽管提供了如此丰富的查询约定规则，但无论如何是满足不了所有需求的。此时，直接使用jade的原生方式吧：

    @SQL("select id, name, cola, colb from my_table where xxxx")
    public List<UserDAO> findWithSQL(xxxx);

Welcome to jade-plugin-sql