dto.java.ftl 和 vo.java.ftl 两个核心数据传输对象模板文件2

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

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

9 ·

CC 4.0 BY-SA版权

文章标签：

#java #开发语言 #mybatis #前端 #typescript #javascript

MyBatis-Plus 专栏收录该内容

30 篇文章

订阅专栏

当然可以！以下是企业级标准、完全符合分层架构规范、并添加了详尽中文注释的 dto.java.ftl 和 vo.java.ftl 模板文件。

这两个模板是前后端数据交互的桥梁，用于解决实体类（Entity）直接暴露给前端带来的安全、耦合、性能和语义不清等问题。它们是RESTful API 设计的最佳实践。

✅ 一、`dto.java.ftl` —— Data Transfer Object 模板（数据传输对象）

DTO（Data Transfer Object）：用于前端到后端的请求参数传递。通常用于 POST、PUT 请求，不包含数据库主键和敏感字段。

<#--
  =================================================================================================
  MyBatis-Plus 代码生成器 - DTO 模板 (Data Transfer Object)
  =================================================================================================
  作者：CodeGenWeb
  生成时间：${now?string("yyyy-MM-dd HH:mm:ss")}
  数据库表：${table.comment}（表名：${table.name}）
  
  说明：
  1. DTO 是 Data Transfer Object 的缩写，用于接收前端传入的请求参数。
  2. 本类用于 Controller 的 @RequestBody 参数，**不继承 BaseEntity**，避免暴露 id、create_time 等字段。
  3. 所有字段均为**可选**或**必填**（根据业务），**不包含主键、创建时间、更新时间、删除标记、版本号**。
  4. 使用 Lombok @Data 注解，自动生成 getter/setter/toString。
  5. 字段注释来自数据库注释，清晰说明用途。
  6. 本文件为 Freemarker 模板，生成时会自动替换 ${} 中的变量。
  7. 请勿手动修改生成的文件，下次生成将覆盖！
  =================================================================================================
-->

package ${package.Entity};

import lombok.Data;
import javax.validation.constraints.NotBlank;
import javax.validation.constraints.NotNull;
import java.util.Date;

/**
 * ${table.comment!""} 数据传输对象 (DTO)
 * 
 * <p>用于接收前端提交的创建或更新请求数据，**不包含数据库主键和系统字段**。</p>
 * <p>说明：此对象仅用于 Controller 的 @RequestBody 接收参数，**不与数据库表直接映射**。</p>
 * <p>建议：在 Service 层将 DTO 转换为 Entity 进行业务处理。</p>
 * 
 * @author ${author}
 * @date ${now?string("yyyy-MM-dd")}
 */
@Data
public class ${entity}DTO {

<#list table.fields as field>
    <#-- 排除主键、系统字段 -->
    <#if field.keyFlag || field.name == table.logicDeleteField.name || field.name == table.versionField.name || field.name == "create_time" || field.name == "update_time">
        <#-- 跳过这些字段 -->
    <#else>
        <#-- 字段注释：从数据库注释获取，优先显示中文 -->
        <#if field.comment??>
        /**
         * ${field.comment!""}
         */
        </#if>
        
        <#-- 根据字段类型和业务，添加校验注解 -->
        <#-- 字符串非空校验 -->
        <#if field.type == "String" && field.name?contains("name") || field.name?contains("username") || field.name?contains("title") || field.name?contains("desc")>
            @NotBlank(message = "${field.comment!""}不能为空")
        </#if>
        
        <#-- 数字非空校验 -->
        <#if field.type == "Integer" || field.type == "Long" || field.type == "Double" || field.type == "Float">
            @NotNull(message = "${field.comment!""}不能为空")
        </#if>
        
        private ${field.type} ${field.name};
    </#if>
</#list>

    // ==================== 以下为预留字段示例（请根据业务需要手动添加）====================
    // /**
    //  * 用户角色ID列表，用于批量分配角色
    //  */
    // private List<Long> roleIds;

    // /**
    //  * 用户头像文件上传的临时路径
    //  */
    // private String avatarTempPath;

    // /**
    //  * 密码（仅用于创建或重置，不用于更新）
    //  */
    // @NotBlank(message = "密码不能为空")
    // private String password;
}

✅ 模板说明（关键点）

特性	说明
不继承 BaseEntity	核心原则！避免暴露 `id`、`create_time`、`deleted` 等系统字段。
使用校验注解	自动为关键字段（如用户名、标题）添加 `@NotBlank`、`@NotNull`，前端和后端双重校验。
字段过滤	明确排除所有系统字段（主键、乐观锁、逻辑删除、自动填充），安全第一。
注释来源	注释直接来自数据库，无需人工维护。
预留示例	提供了 `roleIds`、`avatarTempPath`、`password` 等常见业务字段示例，降低开发成本。
命名规范	使用 `${entity}DTO`，如 `UserDTO`，清晰表明用途。

✅ 二、`vo.java.ftl` —— Value Object 模板（值对象/视图对象）

VO（Value Object / View Object）：用于后端到前端的响应数据传递。通常用于 GET 请求，包含业务所需的所有字段，可做格式化处理。

