TugboatAIRebuild/.trae/skills/common-query-dto-base-class/SKILL.md

通用查询DTO基类设计技能

技能描述

创建通用的查询DTO基类，封装常用的分页和排序属性，便于后续创建的表单复用。

设计原则

1. 继承架构

• 创建BaseQueryDTO作为所有查询DTO的基类
• 封装通用的分页和排序属性
• 子类继承基类并添加特定业务属性

2. 通用属性

• page: 页码，默认为1
• pageSize: 每页大小，默认为20
• sortBy: 排序列名
• sortOrder: 排序方向（ASC/DESC）

3. 验证机制

• 在setSortOrder方法中验证排序方向的有效性
• 只允许ASC或DESC两种排序方式（忽略大小写）

实现模式

BaseQueryDTO基类

public class BaseQueryDTO {
    private Integer page = 1;    // 页码，默认第一页
    private Integer pageSize = 20; // 每页大小，默认20条
    private String sortBy;  // 排序列名
    private String sortOrder;  // 排序方向，ASC或DESC
    
    // 相应的getter和setter方法
}

业务DTO类

public class BusinessQueryDTO extends BaseQueryDTO {
    // 业务特定的属性
    private String businessField;
    
    // 业务特定的getter和setter方法
}

优势

1. 代码复用: 避免在每个查询DTO中重复编写相同的分页和排序属性
2. 维护性: 统一管理分页和排序相关的代码变更
3. 一致性: 确保所有查询接口使用相同的标准分页和排序参数
4. 扩展性: 便于在未来向所有查询DTO添加通用功能

注意事项

1. 向后兼容: 确保API接口参数名称保持不变
2. 验证逻辑: 在基类中统一处理参数验证
3. 文档更新: 更新API文档以反映新的继承关系
4. 测试覆盖: 确保继承基类的子类仍能正常工作

使用场景

• 创建新的查询DTO时，优先考虑继承BaseQueryDTO
• 当多个DTO需要相同的分页和排序功能时
• 当需要标准化查询接口的分页参数时