JPwise-docs

Appearance

实体类参考 ​

📐 实体详解：BaseEntity和SysBaseEntity的完整字段说明

📋 目录 ​

BaseEntity详解 ​

概述 ​

BaseEntity 是业务实体的基类，包含了所有业务表的通用字段。业务实体类必须继承此类。

字段清单（全大写命名） ​

java
public class BaseEntity {
    
    // ==================== 主键字段 ====================
    @Schema(description = "主键ID")
    @Id(value = "ID")
    @Column(value = "ID")
    @JsonProperty("ID")
    private String ID;
    
    // ==================== 创建信息 ====================
    @Schema(description = "创建时间")
    @Column("CREATORTIME")
    @JsonProperty("CREATORTIME")
    private Date CREATORTIME;
    
    @Schema(description = "创建人ID")
    @Column("CREATORUSER")
    @JsonProperty("CREATORUSER")
    private String CREATORUSER;
    
    // ==================== 修改信息 ====================
    @Schema(description = "最后修改时间")
    @Column("LASTMODIFYTIME")
    @JsonProperty("LASTMODIFYTIME")
    private Date LASTMODIFYTIME;
    
    @Schema(description = "最后修改人ID")
    @Column("LASTMODIFYUSER")
    @JsonProperty("LASTMODIFYUSER")
    private String LASTMODIFYUSER;
    
    // ==================== 删除信息（软删除）====================
    @Schema(description = "删除时间")
    @Column("DELETETIME")
    @JsonProperty("DELETETIME")
    private Date DELETETIME;
    
    @Schema(description = "删除人ID")
    @Column("DELETEUSER")
    @JsonProperty("DELETEUSER")
    private String DELETEUSER;
    
    // ==================== 通用属性 ====================
    @Schema(description = "有效标志")
    @Column("ENABLEDMARK")
    @JsonProperty("ENABLEDMARK")
    private String ENABLEDMARK;
    
    @Schema(description = "排序码")
    @Column("SORTCODE")
    @JsonProperty("SORTCODE")
    private Integer SORTCODE;
    
    @Schema(description = "组织ID")
    @Column("ORGANIZE")
    @JsonProperty("ORGANIZE")
    private String ORGANIZE;
    
    // ==================== 工作流字段 ====================
    @Schema(description = "流程状态")
    @Column("FLOWPHASE")
    @JsonProperty("FLOWPHASE")
    private String FLOWPHASE;
    
    @Schema(description = "流程环节名称")
    @Column("STEPNAME")
    @JsonProperty("STEPNAME")
    private String STEPNAME;
    
    // Getter和Setter方法...
}

字段说明 ​

核心字段 ​

  • ID: 主键，通常使用雪花算法生成的字符串
  • CREATORTIME: 记录创建时间，自动设置
  • CREATORUSER: 创建人ID，关联用户表
  • LASTMODIFYTIME: 最后修改时间，更新时自动设置
  • LASTMODIFYUSER: 最后修改人ID

软删除字段 ​

  • DELETETIME: 删除时间，删除时设置
  • DELETEUSER: 删除人ID，删除时设置
  • 查询时需要过滤：queryWrapper.isNull(Entity::getDELETEUSER)

通用属性 ​

  • ENABLEDMARK: 有效标志，"1"表示有效，"0"表示无效
  • SORTCODE: 排序码，用于列表排序
  • ORGANIZE: 组织ID，用于数据权限控制

工作流字段 ​

  • FLOWPHASE: 当前流程状态
  • STEPNAME: 当前流程环节名称

扩展字段 ​

  • F_1 到 F_5: 预留的扩展字段，可用于存储额外信息

SysBaseEntity详解 ​

概述 ​

SysBaseEntity 是系统实体的基类，用于系统级别的表（如用户、菜单、角色等）。字段采用驼峰命名。

字段清单（驼峰命名） ​

java
public class SysBaseEntity {
    
    // ==================== 主键字段 ====================
    @Schema(description = "主键ID")
    @Id(value = "id")
    @Column(value = "id")
    private String id;
    
    // ==================== 创建信息 ====================
    @Schema(description = "创建时间")
    @Column("create_time")
    private Date creatorTime;
    
    @Schema(description = "创建人")
    @Column("creator_user")
    private String creatorUser;
    
    // ==================== 修改信息 ====================
    @Schema(description = "最后修改时间")
    @Column("last_modify_time")
    private Date lastModifyTime;
    
    @Schema(description = "最后修改人")
    @Column("last_modify_user")
    private String lastModifyUser;
    
    // ==================== 通用属性 ====================
    @Schema(description = "有效标志")
    @Column("enabled_mark")
    private Integer enabledMark;
    
    @Schema(description = "排序码")
    @Column("sort_code")
    private Integer sortCode;
    
    @Schema(description = "描述")
    @Column("description")
    private String description;
    
    // Getter和Setter方法...
}

