关于分页数据结构的设计

2.1 双轨制的本质：将运行时状态提升为编译时类型

"是否分页"本质上是运行时状态——用户在页面上选择"显示全部"还是"分页显示"，是一个运行时的交互决策。传统方案却将其提升到编译时类型层面，用两种不同的返回类型来表达一个运行时选择。

2.2 降级的深层意义：从类型决策到参数配置

结构对比

public class Page<T> {
  private List<T> records;
  private int pageNum;
  private int pageSize;
  private long total;
}

// 非分页场景：类型完全不同
public class UserController {
  // 路径 A：分页
  Page<User> listUsers(PageParam p);
  // 路径 B：不分页
  List<User> allUsers();
}

public class DataSet {
  private List<DataRow> rows;
  private Integer pageSize;  // null 或 -1 表示不分页
  private Integer pageNum;
  private long totalRow;
}

// 统一结构：一种类型应对所有场景
public class UserController {
  // 唯一路径：分页与否由参数决定
  DataSet listUsers(QueryParam q);
}

3.1 信息单向坍缩：传统方案的不可逆损失

当传统方案选择返回 List 而非 Page 时，totalRow、pageSize 等分页元数据被彻底丢弃。这不是"暂时不用"，而是不可逆的信息损失——即便数据库已经计算出 total，这些信息在类型转换的瞬间灰飞烟灭。

3.2 DataSet 的信息守恒

DataSet 始终保留全部信息。当不需要分页时，pageSize = -1 表示"无限制"，而非"不存在"。totalRow 始终有效，随时可以切换为分页模式。

3.3 对下游消费者的实际影响

4.1 组合爆炸：传统 DAO 层的噩梦

传统方案中，每支持一种新数据库，DAO 层就需要新增对应的分页 SQL 方言。当存在 N 种数据库和 2 种查询模式（分页 / 非分页）时，路径数为 N × 2。MySQL 的 LIMIT、Oracle 的 ROWNUM、SQL Server 的 OFFSET FETCH、达梦的 LIMIT……每一种都需要手写、测试和维护。

4.2 方言引擎：内置 200+ SQL 转换规则

DataSet 方案内置方言引擎，包含 200+ SQL 转换规则，自动适配各类数据库的分页语法。开发者只需写一次查询，方言引擎在运行时自动将其转换为目标数据库的等效 SQL。

4.3 信创迁移与多数据源场景的实际价值

5.1 不只是"带分页的 List"

DataSet 的设计目标远不止"一个带分页信息的列表"。它是一个具备自治能力的数据容器——数据加载后，容器自身就能完成查询、过滤、聚合、格式转换等操作，无需将数据倒腾到外部工具中处理。

5.2 内聚设计的三个维度

5.3 自治性带来的架构收益

当数据容器具备自治能力时，数据与其处理逻辑之间的隐性耦合被消除。传统方案中，"拿到 List 后再用 Stream 过滤"意味着数据处理逻辑散落在各个 Service 方法中；DataSet 方案将这些能力内聚到容器自身，处理逻辑统一、可复用、可测试。