必须在Program.cs中调用AddOData并配置模型和查询选项，否则注入ODataQueryOptions会导致500错误；手动绑定时需先Validate再ApplyTo，且Ensure IQueryable以支持分页与过滤。
为什么直接加 ODataQueryOptions 参数会报 500 错误
常见现象是：控制器方法加了 ODataQueryOptions<product></product> 参数，但请求一发就返回 500，日志里看到 System.ArgumentNullException: Value cannot be null. (Parameter 'service')。这不是代码写错了，而是 OData 服务注册不完整——ASP.NET Core 的 DI 容器根本没注入 IEdmModel 和相关查询处理器。
必须在 Program.cs 中显式调用 AddOData 并配置模型：
var builder = WebApplication.CreateBuilder(args);
builder.Services.AddControllers();
builder.Services.AddOData(opt => opt
.AddRouteComponents("odata", GetEdmModel()) // 路由前缀和模型缺一不可
.Filter() // 显式启用 Filter，否则 $filter 不生效
.Select()
.Expand()
.OrderBy()
.Count()
.SetMaxTop(100));
注意：GetEdmModel() 必须返回非 null 的 IEdmModel，推荐用 EdmModelBuilder 或 ODataConventionModelBuilder 构建；若用后者，需确保所有实体类有 public 属性且无循环引用。
如何让普通 API 控制器支持 OData 查询（不改路由）
不是所有接口都要走 /odata/xxx 路由。想保留 /api/products 这种路径，又支持 $filter、$top 等参数，可以手动绑定并执行查询：
- 控制器方法保留传统签名，比如
Get([FromQuery] ODataQueryOptions<product> options)</product> - 但必须在 action 内部手动调用
options.ApplyTo(IQueryable)，不能依赖框架自动处理 - 返回前要确保结果是
IQueryable（不是List或ToArray()），否则ApplyTo会抛NotSupportedException - 如果用了 EF Core，记得先
.AsQueryable()，避免提前执行 SQL
示例片段：
[HttpGet("api/products")]
public IActionResult Get([FromQuery] ODataQueryOptions<Product> options)
{
var query = _context.Products.AsQueryable(); // 关键：必须是 IQueryable
var result = options.ApplyTo(query) as IQueryable<Product>;
return Ok(result.ToList()); // ApplyTo 后再 ToList
}
ODataQueryOptions 的 Validate 和 ApplyTo 顺序为什么不能颠倒
很多人把 options.Validate() 放在 ApplyTo 之后，结果发现非法参数（比如 $filter=1+1）没被拦截，反而进了数据库查询。这是因为 Validate 只检查语法和权限规则，不修改查询表达式；而 ApplyTo 一旦执行，就会生成实际的 LINQ 表达式树——再验证已经晚了。
正确顺序必须是：
- 先调
options.Validate(model)（model是你的IEdmModel） - 捕获
ODataValidationException并返回 400 - 再调
ApplyTo
另外注意：默认验证不检查 $filter 是否访问了未声明的属性，得自己在模型里用 [NotMapped] 或 Ignore 排除敏感字段，否则可能意外暴露数据。
EF Core + OData 分页时 $count=true 为何慢得离谱
开启 $count=true 后接口响应从 50ms 拉到 2s，不是因为 OData 本身，而是 EF Core 默认对每个请求生成两条 SQL：一条查数据，一条用 COUNT(*) 查总数。当表大、关联多、有复杂 WHERE 条件时，COUNT 往往无法走索引，甚至触发全表扫描。
缓解方式有限但有效：
- 确认数据库对应字段有索引（特别是
WHERE条件里的列） - 用
options.Count().PageSize(10)配合SetMaxTop，避免前端传超大$top - 业务允许时，改用估算总数（如 PostgreSQL 的
reltuples）或缓存分页元数据 - 极端情况可禁用 count：
opt.Filter().Count(false)，然后前端用@odata.count缺失来判断是否支持总数
OData 查询链路比表面看起来深得多，尤其是验证时机、IQueryable 生命周期、以及 COUNT 的执行策略，这几处不细看文档很容易掉进性能或安全坑里。
