分页响应必须在JSON体中包含TotalCount字段，推荐使用泛型PagedResponse类封装；需用CountAsync()单独查总数，避免Skip().Take()遗漏；应封装PagingOptions统一校验；大数据量时优先游标分页。
分页返回必须带 TotalCount 字段，不能只靠响应头或额外接口
WebAPI 分页的常见误区是把总条数藏在 Content-Range 响应头里，或者要求前端再发一次 GET /api/items/count。这两种方式在真实项目中都容易出问题：前者前端解析成本高、不统一；后者增加请求次数、并发时数据可能不一致。C# WebAPI（尤其 ASP.NET Core）推荐直接在 JSON 响应体里返回结构化分页对象。
正确做法是定义一个泛型分页响应类，比如：
public class PagedResponse<T>
{
public List<T> Items { get; set; } = new();
public int TotalCount { get; set; }
public int PageNumber { get; set; }
public int PageSize { get; set; }
}后端 Controller 返回这个类型，前端拿到的就是开箱即用的 TotalCount 和当前页数据，不需要拼接逻辑。
IQueryable<t>.Skip().Take()</t> 是基础，但必须配合 CountAsync() 才能拿到总数
很多人以为 Skip().Take() 能自动算总数，其实不能——它只生成 LIMIT/OFFSET SQL，不触发 COUNT 查询。漏掉总数统计会导致 TotalCount 为 0 或硬编码值，分页控件直接失效。
实操建议：
- 用
await query.CountAsync()单独查总数，不要用query.ToList().Count，后者会把全量数据拉到内存 - 总数查询和分页查询尽量复用同一个
IQueryable基础（比如过滤条件一致），否则前后数据口径不一致 - 如果查询本身含复杂 Join 或 GroupBy，
Count()可能比主查询还慢，这时要考虑缓存总数或改用游标分页
示例片段：
var totalCount = await context.Orders.CountAsync(x => x.Status == "Active");<br>var items = await context.Orders<br> .Where(x => x.Status == "Active")<br> .Skip((pageNumber - 1) * pageSize)<br> .Take(pageSize)<br> .ToListAsync();
ASP.NET Core 中避免手动解析 page 和 pageSize 查询参数
手写 [FromQuery] int page = 1, [FromQuery] int pageSize = 20 看似简单，但容易忽略边界校验和默认值一致性。更麻烦的是，不同接口重复写这套逻辑，后期改分页规则（比如全局限制 pageSize ≤ 100）就得逐个改。
推荐方案：
- 封装一个
PagingOptions模型，加[ModelBinder]或使用AddMvcOptions(x => x.ModelBinderProviders.Insert(0, new PagingModelBinderProvider())) - 在模型里做默认值和范围约束：
[Range(1, 100)] public int PageSize { get; set; } = 20; - Controller 方法签名直接接收
PagingOptions paging，干净且可复用
这样连错误响应都统一：当传入 pageSize=500，框架自动返回 400 并带验证失败信息，不用自己 if (pageSize > 100) throw...。
EF Core 分页性能陷阱：OFFSET 越大越慢，10 万行后 Skip(10000) 可能卡住
SQL Server/PostgreSQL 的 OFFSET 在大数据量下本质是“跳过前 N 行再取”，不是随机访问。Skip 值越大，数据库扫描越多，甚至可能放弃索引走全表扫描。
应对策略取决于场景：
- 如果只是管理后台、数据量稳定在 10 万以内，
Skip()/Take()足够，加好CreatedTime等排序字段的索引就行 - 如果是用户高频翻页的列表（比如商品、订单），且总量超 50 万，优先考虑游标分页（
WHERE id > @lastId ORDER BY id LIMIT 20），用id或时间戳做游标 - 不要为了“支持任意跳页”强行保留 OFFSET 分页——用户几乎不会翻到第 200 页，真有需求就用搜索或筛选替代
游标分页在 C# 里实现很简单：参数从 page 改成 cursor（比如上一页最后一条的 Id），查询语句变成 .Where(x => x.Id > cursor).Take(pageSize)。
真正难的不是代码怎么写，而是说服产品接受“只能下一页/上一页”，以及处理游标值重复、删除导致断层这些边界情况。
