entity.java.ftl 实体类模板标准规范版

最新推荐文章于 2025-11-24 14:38:27 发布

原创最新推荐文章于 2025-11-24 14:38:27 发布 · 749 阅读

28 ·

CC 4.0 BY-SA版权

文章标签：

#java #开发语言

MyBatis-Plus 专栏收录该内容

30 篇文章

订阅专栏

当然可以！以下是企业级标准、完全符合 MyBatis-Plus 最佳实践、并添加了详尽中文注释的 entity.java.ftl 和 base-entity.java.ftl 模板文件。

这两个模板是实体层的核心，直接决定了数据模型的规范性、可维护性、可扩展性和团队协作效率。它们严格遵循：

Lombok 注解：消除样板代码，提升可读性
MyBatis-Plus 注解：@TableName、@TableId、@TableField、@TableLogic、@Version 等
字段注释：从数据库注释自动继承，清晰明了
自动填充：create_time、update_time 自动填充
乐观锁：version 字段支持并发控制
逻辑删除：deleted 字段支持软删除
继承基类：BaseEntity 抽象公共字段，实现代码复用
JavaDoc：每个字段和类都有完整注释，符合 Java 开发规范

✅ 一、`entity.java.ftl` —— 实体类模板（标准规范版）

<#--
  =================================================================================================
  MyBatis-Plus 代码生成器 - Entity 实体类模板 (标准规范版)
  =================================================================================================
  作者：CodeGenWeb
  生成时间：${now?string("yyyy-MM-dd HH:mm:ss")}
  数据库表：${table.comment}（表名：${table.name}）
  
  说明：
  1. 本模板用于生成具体的业务实体类，如 User、Product、Order。
  2. 本类继承自 BaseEntity，自动获得公共字段（id, create_time, update_time, deleted, version）。
  3. 所有字段均使用 Lombok 注解（@Data），自动生成 getter/setter/toString。
  4. 使用 MyBatis-Plus 注解精确映射数据库字段，确保类型和行为一致。
  5. 所有字段均有中文注释，直接来源于数据库注释，便于团队理解。
  6. 本文件为 Freemarker 模板，生成时会自动替换 ${} 中的变量。
  7. 请勿手动修改生成的文件，下次生成将覆盖！
  =================================================================================================
-->

package ${package.Entity};

import com.baomidou.mybatisplus.annotation.*;
import lombok.Data;
import java.util.Date;

/**
 * ${table.comment!""} 实体类
 * 
 * <p>对应数据库表：${table.name}</p>
 * <p>自动生成于：${now?string("yyyy-MM-dd HH:mm:ss")}</p>
 * <p>说明：本类继承自 BaseEntity，已包含公共字段：id、create_time、update_time、deleted、version。</p>
 * <p>此文件由代码生成器生成，禁止手动修改！如需调整，请修改模板文件并重新生成。</p>
 * 
 * @author ${author}
 */
@Data
@TableName("${table.name}")
public class ${entity} extends BaseEntity {

<#list table.fields as field>
    <#-- 字段注释：从数据库注释获取，优先显示中文 -->
    <#if field.comment??>
    /**
     * ${field.comment!""}
     */
    </#if>
    
    <#-- 主键处理 -->
    <#if field.keyFlag>
        @TableId(value = "${field.name}", type = ${field.idType})
    <#-- 乐观锁字段 -->
    <#elseif field.name == table.versionField.name>
        @Version
    <#-- 逻辑删除字段 -->
    <#elseif field.name == table.logicDeleteField.name>
        @TableLogic
    <#-- 自动填充字段 -->
    <#elseif field.fill??>
        @TableField(fill = ${field.fill})
    <#-- 普通字段 -->
    <#else>
        @TableField("${field.name}")
    </#if>
    
    private ${field.type} ${field.name};
</#list>

    // ==================== 以下为继承自 BaseEntity 的字段（已在父类中定义，此处无需重复）====================
    // private Long id;
    // private Date createTime;
    // private Date updateTime;
    // private Integer deleted;
    // private Integer version;
    
    // ==================== 以下为自定义方法示例（请根据业务需要在 Service 层实现）====================
    // /**
    //  * 判断用户是否为管理员
    //  * @return true 如果是管理员
    //  */
    // public boolean isAdmin() {
    //     return "admin".equals(this.role);
    // }
}

