@Insert 注解

用来标记在接口方法上，执行一个 INSERT 语句。

信息

如果传入的是一个字符串数组，它们会被连接起来，中间用一个空格隔开。
通过字符串数组可以更清晰地管理多行 SQL。

示例：新增一条用户记录

@SimpleMapper
public interface UserMapper {
    @Insert({ "insert into users (",                      // 1. 定义 SQL 语句
              "    id, name, age, create_time",           //
              ") values (",                               //
              "    #{id}, #{name}, #{age}, #{createTime}", //
              ")" })
    int saveUser(UserDTO user);                           // 2. user 对象为参数
}

属性清单

属性名	描述
value	必选 将要被执行的 INSERT 语句。
statementType	可选 JDBC 执行使用何种方式。默认值为 Prepared - Statement 对应 java.sql.Statement - Prepared 对应 java.sql.PreparedStatement - Callable 对应 java.sql.CallableStatement
timeout	可选 设置执行超时时间（秒），会调用 Statement.setQueryTimeout(int)。默认值 -1 表示不设置
useGeneratedKeys	可选 是否使用自增属性。如果同时配置了 @SelectKeySql 注解，该配置将会失效。
keyProperty	可选 当 useGeneratedKeys = true 时，用于回填自增值的 Bean 属性名。如果同时配置了 @SelectKeySql 注解，该属性将会失效。
keyColumn	可选 当 useGeneratedKeys = true 时，从返回结果集中选择的列名用于回填。默认选择结果集的第一列。如果同时配置了 @SelectKeySql 注解，该属性将会失效。

小提示

keyColumn 属性为空时，将会选择返回结果集的第一个列值作为回填结果。

@SelectKeySql 注解

有时新增数据后需要获取自增主键，用于后续业务逻辑。@SelectKeySql 注解可以在 INSERT 前后执行一条额外的 SQL 来获取主键值，并回填到参数对象中。

该注解需要与 @Insert 配合使用。

示例：INSERT 后获取 MySQL 自增 ID

//create table users (
//  id          bigint auto_increment primary key,
//  name        varchar(255),
//  age         int,
//  create_time datetime
//);

@SimpleMapper
public interface UserMapper {
    @Insert({ "insert into users (",               // 1. 定义 SQL 语句
              "    name, age, create_time",         //
              ") values (",                         //
              "    #{name}, #{age}, #{createTime}", //
              ")" })
    // 在 INSERT 执行后，使用 MySQL last_insert_id() 获取自增 ID，并回填到参数对象的 id 属性
    @SelectKeySql(value = "select last_insert_id()", keyProperty = "id", order = Order.After)
    int saveUser(UserDTO user);
}

UserMapper mapper = ...;
UserDTO user = ...;

mapper.saveUser(user);

long afterId = user.getId(); // 自增 ID 已被回填

属性清单

属性名	描述
value	必选 用于获取自增主键的 SQL 查询语句。
keyProperty	必选 回填主键值的 Bean 属性名。
order	必选 执行时机：Before（INSERT 之前）或 After（INSERT 之后）。
keyColumn	可选 从查询结果中选择的列名用于回填。默认选择第一列。
statementType	可选 JDBC 执行方式。默认值为 Prepared
timeout	可选 执行超时时间（秒）。默认值 -1 表示不设置
fetchSize	可选 每次从数据库获取的行数。默认值为 256
resultSetType	可选 结果集类型：FORWARD_ONLY、SCROLL_INSENSITIVE、SCROLL_SENSITIVE、DEFAULT（默认）