跳到主要内容

6.3 注解与选项

实体注解位于 com.dlz.db.core.anno，内置操作选项位于 com.dlz.db.option。业务代码不需要引用实现包。

1. 实体注解​

注解目标属性作用
@TableName类value、comment指定表名和建表注释
@TableId字段value、type指定主键列和 ID 策略
@TableField字段value、exist、select、comment指定列名、是否属于表字段、是否默认查询及列注释
@Schema类value提供实体描述，用于 DDL 表注释
@SchemaField字段value提供字段描述，用于 DDL 列注释

没有指定名称时，默认将 Java 驼峰名称转换为下划线名称。

import com.dlz.db.core.anno.IdType;
import com.dlz.db.core.anno.Schema;
import com.dlz.db.core.anno.SchemaField;
import com.dlz.db.core.anno.TableField;
import com.dlz.db.core.anno.TableId;
import com.dlz.db.core.anno.TableName;

@Schema("用户")
@TableName(value = "sys_user", comment = "用户表")
public class User {
    @TableId(type = IdType.AUTO)
    private Long id;

    @SchemaField("登录名称")
    @TableField(value = "user_name", comment = "登录名称")
    private String userName;

    @TableField(exist = false)
    private String displayText;

    private Integer deleted;
}

@TableField(select = false) 只影响实体默认投影；显式 .select(...) 时仍应根据业务需要选择列。exist = false 表示该字段不参与表字段映射。

2. 主键策略​

IdType行为
AUTO使用数据库自增或数据库生成的主键，并在支持的插入路径回填
SEQ使用 DLZ-DB 的号段 ID；这是 @TableId 的默认值
INPUT主键由业务代码提供
ASSIGN_ID主键为空时分配雪花 ID，适合数值或字符串字段
ASSIGN_UUID主键为空时分配无连字符 UUID，适合字符串字段

数据库自增主键必须显式写成 @TableId(type = IdType.AUTO)，不能依赖默认值。号段算法的实现和限制见 智能号段 ID。

3. null 字段选项​

直接插入和按 ID 更新方法接受 DbOption...：

import com.dlz.db.DB;
import com.dlz.db.option.InsertOption;
import com.dlz.db.option.UpdateOption;

DB.pojo.insert(user, InsertOption.INCLUDE_NULL);
DB.pojo.updateById(user, UpdateOption.INCLUDE_NULL);
选项适用操作作用
InsertOption.IGNORE_NULLINSERT忽略值为 null 的字段
InsertOption.INCLUDE_NULLINSERT把值为 null 的字段写入 SQL
UpdateOption.IGNORE_NULLUPDATE不更新值为 null 的字段
UpdateOption.INCLUDE_NULLUPDATE显式把相应列更新为 NULL

选项会校验适用的操作类型；把更新选项传给插入操作会失败。

4. 查询与删除选项​

import com.dlz.db.DB;
import com.dlz.db.option.DeleteOption;
import com.dlz.db.option.SelectOption;

User deleted = DB.pojo.selectById(
    User.class, id, SelectOption.INCLUDE_DELETED);

User locked = DB.pojo.selectById(
    User.class, id, SelectOption.FOR_UPDATE);

int affected = DB.pojo.deleteById(
    User.class, id, DeleteOption.PHYSICAL);
选项作用
SelectOption.INCLUDE_DELETED对支持 DbOption... 的直接查询取消逻辑删除过滤
SelectOption.FOR_UPDATE对支持该选项的查询追加 FOR UPDATE
DeleteOption.LOGIC使用逻辑删除
DeleteOption.PHYSICAL强制物理删除

当前 Pojo 查询 Wrapper 没有与 SelectOption.INCLUDE_DELETED 对称的稳定便捷方法。Wrapper 物理删除可使用：

int affected = DB.pojo.deleteWrapper(User.class)
    .eq(User::getId, id)
    .physical();

5. 自定义选项​

DbOption 与 com.dlz.db.option.point 下已经接线的桩点属于扩展 SPI，不是普通 CRUD 的必需部分。自定义选项必须：

  1. 实现 DbOption 以及至少一个已经接线的桩点。
  2. 通过 supports(DbOperation) 限制适用操作。
  3. 提供稳定且不冲突的 key()。
  4. 用 SQL 和行为测试证明桩点真实生效。

当前接线范围和兼容承诺见 API、SPI 与实现边界。源码中存在但没有执行路径消费的类型，不应仅因其是 public 就作为已支持能力使用。