DTO 与 Converter

为分层架构项目创建规范的 DTO（数据传输对象）和 MapStruct Converter（对象转换器）。

DTO 命名体系

请求 DTO

用途	命名	示例
创建	{Resource}CreateReq	PolicyCreateReq
更新	{Resource}UpdateReq	PolicyUpdateReq
分页查询	{Resource}PageReq	PolicyPageReq
批量操作	{Resource}BatchReq	TaskBatchReq

响应 DTO

用途	命名	示例
列表卡片	{Resource}Card	PolicyCard
详情	{Resource}Detail	PolicyDetail
通用响应	{Resource}Resp	VideoSourceResp
批量结果	{Resource}BatchResp	TaskBatchResp

通用 DTO

类	用途
IdResp	创建操作返回 ID
PageReq	分页请求基类 (page, size)
PageResult<T>	偏移分页结果 (records, total, page, size)
CursorPageResult<T>	游标分页结果 (records, nextCursor, hasMore, count)

@Data
@Schema(description = "分页请求基类")
public class PageReq {
    @Schema(description = "页码", example = "1")
    @Min(value = 1, message = "页码不能小于1")
    private Integer page = 1;

    @Schema(description = "每页大小", example = "20")
    @Range(min = 1, max = 100, message = "每页大小需在1-100之间")
    private Integer size = 20;
}

@Data
@Schema(description = "创建操作返回ID")
public class IdResp {
    @Schema(description = "资源ID")
    private Long id;

    public IdResp(Long id) { this.id = id; }
}

包组织

DTO 按业务模块分子目录：

dto/
├── policy/
│   ├── PolicyCreateReq.java
│   ├── PolicyUpdateReq.java
│   ├── PolicyCard.java
│   └── PolicyDetail.java
├── task/
│   ├── AnalysisTaskCreateReq.java
│   └── ...
├── ApiResponse.java
├── IdResp.java
├── PageReq.java
├── PageResult.java
└── CursorPageResult.java

DTO 注解规范

请求 DTO 模板

@Data
@Schema(description = "策略创建请求")
public class PolicyCreateReq {

    @Schema(description = "策略名称", example = "火灾预警策略")
    @NotBlank(message = "策略名称不能为空")
    private String name;

    @Schema(description = "策略描述")
    private String description;

    @Schema(description = "告警等级")
    @NotNull(message = "告警等级不能为空")
    private AlertLevelEnum alertLevel;

    @Schema(description = "关联设备ID列表")
    @NotEmpty(message = "设备ID列表不能为空")
    private List<String> deviceIds;
}

更新 DTO 模板

更新 DTO 与创建 DTO 的区别：字段通常全部可选（仅传入需要修改的字段），不加 @NotBlank 等必填校验。

@Data
@Schema(description = "策略更新请求")
public class PolicyUpdateReq {

    @Schema(description = "策略名称", example = "火灾预警策略V2")
    private String name;

    @Schema(description = "策略描述")
    private String description;

    @Schema(description = "告警等级")
    private AlertLevelEnum alertLevel;

    @Schema(description = "关联设备ID列表")
    private List<String> deviceIds;
}

设计策略: 若业务要求全量更新（每次提交完整数据），则 UpdateReq 可加必填校验，与 CreateReq 类似。

响应 DTO 模板

@Data
@Schema(description = "策略卡片")
public class PolicyCard {

    @Schema(description = "策略ID")
    private Long id;

    @Schema(description = "策略名称")
    private String name;

    @Schema(description = "是否启用")
    private Boolean enabled;

    @Schema(description = "告警等级")
    private AlertLevelEnum alertLevel;

    @Schema(description = "创建时间")
    @JsonFormat(pattern = "yyyy-MM-dd HH:mm:ss")
    private LocalDateTime createTime;
}

详情继承卡片

@Data
@EqualsAndHashCode(callSuper = true)
@ToString(callSuper = true)
@Schema(description = "策略详情")
public class PolicyDetail extends PolicyCard {

    @Schema(description = "策略描述")
    private String description;

    @Schema(description = "时间计划列表")
    private List<TimePlanResp> timePlans;

    @Schema(description = "更新时间")
    @JsonFormat(pattern = "yyyy-MM-dd HH:mm:ss")
    private LocalDateTime updateTime;
}

继承场景必须: @EqualsAndHashCode(callSuper = true) + @ToString(callSuper = true)，否则父类字段不参与 equals/toString。

分页请求继承基类

@Data
@EqualsAndHashCode(callSuper = true)
@Schema(description = "策略分页查询请求")
public class PolicyPageReq extends PageReq {

    @Schema(description = "策略名称（模糊查询）")
    private String name;

    @Schema(description = "告警等级列表（多选）")
    private List<AlertLevelEnum> alertLevels;

    @Schema(description = "开始时间")
    @DateTimeFormat(pattern = "yyyy-MM-dd HH:mm:ss")
    private LocalDateTime startTime;
}

常用注解速查

注解	用途	示例
@Schema(description, example)	OpenAPI 字段说明	@Schema(description = "用户名", example = "张三")
@NotBlank	字符串非空	必填 String 字段
@NotNull	非 null	必填枚举/对象字段
@NotEmpty	集合非空	必填 List 字段
@JsonFormat(pattern)	JSON 日期格式	"yyyy-MM-dd HH:mm:ss"
@JsonProperty	JSON 字段名	@JsonProperty("sourceId")
@DateTimeFormat(pattern)	查询参数日期解析	GET 请求的日期参数

枚举序列化

DTO 中使用枚举类型时，需明确 JSON 序列化/反序列化策略：

@Getter
@AllArgsConstructor
public enum AlertLevelEnum {
    HIGH("high", "高"),
    MEDIUM("medium", "中"),
    LOW("low", "低");

