Shipeng.Data.Hybrid 4.1.1

.NET 10.0

dotnet add package Shipeng.Data.Hybrid --version 4.1.1

NuGet\Install-Package Shipeng.Data.Hybrid -Version 4.1.1

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.1" />

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.1" />
                    

                            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.1

The NuGet Team does not provide support for this client. Please contact its maintainers for support.

#r "nuget: Shipeng.Data.Hybrid, 4.1.1"

#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.1

#: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.1
                    

                            Install as a Cake Addin

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

                            Install as a Cake Tool

The NuGet Team does not provide support for this client. Please contact its maintainers for support.

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 索引

nuget.org 当前只会直接渲染包的 README 和 Release Notes，不会把包内 docs/API_REFERENCE.md 自动显示成一个独立页面标签。完整公开 API 索引已经随 NuGet 包打入 docs/API_REFERENCE.md，也可以在源码仓库中查看。

如果你正在 NuGet 页面阅读本文，请优先看本 README 的“主要类型”和示例；下载包后可在包内容中打开 docs/API_REFERENCE.md 查看完整公开类型、方法、属性和构造函数签名。

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.

net10.0
- Mapster (>= 10.0.10)
- MongoDB.Driver (>= 3.9.0)
- Shipeng.Data.MongoDB (>= 4.1.1)
- Shipeng.Data.SqlSugar (>= 4.1.1)
- Shipeng.Foundation (>= 4.1.1)
- Shipeng.Mapster (>= 4.1.1)
- SqlSugarCore (>= 5.1.4.215)

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	86	6/30/2026
4.1.0	89	6/30/2026

4.1.1 / 2026-06-30

English:
- Split the original monolithic foundation library into focused Shipeng.* NuGet packages so applications can reference only the capabilities they actually need.
- Added Shipeng.DatabaseMaintenance for SQL Server and MongoDB database maintenance. It supports non-destructive cleanup preview, SqlSugar entity scanning, MongoDB collection scanning from configuration or source declarations, keep lists, ignored prefixes, empty-scan protection, missing table preview, controlled SqlSugar CodeFirst table creation, SQL Server schema difference preview, safe missing-column creation, safe changed-column synchronization, explicit execution switches, and confirmation-code protected destructive/schema-changing execution.
- Improved Shipeng.Payment with a unified payment abstraction for WeChat, Alipay, UnionPay, Cloud QuickPass, bank gateways, and profit-sharing scenarios. WeChat Pay V3 remains the concrete built-in implementation; other channels expose stable provider contracts and explicit placeholders so applications can add real vendor SDK implementations without changing business code.
- Centralized common NuGet metadata in Directory.Build.props: target framework, version, authors, repository, license, README, XML documentation, warning policy, and release notes.
- Every package includes README.md, XML IntelliSense documentation, and docs/API_REFERENCE.md inside the generated nupkg.
- Updated README files to explain that nuget.org renders README and Release Notes directly but does not expose packaged docs/API_REFERENCE.md as a separate page tab.
- Release build validation: all projects build and pack successfully for net10.0 with 0 warnings and 0 errors.

中文：
- 将早期单体基础库拆分为职责更清晰的 Shipeng.* NuGet 包，业务项目可以按需引用认证、MongoDB、SqlSugar、EF Core、数据库索引、数据库维护、第三方集成、日志、映射、支付和混合分页能力。
- 新增 Shipeng.DatabaseMaintenance，用于 SQL Server 和 MongoDB 数据库维护。支持冗余表/集合预览清理、SqlSugar 实体扫描、MongoDB 配置集合扫描、源码集合声明扫描、保留名单、忽略前缀、空扫描保护、缺失表预览、受控 CodeFirst 自动建表、SQL Server 结构差异预览、缺失字段补齐、安全字段同步、显式执行开关和确认码保护。
- 增强 Shipeng.Payment，新增统一支付抽象，覆盖微信、支付宝、银联、云闪付、银行网关和分账场景。微信支付 V3 是当前内置可用实现；其他通道提供稳定 Provider 契约和明确占位实现，方便业务项目接入真实厂商 SDK。
- 将公共 NuGet 元数据统一集中到 Directory.Build.props，避免各项目 PropertyGroup 重复和不一致。
- 每个包都打入 README.md、XML IntelliSense 文档和 docs/API_REFERENCE.md。
- 所有 README 都补充说明：nuget.org 会直接显示 README 和 Release Notes，但不会把包内 docs/API_REFERENCE.md 自动显示为独立标签页。
- 已验证 Release 构建和打包，目标框架 net10.0，0 警告，0 错误。