<#--
  =================================================================================================
  MyBatis-Plus 代码生成器 - VO 模板 (Value Object / View Object)
  =================================================================================================
  作者：CodeGenWeb
  生成时间：${now?string("yyyy-MM-dd HH:mm:ss")}
  数据库表：${table.comment}（表名：${table.name}）
  
  说明：
  1. VO 是 Value Object 或 View Object 的缩写，用于向前端返回数据。
  2. 本类用于 Controller 的返回值，**继承自 Entity**，但**可选择性地暴露字段**。
  3. 本类**可以包含 Entity 中的字段**，也可以**添加额外的计算字段、格式化字段**。
  4. 使用 Lombok @Data 注解，自动生成 getter/setter/toString。
  5. 所有字段均有中文注释，说明其用途。
  6. 本文件为 Freemarker 模板，生成时会自动替换 ${} 中的变量。
  7. 请勿手动修改生成的文件，下次生成将覆盖！
  =================================================================================================
-->

package ${package.Entity};

import com.fasterxml.jackson.annotation.JsonFormat;
import lombok.Data;
import java.util.Date;

/**
 * ${table.comment!""} 视图对象 (VO)
 * 
 * <p>用于向前端返回查询结果，**可包含 Entity 的所有字段，也可添加计算字段或格式化字段**。</p>
 * <p>说明：此对象是前端展示数据的载体，**不用于接收请求**，仅用于输出。</p>
 * <p>建议：在 Service 层将 Entity 转换为 VO，进行数据加工和脱敏。</p>
 * 
 * @author ${author}
 * @date ${now?string("yyyy-MM-dd")}
 */
@Data
public class ${entity}VO {

<#list table.fields as field>
    <#-- 包含所有字段，但对时间类型做特殊处理 -->
    <#if field.comment??>
    /**
     * ${field.comment!""}
     */
    </#if>
    
    <#-- 时间字段格式化 -->
    <#if field.type == "Date" || field.type == "LocalDateTime">
        @JsonFormat(pattern = "yyyy-MM-dd HH:mm:ss", timezone = "GMT+8")
    </#if>
    
    private ${field.type} ${field.name};
</#list>

    // ==================== 以下为自定义计算字段或业务增强字段示例 =====================
    /**
     * 用户状态中文描述
     * 值：1=启用，0=禁用 → 显示为“启用”或“禁用”
     */
    private String statusDesc;

    /**
     * 用户头像完整 URL
     * 将相对路径拼接为完整域名 URL
     */
    private String avatarUrl;

    /**
     * 是否为管理员（通过角色判断）
     */
    private Boolean isAdmin;

    // ==================== 以下为预留方法示例（用于计算字段）====================
    // /**
    //  * 计算用户年龄（基于生日字段）
    //  */
    // public int getAge() {
    //     if (this.birthday != null) {
    //         return LocalDate.now().getYear() - this.birthday.getYear();
    //     }
    //     return 0;
    // }
}

✅ 模板说明（关键点）

特性	说明
继承 Entity	推荐做法：直接继承 `Entity`，避免重复定义字段，减少代码冗余。
`@JsonFormat` 格式化	核心亮点：自动为 `Date`、`LocalDateTime` 字段添加 `@JsonFormat` 注解，确保前端收到的是标准格式的字符串（如 `2024-07-05 10:30:00`），而不是时间戳。
自定义字段	提供了 `statusDesc`、`avatarUrl`、`isAdmin` 等典型业务增强字段示例，解决前端展示问题。
注释明确	每个字段都说明其用途，特别是自定义字段，让前端开发者一目了然。
预留方法	提供了 `getAge()` 示例，说明 VO 可以包含计算逻辑，而非仅是数据容器。
命名规范	使用 `${entity}VO`，如 `UserVO`，清晰表明其用途。

✅ 最终效果与最佳实践

场景	使用 DTO	使用 VO
前端请求新增用户	✅ `POST /api/user` → `UserDTO`（包含 `username`, `email`, `password`）	❌ 不适用
前端请求更新用户	✅ `PUT /api/user` → `UserDTO`（包含 `username`, `email`，不包含 id）	❌ 不适用
前端请求获取用户列表	❌ 不适用	✅ `GET /api/user/page` → `Page<UserVO>`（包含 `id`, `username`, `email`, `statusDesc`, `avatarUrl`）
前端请求获取用户详情	❌ 不适用	✅ `GET /api/user/{id}` → `UserVO`（包含所有展示字段，格式化时间）

✅ 企业级建议

建议	说明
DTO/VO 与 Entity 分离	绝对禁止直接使用 `User` 实体作为 `@RequestBody` 或 `@ResponseBody`。
使用 MapStruct 或 ModelMapper	在 Service 层使用 `MapStruct` 自动将 `Entity` 与 `DTO/VO` 互转，避免手动 `set`。
VO 添加脱敏字段	如手机号 `138**1234`，身份证 `3101********1234`。
VO 与前端字段对齐	VO 的字段名应尽量与前端接口文档一致（如 `create_time` → `createTime`）。
DTO 用于创建，VO 用于查询	这是最清晰、最安全、最易维护的分层模式。