系统实体特点 ​

  • 字段使用驼峰命名（如 creatorTime）
  • 数据库字段使用下划线（如 creator_time）
  • 比业务实体字段更精简
  • 没有工作流相关字段
  • 没有软删除机制（直接物理删除）

实体使用规范 ​

继承选择 ​

java
// ✅ 业务实体继承BaseEntity
@Table("LEAVE_APPLICATION")
public class LeaveApplicationEntity extends BaseEntity {
    // 业务字段使用全大写
    private String LEAVETITLE;
    private Date STARTTIME;
    private BigDecimal AMOUNT;
}

// ✅ 系统实体继承SysBaseEntity
@Table("sys_menu")
public class SysMenuEntity extends SysBaseEntity {
    // 系统字段使用驼峰命名
    private String menuName;
    private String menuUrl;
    private Integer sortOrder;
}

常用操作示例 ​

java
// 创建业务实体
BusinessEntity entity = new BusinessEntity();
entity.setID(RandomUtil.uuId());
entity.setCREATORUSER(userProvider.get().getUserId());
entity.setCREATORTIME(DateUtil.getNowDate());
entity.setENABLEDMARK("1");
entity.setORGANIZE(userProvider.get().getOrganizeId());

// 更新业务实体
entity.setLASTMODIFYUSER(userProvider.get().getUserId());
entity.setLASTMODIFYTIME(DateUtil.getNowDate());

// 软删除业务实体
entity.setDELETEUSER(userProvider.get().getUserId());
entity.setDELETETIME(DateUtil.getNowDate());

子表关联配置 ​

@SubEntity注解详解 ​

java
@Table("main_table")
public class MainEntity extends BaseEntity {
    
    // 主要业务字段
    private String TITLE;
    private String CODE;
    
    // 子表关联配置
    @Schema(description = "明细列表")
    @SubEntity(
        targetEntity = DetailEntity.class,     // 子表实体类
        service = DetailService.class,         // 子表Service类
        foreign = "MAINID"                     // 子表外键字段名
    )
    @Column(ignore = true)                     // 不映射到数据库字段
    @JsonProperty("DETAILLIST")                // JSON序列化时的属性名
    private List<DetailEntity> DETAILLIST;
}

子表实体定义 ​

java
@Table("detail_table")
public class DetailEntity {
    // 注意：子表实体不继承BaseEntity，只包含必要字段
    
    @Id(value = "ID")
    @Column(value = "ID")
    @JsonProperty("ID")
    private String ID;
    
    @Schema(description = "主表ID")
    @Column("MAINID")
    @JsonProperty("MAINID")
    private String MAINID;  // 外键，关联主表
    
    @Schema(description = "明细名称")
    @Column("DETAILNAME")
    @JsonProperty("DETAILNAME")
    private String DETAILNAME;
    
    @Schema(description = "数量")
    @Column("QUANTITY")
    @JsonProperty("QUANTITY")
    private Integer QUANTITY;
    
    @Schema(description = "金额")
    @Column("AMOUNT")
    @JsonProperty("AMOUNT")
    private BigDecimal AMOUNT;
}

多子表配置 ​

java
@Table("order_table")
public class OrderEntity extends BaseEntity {
    
    // 订单明细
    @SubEntity(targetEntity = OrderDetailEntity.class,
               service = OrderDetailService.class,
               foreign = "ORDERID")
    @Column(ignore = true)
    @JsonProperty("ORDERDETAILS")
    private List<OrderDetailEntity> ORDERDETAILS;
    
    // 订单附件
    @SubEntity(targetEntity = OrderAttachmentEntity.class,
               service = OrderAttachmentService.class,
               foreign = "ORDERID")
    @Column(ignore = true)
    @JsonProperty("ATTACHMENTS")
    private List<OrderAttachmentEntity> ATTACHMENTS;
}

字段映射规范 ​

注解配置完整示例 ​

java
@Data
@EqualsAndHashCode(callSuper = true)
@Table("BUSINESS_ENTITY")
@Schema(description = "业务实体")
public class BusinessEntity extends BaseEntity {
    
    // 字符串字段
    @Schema(description = "业务标题", required = true)
    @Column("TITLE")
    @JsonProperty("TITLE")
    @NotBlank(message = "标题不能为空")
    @Size(max = 200, message = "标题长度不能超过200字符")
    private String TITLE;
    
    // 数值字段
    @Schema(description = "金额", example = "1000.00")
    @Column("AMOUNT")
    @JsonProperty("AMOUNT")
    @NotNull(message = "金额不能为空")
    @DecimalMin(value = "0.01", message = "金额必须大于0")
    @Digits(integer = 10, fraction = 2, message = "金额格式不正确")
    private BigDecimal AMOUNT;
    
    // 日期字段
    @Schema(description = "开始时间")
    @Column("STARTTIME")
    @JsonProperty("STARTTIME")
    @JsonFormat(pattern = "yyyy-MM-dd HH:mm:ss", timezone = "GMT+8")
    @NotNull(message = "开始时间不能为空")
    private Date STARTTIME;
    