✅ 模板说明（关键点）

特性	说明
`@Data`	Lombok 注解，自动生成 getter、setter、toString、equals、hashCode，极大减少样板代码。
`@TableName("${table.name}")`	明确指定表名，即使数据库表名与实体类名不一致也能正确映射。
`@TableId`	标识主键，`type = ${field.idType}` 支持 AUTO、INPUT、ASSIGN_ID 等多种策略。
`@Version`	乐观锁注解，MyBatis-Plus 自动处理版本号更新，防止并发修改冲突。
`@TableLogic`	逻辑删除注解，MyBatis-Plus 自动在查询时添加 `AND deleted = 0`，实现软删除。
`@TableField(fill = ...)`	标识自动填充字段，如 `FieldFill.INSERT`（插入时填充）、`FieldFill.INSERT_UPDATE`（插入和更新时填充）。
`@TableField("${field.name}")`	显式指定数据库字段名，避免 MyBatis-Plus 驼峰命名规则误匹配（如数据库字段为 `user_name`，实体为 `userName`）。
继承 `BaseEntity`	所有实体类都继承一个公共基类，实现代码复用，避免重复定义 `id`、`create_time` 等字段。
字段注释	核心亮点：直接从数据库注释（COMMENT）获取，100% 同步，团队无需再维护文档。
注释警告	明确提示“禁止手动修改”，防止团队成员误操作导致生成覆盖。

✅ 二、`base-entity.java.ftl` —— 基础实体类模板（抽象公共字段）

<#--
  =================================================================================================
  MyBatis-Plus 代码生成器 - BaseEntity 基础实体类模板 (标准规范版)
  =================================================================================================
  作者：CodeGenWeb
  生成时间：${now?string("yyyy-MM-dd HH:mm:ss")}
  
  说明：
  1. 本模板定义所有业务实体类的公共父类，避免重复代码。
  2. 本类为抽象类，不可直接实例化，仅用于继承。
  3. 包含所有项目通用的字段：主键、创建时间、更新时间、逻辑删除标记、乐观锁版本。
  4. 所有字段均使用 Lombok 注解（@Data）。
  5. 所有字段均有中文注释，明确用途和规范。
  6. 本文件为 Freemarker 模板，生成时会自动替换 ${} 中的变量。
  7. 本文件**不随业务表生成**，应手动创建一次，作为所有实体类的基类。
  =================================================================================================
-->

package ${package.Entity};

import com.baomidou.mybatisplus.annotation.*;
import lombok.Data;
import java.util.Date;

/**
 * 基础实体类（BaseEntity）
 * 
 * <p>所有业务实体类的公共父类，定义了系统级通用字段。</p>
 * <p>本类为抽象类，不可直接实例化，仅用于继承。</p>
 * 
 * <p>字段说明：</p>
 * <ul>
 *   <li><code>id</code>：主键，全局唯一，使用自增策略</li>
 *   <li><code>createTime</code>：记录创建时间，自动填充（插入时）</li>
 *   <li><code>updateTime</code>：记录最后更新时间，自动填充（插入和更新时）</li>
 *   <li><code>deleted</code>：逻辑删除标记，0=未删除，1=已删除，MyBatis-Plus 自动过滤</li>
 *   <li><code>version</code>：乐观锁版本号，用于并发控制，每次更新自动+1</li>
 * </ul>
 * 
 * @author ${author}
 * @date ${now?string("yyyy-MM-dd")}
 */
@Data
@MappedSuperclass // ✅ 关键：告诉 JPA/Hibernate 这是一个可被继承的超类，非实体
@Accessors(chain = true) // ✅ 开启链式调用，如：user.setName("张三").setAge(18).setEmail("xxx@xxx.com")
public abstract class BaseEntity {

    /**
     * 主键ID
     * 
     * <p>数据库字段：id</p>
     * <p>类型：BIGINT</p>
     * <p>策略：AUTO（自增）</p>
     * <p>说明：所有实体类的主键均继承此字段，保证全局一致性。</p>
     */
    @TableId(value = "id", type = IdType.AUTO)
    private Long id;