    @JsonValue   // 序列化时输出 value 值（如 "high"）
    private final String value;

    private final String label;

    @JsonCreator // 反序列化时按 value 匹配
    public static AlertLevelEnum fromValue(String value) {
        for (AlertLevelEnum e : values()) {
            if (e.value.equals(value)) return e;
        }
        throw new IllegalArgumentException("未知告警等级: " + value);
    }
}

注解	用途
@JsonValue	控制枚举序列化输出（推荐使用业务值而非 name/ordinal）
@JsonCreator	控制枚举反序列化匹配逻辑

MapStruct Converter

统一配置（推荐）

所有 Converter 共享的配置，自动忽略未映射字段，无需逐个 @Mapping(ignore=true)：

@MapperConfig(
    componentModel = "spring",
    unmappedTargetPolicy = ReportingPolicy.IGNORE,
    unmappedSourcePolicy = ReportingPolicy.IGNORE
)
public interface ConverterConfig {
}

推荐策略: 优先使用 config = ConverterConfig.class（简洁、统一）。仅在需要显式控制映射关系（如字段名不同、常量赋值）时才使用 @Mapping。

Converter 接口模板

@Mapper(config = ConverterConfig.class)
public interface PolicyConverter {

    // Entity → DTO
    PolicyCard toCard(AlertPolicy entity);
    PolicyDetail toDetail(AlertPolicy entity);
    List<PolicyCard> toCards(List<AlertPolicy> entities);

    // 创建: DTO → Entity
    AlertPolicy toEntity(PolicyCreateReq req);

    // 更新: DTO 合并到已有 Entity（仅覆盖非 null 字段）
    @BeanMapping(nullValuePropertyMappingStrategy = NullValuePropertyMappingStrategy.IGNORE)
    void updateEntity(PolicyUpdateReq req, @MappingTarget AlertPolicy entity);
}

不使用 ConverterConfig 的写法: 将 @Mapper(config = ConverterConfig.class) 替换为 @Mapper(componentModel = "spring")，并手动添加 @Mapping(target = "id", ignore = true) 等忽略注解。

方法命名规范

方法	用途
toEntity(Req)	请求 DTO → 新 Entity（创建）
updateEntity(Req, @MappingTarget Entity)	请求 DTO 合并到已有 Entity（更新）
toCard(Entity)	Entity → 列表卡片 DTO
toDetail(Entity)	Entity → 详情 DTO
toResp(Entity)	Entity → 通用响应 DTO
toCards(List)	批量转换

字段映射

// 忽略字段
@Mapping(target = "id", ignore = true)

// 字段名不同
@Mapping(source = "sort", target = "sortOrder")

// 常量值
@Mapping(target = "status", constant = "DISABLED")

// 表达式
@Mapping(target = "syncTime", expression = "java(java.time.LocalDateTime.now())")

// 嵌套属性
@Mapping(target = "typeName", source = "entity.modelType.label")

后处理 (@AfterMapping)

用于 MapStruct 自动映射后的补充逻辑（组装显示名称、计算派生字段等）：

@AfterMapping
default void enrichCard(AlertPolicy entity, @MappingTarget PolicyCard card) {
    // 组装显示名称
    card.setDisplayName(entity.getName() + " (" + entity.getAlertLevel().getLabel() + ")");
}

@AfterMapping
default void setDefaultValues(@MappingTarget AlertPolicy entity) {
    if (entity.getEnabled() == null) entity.setEnabled(false);
    if (entity.getStatus() == null) entity.setStatus(PolicyStatusEnum.DISABLED);
}

null 值处理: 简单的 null → 默认值场景优先使用 @BeanMapping(nullValuePropertyMappingStrategy) 或 ConverterConfig 级别配置，@AfterMapping 保留给需要自定义逻辑的场景。

自定义转换 (default 方法)

用于枚举、时间戳等需要逻辑的转换：

@Mapper(config = ConverterConfig.class)
public interface AlertConverter {

    AlertCard toCard(AlertRecord entity);

    // 自定义时间戳转换（MapStruct 自动调用匹配的类型转换方法）
    default LocalDateTime timestampToLocalDateTime(long timestamp) {
        if (timestamp == 0) return null;
        return LocalDateTime.ofInstant(
            Instant.ofEpochSecond(timestamp),
            ZoneId.systemDefault()
        );
    }

    // 自定义枚举转换
    default OnlineStatus convertOnlineStatus(String videoUrlStatus) {
        return OnlineStatus.fromVideoUrlStatus(videoUrlStatus);
    }
}

组合 Converter (uses)

当 Entity 含有嵌套对象需要转换时，使用 uses 引入其他 Converter：

@Mapper(config = ConverterConfig.class, uses = {TimePlanConverter.class})
public interface PolicyConverter {
    // MapStruct 自动调用 TimePlanConverter 转换嵌套的 TimePlan → TimePlanResp
    PolicyDetail toDetail(AlertPolicy entity);
}

@Mapper(config = ConverterConfig.class)
public interface TimePlanConverter {
    TimePlanResp toResp(TimePlan entity);
    List<TimePlanResp> toResps(List<TimePlan> entities);
}

必须忽略的字段

当 DTO → Entity 转换时，以下字段必须 ignore（由框架自动填充）：

字段	原因
id	数据库自增
deleted	默认值 0
createTime / updateTime	MetaObjectHandler 自动填充
createUser / updateUser	MetaObjectHandler 自动填充
versionNum	默认值 1

当 Entity → DTO 转换时，以下字段由 Facade 层填充，Converter 应 ignore：

• 关联数据字段（如 agentNames, regionPath, deviceGroups）
• 计算字段（如 sourceCount, taskCount）
• URL 转换字段（如存储路径 → 下载链接）