Shipeng.Data.Hybrid 4.1.0

.NET 10.0 This package targets .NET 10.0. The package is compatible with this framework or higher.
There is a newer version of this package available.
See the version list below for details. 
dotnet add package Shipeng.Data.Hybrid --version 4.1.0
                    


                    

                
NuGet\Install-Package Shipeng.Data.Hybrid -Version 4.1.0
This command is intended to be used within the Package Manager Console in Visual Studio, as it uses the NuGet module's version of Install-Package. 
<PackageReference Include="Shipeng.Data.Hybrid" Version="4.1.0" />
For projects that support PackageReference, copy this XML node into the project file to reference the package. 
<PackageVersion Include="Shipeng.Data.Hybrid" Version="4.1.0" />
                    


                            Directory.Packages.props
                        

                    

                
<PackageReference Include="Shipeng.Data.Hybrid" />
                    


                            Project file
For projects that support Central Package Management (CPM), copy this XML node into the solution Directory.Packages.props file to version the package. 
paket add Shipeng.Data.Hybrid --version 4.1.0
                    


                    

                
#r "nuget: Shipeng.Data.Hybrid, 4.1.0"
#r directive can be used in F# Interactive and Polyglot Notebooks. Copy this into the interactive tool or source code of the script to reference the package. 
#:package Shipeng.Data.Hybrid@4.1.0
#:package directive can be used in C# file-based apps starting in .NET 10 preview 4. Copy this into a .cs file before any lines of code to reference the package. 
#addin nuget:?package=Shipeng.Data.Hybrid&version=4.1.0
                    


                            Install as a Cake Addin
                        

                    

                
#tool nuget:?package=Shipeng.Data.Hybrid&version=4.1.0
                    


                            Install as a Cake Tool

Shipeng.Data.Hybrid

Shipeng.Data.Hybrid 提供 MongoDB 与 SqlSugar 混合分页查询辅助能力，适合“优先读 MongoDB 读模型，不足时回源 SQL 数据”的场景。它把混合分页从 Foundation 中拆出来，避免普通项目无意引用 MongoDB、SqlSugar 和 Mapster。

安装

dotnet add package Shipeng.Data.Hybrid

适用场景

  • 列表页优先从 MongoDB 读取聚合后的读模型。
  • MongoDB 数据不完整时，需要按页从关系数据库补齐。
  • 查询结果需要 DTO 映射，且项目已经使用 Mapster。
  • 审计、轨迹、订单列表、报表预聚合等读多写少场景。

主要类型

  • HybridPageQueryHelper：混合分页查询入口，先查询 MongoDB 读模型；当 MongoDB 没有匹配数据时，再回退查询 SqlSugar 关系库。
  • QueryPagedAsync<TEntity>：返回实体分页结果，适合 MongoDB 与 SQL 使用同一实体模型的列表。
  • QueryPagedAsync<TEntity, TDto>：返回 DTO 分页结果，查询后通过 Mapster 将实体映射为 DTO。

基本用法

using Shipeng.Foundation.Data.Hybrid;
using MongoDB.Driver;

var result = await HybridPageQueryHelper.QueryPagedAsync<OrderEntity, OrderListDto>(
    mongoRepository,
    sqlRepository,
    mongoCollectionName: "orders_read_model",
    where: order => order.TenantId == tenantId && order.CreatedTime >= beginTime,
    currentPage: pageIndex,
    pageSize: pageSize,
    mongoSort: Builders<OrderEntity>.Sort.Descending(order => order.CreatedTime),
    sqlOrderBy: query => query.OrderByDescending(order => order.CreatedTime),
    afterMapAsync: async rows =>
    {
        await dictionaryService.FillDisplayTextAsync(rows);
    });

只需要实体结果时：

var page = await HybridPageQueryHelper.QueryPagedAsync<OrderEntity>(
    mongoRepository,
    sqlRepository,
    "orders_read_model",
    order => order.Status == OrderStatus.Paid,
    currentPage: 1,
    pageSize: 20);

使用建议

  • 混合分页必须先设计清楚排序字段，否则 MongoDB 和 SQL 的结果合并会出现顺序不稳定。
  • MongoDB 读模型应包含列表页所需字段，避免分页后再大量回表。
  • 当前实现不是“同一页 MongoDB 不足再用 SQL 补齐”的合并模式；只要 MongoDB 有匹配数据，就直接返回 MongoDB 结果。只有 MongoDB 匹配总数为 0 时才回源 SQL。
  • SQL 回源只用于读模型缺失或尚未同步时兜底，不应成为每次查询的主路径。
  • DTO 映射规则建议集中配置在 Shipeng.Mapster，避免每个查询重复写转换代码。
  • currentPage 小于 1 时会按 1 处理，pageSize 小于 1 时会按 20 处理。
  • where 表达式会同时用于 MongoDB 和 SqlSugar，编写条件时应避免使用某一侧无法翻译的方法调用。

引用关系

本包引用 Shipeng.Foundation、Shipeng.Data.MongoDB、Shipeng.Data.SqlSugar 和 Shipeng.Mapster。如果项目只使用单一数据库，请优先引用单独的数据访问包。

API Reference / API 索引

完整公开类型、方法、属性签名请查看 API_REFERENCE.md。该文件从源码 public 声明生成，用于补充 README 中的场景说明和示例。

Product Compatible and additional computed target framework versions.
.NET net10.0 is compatible.  net10.0-android was computed.  net10.0-browser was computed.  net10.0-ios was computed.  net10.0-maccatalyst was computed.  net10.0-macos was computed.  net10.0-tvos was computed.  net10.0-windows was computed. 
Compatible target framework(s)
Included target framework(s) (in package)
Learn more about Target Frameworks and .NET Standard.

NuGet packages

This package is not used by any NuGet packages.

GitHub repositories

This package is not used by any popular GitHub repositories.

Version Downloads Last Updated
4.1.1 91 6/30/2026
4.1.0 92 6/30/2026

4.1.0: Split the original monolithic foundation library into focused Shipeng.* NuGet packages. Consumers can reference authentication, MongoDB, SqlSugar, EF Core, database index, third-party integration, logging, mapping, payment, and hybrid paging capabilities on demand.