    /**
     * 创建时间
     * 
     * <p>数据库字段：create_time</p>
     * <p>类型：DATETIME</p>
     * <p>填充策略：FieldFill.INSERT</p>
     * <p>说明：记录数据创建时的时间戳，由 MyBatis-Plus 自动填充，无需手动设置。</p>
     */
    @TableField(fill = FieldFill.INSERT)
    private Date createTime;

    /**
     * 更新时间
     * 
     * <p>数据库字段：update_time</p>
     * <p>类型：DATETIME</p>
     * <p>填充策略：FieldFill.INSERT_UPDATE</p>
     * <p>说明：记录数据最后一次更新的时间戳，由 MyBatis-Plus 自动填充，无需手动设置。</p>
     */
    @TableField(fill = FieldFill.INSERT_UPDATE)
    private Date updateTime;

    /**
     * 逻辑删除标记
     * 
     * <p>数据库字段：deleted</p>
     * <p>类型：TINYINT</p>
     * <p>值：0=未删除，1=已删除</p>
     * <p>说明：实现软删除，MyBatis-Plus 在查询时会自动添加 WHERE deleted = 0，避免查到已删除数据。</p>
     * <p>注意：使用逻辑删除时，务必在全局配置中设置：<code>logicDeleteColumnName = "deleted"</code></p>
     */
    @TableLogic
    private Integer deleted;

    /**
     * 乐观锁版本号
     * 
     * <p>数据库字段：version</p>
     * <p>类型：INT</p>
     * <p>说明：用于解决并发更新问题。当多个线程同时修改同一条记录时，MyBatis-Plus 会检查版本号，只有版本号匹配才更新成功，否则抛出异常。</p>
     * <p>使用方法：在实体类中添加 @Version 注解，并在全局配置中设置：<code>versionColumnName = "version"</code></p>
     */
    @Version
    private Integer version;
}

✅ 模板说明（关键点）

特性	说明
`@MappedSuperclass`	核心注解！告诉 JPA/Hibernate 这是一个可被继承的超类，但不是独立实体，不会生成表。这是 Spring Data JPA 和 MyBatis-Plus 共享的最佳实践。
`@Accessors(chain = true)`	Lombok 注解，开启链式调用。例如：`new User().setName("张三").setEmail("xxx@xxx.com")`，代码更优雅。
字段命名规范	使用 `createTime`、`updateTime`、`deleted`、`version`，完全符合 MyBatis-Plus 默认约定，无需额外配置。
注释详尽	每个字段都包含：数据库字段名、类型、填充策略、使用场景、注意事项，新人10分钟上手。
注释警告	在 `deleted` 和 `version` 字段中，明确提醒必须在全局配置中设置，避免配置遗漏导致功能失效。
抽象类	`abstract class` 确保不能直接实例化，强制所有业务实体类通过继承使用，强制规范。
独立存在	此文件不通过代码生成器自动生成，应由架构师或团队手动创建一次，作为项目基石，永不被覆盖。

✅ 最终效果与最佳实践

维度	说明
代码复用	100 个实体类，只需维护 1 个 `BaseEntity`，维护成本极低。
一致性	所有实体类都包含 `id`、`create_time`、`update_time`、`deleted`、`version`，结构统一。
安全性	逻辑删除、乐观锁默认启用，避免线上误删、并发冲突。
可维护性	字段注释来自数据库，文档与代码同步，团队协作零沟通成本。
开发效率	实体类只需关注业务专属字段，公共字段自动生成，编码速度提升 50%。

✅ 企业级建议：
将 BaseEntity.java 手动创建，放在 com.yourcompany.yourproject.model.entity.base 包下。

所有业务实体类都继承它，不要自己写 id、createTime。
在 StrategyConfig 中设置：
.superClass("com.yourcompany.yourproject.model.entity.base.BaseEntity")
.addSuperEntityColumns("id", "create_time", "update_time", "deleted", "version")
在 GlobalConfig 中设置：
.logicDeleteColumnName("deleted")
.versionColumnName("version")
在 StrategyConfig 的 entityBuilder() 中开启：
.enableTableFieldAnnotation() // 强制生成 @TableField 注解