Hot Chocolate OffsetPagination中LINQ Skip/Take无预期结果排查

先直接说结论：99%的概率是代码配置或使用方式错误，而非[UseOffsetPaging]的Bug，以下是按优先级排序的排查步骤：

1. 检查是否重复应用了分页逻辑 #

这是最常见的坑：当你用了[UseOffsetPaging]特性，Hot Chocolate会自动根据GraphQL查询传入的offset/limit参数，对返回的IQueryable执行Skip/Take。如果你手动在Resolver里又加了一次Skip/Take，就会导致双重分页。

比如错误写法：

[UseOffsetPaging]
public List<Product> GetProducts(AppDbContext db)
{
    // 手动加了分页，框架会再叠加一次
    return db.Products.OrderBy(p => p.Id).Skip(5).Take(10).ToList();
}

后端断点看到的是Skip(5).Take(10)的结果，但框架会额外叠加查询参数里的offset/limit，最终变成Skip(5 + offset).Take(min(10, limit))，返回结果自然不对。

正确做法：Resolver只返回未分页的IQueryable，让框架自动处理分页：

[UseOffsetPaging(DefaultPageSize = 10, MaxPageSize = 50)]
public IQueryable<Product> GetProducts(AppDbContext db)
{
    return db.Products.OrderBy(p => p.Id); // 不要手动加Skip/Take
}

2. 核对[UseOffsetPaging]的参数配置 #

特性的MaxPageSize会限制返回的最大条数，如果你手动设置的Take值超过这个限制，框架会自动截断为MaxPageSize。比如：

[UseOffsetPaging(MaxPageSize = 10)]
public IQueryable<Product> GetProducts(AppDbContext db)
{
    return db.Products.OrderBy(p => p.Id);
}

即使你在GraphQL查询里传了limit:20，框架只会返回10条，后端断点如果是直接查Take(20)的结果，自然和返回结果不符。

另外，检查DefaultPageSize是否和你预期的一致，避免默认值覆盖了自定义参数。

3. 检查GraphQL查询的参数是否正确 #

Hot Chocolate的Offset分页默认参数名是offset和limit，不是skip和take。如果你在Playground里写错了参数名，比如传了skip:0而不是offset:0，框架会使用默认值，导致结果不符合预期。

正确的查询示例：

query {
  products(offset: 0, limit: 10) {
    nodes {
      id
      name
    }
    totalCount
  }
}

4. 检查返回类型是否符合要求 #

[UseOffsetPaging]要求Resolver返回IQueryable<T>或Task<IQueryable<T>>，框架会自动将其包装为Connection<T>类型（包含nodes、totalCount等分页信息）。如果你直接返回List<T>，框架可能无法正确处理分页参数，导致返回全量数据或者结构错误。

5. 排查全局分页配置冲突 #

如果在Startup里配置了全局分页选项，会覆盖局部[UseOffsetPaging]的设置：

services.AddGraphQLServer()
    .SetPagingOptions(new PagingOptions { MaxPageSize = 5 }) // 全局限制最大5条
    .AddQueryType<Query>();

这时候即使你在Resolver里设置MaxPageSize=50，也会被全局的5覆盖，导致返回条数受限。

关于是否是Bug的判断 #

如果以上所有排查步骤都确认无误，且更新到Hot Chocolate最新稳定版本后问题仍存在，才需要考虑是否是框架Bug。此时可以：

• 检查官方GitHub仓库的Issue列表，看是否有相同问题的报告
• 最小化复现Demo，提交新的Issue给官方

但根据经验，这类问题几乎都是使用方式错误，而非框架本身的Bug。

内容的提问来源于stack exchange，提问作者GThree