    // 枚举字段
    @Schema(description = "状态", allowableValues = "DRAFT,PENDING,APPROVED,REJECTED")
    @Column("STATUS")
    @JsonProperty("STATUS")
    @Pattern(regexp = "^(DRAFT|PENDING|APPROVED|REJECTED)$", message = "状态值不正确")
    private String STATUS;
    
    // 布尔字段（数据库存储为字符串）
    @Schema(description = "是否紧急")
    @Column("ISURGENT")
    @JsonProperty("ISURGENT")
    private String ISURGENT;  // "1"表示是，"0"表示否
}

特殊字段处理 ​

java
// JSON字段（MySQL 5.7+）
@Schema(description = "扩展属性")
@Column("PROPERTIES")
@JsonProperty("PROPERTIES")
private String PROPERTIES;  // 存储JSON字符串

// 大文本字段
@Schema(description = "详细说明")
@Column("DESCRIPTION")
@JsonProperty("DESCRIPTION")
@Size(max = 4000, message = "详细说明不能超过4000字符")
private String DESCRIPTION;

// 文件路径字段
@Schema(description = "附件路径")
@Column("ATTACHMENTPATH")
@JsonProperty("ATTACHMENTPATH")
private String ATTACHMENTPATH;

验证注解使用 ​

常用验证注解 ​

java
public class BusinessEntity extends BaseEntity {
    
    // 非空验证
    @NotNull(message = "字段不能为空")
    @NotBlank(message = "字符串不能为空")
    @NotEmpty(message = "集合不能为空")
    private String field;
    
    // 长度验证
    @Size(min = 1, max = 100, message = "长度必须在1-100之间")
    private String name;
    
    // 数值验证
    @Min(value = 0, message = "值不能小于0")
    @Max(value = 999999, message = "值不能大于999999")
    @DecimalMin(value = "0.01", message = "金额必须大于0")
    @DecimalMax(value = "999999.99", message = "金额不能超过999999.99")
    private BigDecimal amount;
    
    // 格式验证
    @Pattern(regexp = "^1[3-9]\\d{9}$", message = "手机号格式不正确")
    private String phone;
    
    @Email(message = "邮箱格式不正确")
    private String email;
    
    // 日期验证
    @Past(message = "日期必须是过去的时间")
    @Future(message = "日期必须是将来的时间")
    @DateTimeFormat(pattern = "yyyy-MM-dd")
    private Date date;
    
    // 自定义验证
    @AssertTrue(message = "业务规则验证失败")
    private boolean isValid() {
        return this.AMOUNT != null && this.AMOUNT.compareTo(BigDecimal.ZERO) > 0;
    }
}

分组验证 ​

java
// 定义验证分组
public interface CreateGroup {}
public interface UpdateGroup {}

public class BusinessEntity extends BaseEntity {
    
    @NotBlank(groups = CreateGroup.class, message = "创建时标题不能为空")
    @Size(groups = {CreateGroup.class, UpdateGroup.class}, max = 200)
    private String TITLE;
    
    @Null(groups = CreateGroup.class, message = "创建时不能指定ID")
    @NotBlank(groups = UpdateGroup.class, message = "更新时ID不能为空")
    private String ID;
}

// Controller中使用
@PostMapping
public ActionResult create(@Validated(CreateGroup.class) @RequestBody BusinessEntity entity) {
    // 只验证CreateGroup中的规则
}

@PostMapping("/update/{id}")
public ActionResult update(@Validated(UpdateGroup.class) @RequestBody BusinessEntity entity) {
    // 只验证UpdateGroup中的规则
}

实体最佳实践 ​

1. 字段命名一致性 ​

java
// ✅ 正确：业务实体全大写
private String BUSINESSNAME;
private String CONTACTPHONE;
private BigDecimal TOTALAMOUNT;

// ✅ 正确：系统实体驼峰
private String businessName;
private String contactPhone;
private BigDecimal totalAmount;

2. 必要的注解完整性 ​

java
// 每个字段都应该有的注解
@Schema(description = "字段描述")  // API文档
@Column("FIELD_NAME")            // 数据库映射
@JsonProperty("FIELD_NAME")      // JSON序列化
private String fieldName;

3. 合理使用继承 ​

java
// 业务实体继承BaseEntity
public class BusinessEntity extends BaseEntity {
    // 获得完整的审计字段和工作流支持
}

// 系统实体继承SysBaseEntity
public class SysConfigEntity extends SysBaseEntity {
    // 获得基础的系统字段
}

// 简单的子表或DTO不继承基类
public class DetailEntity {
    // 只包含必要字段，保持轻量
}

💡 提示：正确使用BaseEntity和SysBaseEntity是JPwise项目的核心规范。业务实体必须继承BaseEntity并使用全大写字段命名，系统实体继承SysBaseEntity并使用驼峰命名。合理配置子表关联和验证注解可以大大简化开发工作。