你是否遇到过这样的场景一个看似简单的列表查询随着业务发展查询条件越来越多Where子句像滚雪球一样膨胀最终变成一个几百行的“巨无霸”方法或者同样的过滤逻辑如“只查询已发布且对当前用户可见的文章”在控制器、服务层、仓储层被重复编写稍一改动就牵一发而动全身这不是架构问题而是查询逻辑的组织问题。在 EF Core 项目中我们花费大量时间编写DbContext和 LINQ却很少系统性地思考如何让查询代码像业务逻辑一样清晰、可复用、易测试。结果就是项目中期开始数据访问层逐渐变得难以维护成为滋生 Bug 和性能问题的温床。本文要解决的核心痛点正在于此。我们将深入探讨如何运用规范模式来“清理”你的 EF Core 查询。这不是简单的代码美化而是一种从根本上提升数据访问代码质量的设计范式。你将看到通过将查询条件封装为独立、可组合的“规范”对象那些散落各处、重复混乱的 LINQ 代码将变得井然有序。读完本文你将能清晰地回答规范模式是什么为什么它比直接在服务层写 LINQ 更好如何一步步在 EF Core 中实现它以及在真实项目中应用时有哪些必须注意的“坑”和最佳实践让我们开始这场代码清理之旅。1. 这篇文章真正要解决的问题混乱的查询逻辑在典型的 ASP.NET Core 三层架构中数据访问逻辑的归宿往往是模糊的。很多开发者会不假思索地将 LINQ 查询写在服务层甚至控制器中// 反例查询逻辑侵入服务层 public class ArticleService { private readonly AppDbContext _context; public async TaskListArticle GetPublishedArticlesForUser(int userId, DateTime? fromDate) { var query _context.Articles .Where(a a.Status ArticleStatus.Published) .Where(a a.IsDeleted false) .Where(a a.AuthorId userId || a.Visibility Visibility.Public); if (fromDate.HasValue) { query query.Where(a a.PublishDate fromDate.Value); } return await query.OrderByDescending(a a.PublishDate).ToListAsync(); } }这段代码功能上没问题但它隐藏了四个严重隐患不可复用已发布、未删除、对用户可见这个核心业务规则可能在GetArticlesForDashboard、GetArticlesForRssFeed等方法中再次出现。一旦规则变化例如增加“审核通过”状态你需要修改所有地方。难以测试要单元测试这个服务方法你必须构建一个完整的DbSetArticle模拟或者直接操作内存数据库测试成本很高。职责混杂服务层本应关注业务协调和流程现在却充斥着数据过滤的具体细节。阻碍优化当你想为这个复杂的组合条件添加数据库索引或者分析其执行计划时发现查询逻辑分散在各处难以统一分析和优化。规范模式要解决的正是这种“查询逻辑无处安放”的架构尴尬。它将查询条件提升为一等公民封装成可独立定义、测试、组合和复用的对象从而让数据访问层像业务层一样清晰、健壮。2. 基础概念什么是规范模式规范模式源于领域驱动设计中的一个概念规格。其核心思想是将业务规则特别是用于选择和验证的规则封装成一个独立的、可测试的谓词对象。在 EF Core 的上下文中一个“规范”就是一个定义了Where条件的对象。但它不止于此一个完整的规范通常还可以包含Include贪婪加载OrderBy/ThenBy排序Skip/Take分页甚至投影Select你可以把它想象成LINQ 查询的乐高积木。每个积木规范代表一个明确的业务意图如“已发布”、“属于某个用户”。你可以单独使用它们也可以轻松地将它们拼接起来构建出复杂的查询而无需重复编写或复制粘贴 LINQ 表达式。与仓储模式的对比 很多项目用仓储模式来封装数据访问。基础仓储IRepositoryT提供了GetById,GetAll,Add,Update等通用操作。这很好但它没有解决“复杂查询”的问题。你可能会在仓储中定义无数个像GetPublishedArticlesByUser这样的具体方法导致仓储接口爆炸。规范模式与仓储模式是互补的。一个良好的实践是基础仓储处理简单的 CRUD而规范则负责描述复杂的、动态的查询条件并通过一个通用的ApplySpecification方法应用到查询上。3. 环境准备与前置条件在开始实现之前请确保你的开发环境已就绪。开发环境要求IDE/编辑器Visual Studio 2022 或 JetBrains Rider 或 VS Code。.NET SDK.NET 6.0, .NET 7.0 或 .NET 8.0。本文示例基于 .NET 8但核心概念适用于所有支持 EF Core 的版本。数据库SQL Server / PostgreSQL / MySQL / SQLite 等均可。EF Core 是数据库提供程序无关的。项目与依赖创建一个新的 ASP.NET Core Web API 项目或使用现有项目。通过 NuGet 包管理器或 CLI 安装必要的依赖# 在你的项目目录下执行 dotnet add package Microsoft.EntityFrameworkCore.SqlServer # 以 SQL Server 为例 dotnet add package Microsoft.EntityFrameworkCore.Tools # 用于迁移可选示例领域模型为了后续演示我们定义一个简单的博客领域模型// 文件路径Models/Article.cs namespace CleanEfCoreQuery.Models; public class Article { public int Id { get; set; } public string Title { get; set; } string.Empty; public string Content { get; set; } string.Empty; public ArticleStatus Status { get; set; } public DateTime PublishDate { get; set; } public bool IsDeleted { get; set; } public Visibility Visibility { get; set; } public int AuthorId { get; set; } public User Author { get; set; } null!; // 导航属性 public ListComment Comments { get; set; } new(); } public enum ArticleStatus { Draft, Published, Archived } public enum Visibility { Private, Public } // 文件路径Models/User.cs public class User { public int Id { get; set; } public string Name { get; set; } string.Empty; public ListArticle Articles { get; set; } new(); } // 文件路径Models/Comment.cs public class Comment { public int Id { get; set; } public string Text { get; set; } string.Empty; public int ArticleId { get; set; } public Article Article { get; set; } null!; }对应的AppDbContext请自行配置。准备好这些我们就可以开始构建规范模式的核心了。4. 核心构建定义规范接口与基类规范模式的核心是接口。我们首先定义一个最基础的规范接口它只做一件事将一个 LINQ 表达式应用到IQueryableT上。// 文件路径Specifications/ISpecification.cs namespace CleanEfCoreQuery.Specifications; public interface ISpecificationT { // 核心定义查询的过滤条件 ExpressionFuncT, bool? Criteria { get; } // 定义需要贪婪加载的导航属性 ListExpressionFuncT, object Includes { get; } // 定义排序规则 ListExpressionFuncT, object OrderByExpressions { get; } ListExpressionFuncT, object OrderByDescendingExpressions { get; } // 定义分页 int? Take { get; } int? Skip { get; } }这个接口定义了规范的“能力”。但直接实现这个接口会很繁琐我们需要一个基类来提供通用的属性和构建方法。// 文件路径Specifications/BaseSpecification.cs namespace CleanEfCoreQuery.Specifications; public abstract class BaseSpecificationT : ISpecificationT { // 实现接口属性 public ExpressionFuncT, bool? Criteria { get; private set; } public ListExpressionFuncT, object Includes { get; } new(); public ListExpressionFuncT, object OrderByExpressions { get; } new(); public ListExpressionFuncT, object OrderByDescendingExpressions { get; } new(); public int? Take { get; private set; } public int? Skip { get; private set; } // 受保护的构建方法供子类在构造函数中调用 protected void ApplyCriteria(ExpressionFuncT, bool criteria) { Criteria criteria; } protected void AddInclude(ExpressionFuncT, object includeExpression) { Includes.Add(includeExpression); } protected void AddOrderBy(ExpressionFuncT, object orderByExpression) { OrderByExpressions.Add(orderByExpression); } protected void AddOrderByDescending(ExpressionFuncT, object orderByDescendingExpression) { OrderByDescendingExpressions.Add(orderByDescendingExpression); } protected void ApplyPaging(int skip, int take) { Skip skip; Take take; } }现在创建新规范变得非常简单继承BaseSpecificationT并在构造函数中通过调用基类方法定义规则。5. 实现规范从简单到复杂让我们用具体的业务需求来演示如何创建规范。示例1一个简单的“已发布文章”规范// 文件路径Specifications/Articles/PublishedArticlesSpecification.cs namespace CleanEfCoreQuery.Specifications.Articles; public class PublishedArticlesSpecification : BaseSpecificationArticle { public PublishedArticlesSpecification() { // 定义核心过滤条件 ApplyCriteria(a a.Status ArticleStatus.Published !a.IsDeleted); // 定义默认排序 AddOrderByDescending(a a.PublishDate); } }示例2一个更复杂的“用户可见文章”规范这个规范需要接收外部参数当前用户ID并组合更复杂的逻辑。// 文件路径Specifications/Articles/ArticlesVisibleToUserSpecification.cs namespace CleanEfCoreQuery.Specifications.Articles; public class ArticlesVisibleToUserSpecification : BaseSpecificationArticle { public ArticlesVisibleToUserSpecification(int currentUserId) { // 复合条件已发布、未删除并且作者是当前用户 或 文章是公开的 ApplyCriteria(a a.Status ArticleStatus.Published !a.IsDeleted (a.AuthorId currentUserId || a.Visibility Visibility.Public)); // 包含作者信息 AddInclude(a a.Author); // 包含评论列表 AddInclude(a a.Comments); AddOrderByDescending(a a.PublishDate); } }示例3一个可复用的“分页”规范分页是一个横切关注点可以单独抽离。// 文件路径Specifications/Common/PaginationSpecification.cs namespace CleanEfCoreQuery.Specifications.Common; public class PaginationSpecificationT : BaseSpecificationT { public PaginationSpecification(int pageNumber, int pageSize) { // 计算 Skip 和 Take ApplyPaging((pageNumber - 1) * pageSize, pageSize); } }关键点每个规范类都代表一个明确的、可测试的、单一的业务意图。PublishedArticlesSpecification的意图就是“获取已发布的文章”我们可以为其编写独立的单元测试验证其Criteria是否正确。6. 应用规范构建规约评估器定义了规范之后我们需要一个工具能将规范应用到 EF Core 的DbSet上生成最终的IQueryableT。这个工具通常称为SpecificationEvaluator或规约评估器。// 文件路径Specifications/Evaluators/SpecificationEvaluator.cs namespace CleanEfCoreQuery.Specifications.Evaluators; public class SpecificationEvaluator { public static IQueryableT GetQueryT( IQueryableT inputQuery, ISpecificationT specification) where T : class { var query inputQuery; // 1. 应用过滤条件 (Where) if (specification.Criteria ! null) { query query.Where(specification.Criteria); } // 2. 应用贪婪加载 (Include) // 注意Include 需要处理多层嵌套这里简化处理 query specification.Includes .Aggregate(query, (current, include) current.Include(include)); // 3. 应用排序 (OrderBy) if (specification.OrderByExpressions.Any()) { IOrderedQueryableT? orderedQuery null; var firstOrderBy specification.OrderByExpressions.First(); orderedQuery query.OrderBy(firstOrderBy); foreach (var orderBy in specification.OrderByExpressions.Skip(1)) { orderedQuery orderedQuery.ThenBy(orderBy); } query orderedQuery ?? query; } // 4. 应用降序排序 (OrderByDescending) - 处理逻辑类似略 // ... 实际代码需要处理 OrderBy 和 OrderByDescending 的混合与优先级 // 5. 应用分页 (Skip/Take) if (specification.Skip.HasValue) { query query.Skip(specification.Skip.Value); } if (specification.Take.HasValue) { query query.Take(specification.Take.Value); } return query; } }这个评估器是连接规范与 EF Core 的桥梁。它接收一个初始的IQueryableT和一个规范对象然后按顺序应用规范中定义的所有操作返回一个新的IQueryableT。这里的关键是它返回的仍然是IQueryable这意味着查询还没有真正执行EF Core 的延迟加载特性得以保留我们还可以继续组合其他操作。7. 集成到仓储层通用规约仓储现在我们将规范模式与仓储模式结合。我们创建一个通用的RepositoryT并为其添加一个能接受规范的方法。// 文件路径Data/IGenericRepository.cs namespace CleanEfCoreQuery.Data; public interface IGenericRepositoryT where T : class { TaskT? GetByIdAsync(int id); TaskIReadOnlyListT ListAllAsync(); // 核心方法根据规约获取列表 TaskIReadOnlyListT ListAsync(ISpecificationT spec); // 核心方法根据规约获取单个实体或默认值 TaskT? GetFirstOrDefaultAsync(ISpecificationT spec); TaskT AddAsync(T entity); Task UpdateAsync(T entity); Task DeleteAsync(T entity); }// 文件路径Data/GenericRepository.cs using CleanEfCoreQuery.Specifications; using CleanEfCoreQuery.Specifications.Evaluators; using Microsoft.EntityFrameworkCore; namespace CleanEfCoreQuery.Data; public class GenericRepositoryT : IGenericRepositoryT where T : class { protected readonly AppDbContext _context; public GenericRepository(AppDbContext context) { _context context; } public virtual async TaskT? GetByIdAsync(int id) { return await _context.SetT().FindAsync(id); } public virtual async TaskIReadOnlyListT ListAllAsync() { return await _context.SetT().ToListAsync(); } // 使用规约的核心方法 public virtual async TaskIReadOnlyListT ListAsync(ISpecificationT spec) { // 1. 获取基础查询DbSet var query _context.SetT().AsQueryable(); // 2. 应用规约 var evaluatedQuery SpecificationEvaluator.GetQuery(query, spec); // 3. 执行查询 return await evaluatedQuery.ToListAsync(); } public virtual async TaskT? GetFirstOrDefaultAsync(ISpecificationT spec) { var query _context.SetT().AsQueryable(); var evaluatedQuery SpecificationEvaluator.GetQuery(query, spec); return await evaluatedQuery.FirstOrDefaultAsync(); } // ... 其他 CRUD 方法 }8. 完整示例在服务层中使用规约让我们回到开头的ArticleService看看如何使用规约来重构它。重构后的服务层// 文件路径Services/ArticleService.cs namespace CleanEfCoreQuery.Services; public class ArticleService { private readonly IGenericRepositoryArticle _articleRepository; public ArticleService(IGenericRepositoryArticle articleRepository) { _articleRepository articleRepository; } public async TaskListArticle GetPublishedArticlesForUser(int userId, DateTime? fromDate) { // 1. 创建核心业务规约 var spec new ArticlesVisibleToUserSpecification(userId); // 2. 可选动态组合额外的过滤条件 // 如果业务允许可以创建一个可组合的规约这里演示另一种思路创建新规约 if (fromDate.HasValue) { // 假设我们有一个更灵活的规约构建器这里为演示我们创建一个新的组合规约 // 在实际项目中你可能会使用“组合规约”模式AndSpecification, OrSpecification var finalSpec new ArticlesVisibleToUserWithDateFilterSpecification(userId, fromDate.Value); return await _articleRepository.ListAsync(finalSpec); } // 3. 执行查询 return (await _articleRepository.ListAsync(spec)).ToList(); } } // 文件路径Specifications/Articles/ArticlesVisibleToUserWithDateFilterSpecification.cs // 演示如何通过继承或组合来创建更具体的规约 public class ArticlesVisibleToUserWithDateFilterSpecification : ArticlesVisibleToUserSpecification { public ArticlesVisibleToUserWithDateFilterSpecification(int currentUserId, DateTime fromDate) : base(currentUserId) // 调用基类构造复用基础条件 { // 获取基类已有的条件表达式 var baseCriteria Criteria; // 组合新的条件在原有条件上追加日期过滤 // 注意这里需要处理表达式树的组合是进阶话题。 // 更简单的做法是重写整个 Criteria或者使用专门的组合规约类。 // 以下为概念性代码实际实现更复杂 // ExpressionFuncArticle, bool dateFilter a a.PublishDate fromDate; // Criteria baseCriteria.And(dateFilter); // 需要 ExpressionExtensions } }更优雅的组合方式组合规约对于动态条件更好的方式是实现AndSpecificationT和OrSpecificationT。// 文件路径Specifications/Composite/AndSpecification.cs public class AndSpecificationT : BaseSpecificationT { public AndSpecification(ISpecificationT left, ISpecificationT right) { // 使用 ExpressionVisitor 或第三方库如 LinqKit来组合表达式树 // 这是一个简化示例实际组合逻辑较复杂 // var parameter Expression.Parameter(typeof(T), “x”); // var combinedExpr Expression.AndAlso( // Expression.Invoke(left.Criteria, parameter), // Expression.Invoke(right.Criteria, parameter)); // Criteria Expression.LambdaFuncT, bool(combinedExpr, parameter); } }在服务层中你可以这样使用var visibleSpec new ArticlesVisibleToUserSpecification(userId); var dateSpec new ArticlesPublishedAfterSpecification(fromDate.Value); var combinedSpec new AndSpecificationArticle(visibleSpec, dateSpec); var results await _articleRepository.ListAsync(combinedSpec);9. 运行结果与效果验证假设数据库中有以下数据IdTitleStatusAuthorIdVisibilityPublishDateIsDeleted1文章APublished1Public2024-01-01false2文章BDraft1Private2024-01-02false3文章CPublished2Public2024-01-03false4文章DPublished2Private2024-01-04false当currentUserId 2时调用ArticlesVisibleToUserSpecification生成的SQL概念SELECT * FROM Articles WHERE Status 1 AND IsDeleted 0 AND (AuthorId 2 OR Visibility 1) ORDER BY PublishDate DESC返回结果文章C作者是2已发布公开文章D作者是2已发布私有。文章A作者是1对用户2不可见因为它是私有的。包含导航属性查询会自动LEFT JOIN到Users表和Comments表填充Author和Comments属性避免了 N1 查询问题。验证方式单元测试你可以直接对规约类进行单元测试验证其Criteria表达式树是否正确无需依赖数据库。[Fact] public void PublishedArticlesSpecification_Criteria_IsCorrect() { var spec new PublishedArticlesSpecification(); var articlePublished new Article { Status ArticleStatus.Published, IsDeleted false }; var articleDraft new Article { Status ArticleStatus.Draft, IsDeleted false }; var func spec.Criteria!.Compile(); // 将表达式树编译为委托 Assert.True(func(articlePublished)); Assert.False(func(articleDraft)); }集成测试在内存数据库或测试数据库中使用GenericRepository和规约执行查询验证返回的数据是否符合业务预期。日志查看在开发环境启用 EF Core 的敏感数据日志查看实际生成的 SQL 语句确认Include和Where条件是否正确应用。10. 常见问题与排查思路问题现象可能原因排查方式解决方案查询结果为空但数据库有数据1. 规约的Criteria表达式逻辑错误。2. 多个Criteria在组合时逻辑关系AND/OR错误。3. 导航属性未正确加载导致过滤条件依赖的导航属性为null。1. 单元测试规约的Criteria。2. 输出规约的Criteria.ToString()查看表达式树。3. 检查Includes列表是否包含了过滤条件所需的导航属性。1. 修正业务逻辑。2. 使用LinqKit等库进行可靠的表达式组合。3. 在规约中添加必要的AddInclude。出现NullReferenceException在Criteria表达式中访问了可能为null的导航属性而未使用空条件运算符。检查规约中Criteria表达式特别是涉及导航属性链如a.Author.Profile.Name的部分。在表达式中使用?.空条件运算符或在规约中预先Include确保导航属性已加载。生成的 SQL 性能低下1.Includes过多或过深导致复杂连接。2. 规约组合导致 SQL 条件过于复杂索引失效。1. 使用 SQL Server Profiler 或 EF Core 日志查看生成的 SQL。2. 分析执行计划。1. 按需加载使用投影Select代替贪婪加载不需要的字段。2. 考虑将复杂规约拆分为多个查询或在数据库层面优化索引。分页或排序结果不正确1. 多个OrderBy优先级处理错误。2. 分页前排序不稳定如按非唯一字段排序。1. 检查SpecificationEvaluator中排序逻辑确保OrderBy和OrderByDescending正确应用了ThenBy。2. 确保排序字段组合能唯一确定顺序或增加一个唯一字段如Id作为最终排序条件。1. 完善评估器的排序逻辑。2. 在规约中明确添加最终排序条件如AddOrderBy(a a.Id)。无法组合两个规约的条件直接使用And/Or连接两个ExpressionFuncT, bool对象比较复杂。表达式树是不可变的需要借助工具进行组合。引入LinqKit库使用PredicateBuilder或Expand()方法或者实现自己的AndSpecification/OrSpecification。11. 最佳实践与工程建议保持规约的单一职责一个规约类应只代表一个明确的业务意图。不要创建GetDashboardDataSpecification这种包含无数条件的“上帝规约”。为规约编写单元测试规约是纯业务逻辑的体现不依赖外部资源非常适合单元测试。测试其Criteria是否能正确过滤内存中的对象集合。谨慎使用Include贪婪加载是性能杀手。只在当前业务场景确实需要完整对象图时才使用Include。考虑使用投影Select来只查询需要的字段这可以显著提升查询性能并减少内存占用。你可以将投影逻辑也封装进规约。考虑规约的命名命名应体现其业务意图而非技术细节。例如ActiveUsersSpecification比UsersWhereIsActiveTrueSpecification更好。处理动态查询对于高度动态的查询如高级搜索规约模式可能不是最优解。此时可以考虑使用动态 LINQ 库如System.Linq.Dynamic.Core或显式构建IQueryable并在服务层组合。规约模式更适合于那些定义良好、可复用的业务查询单元。与 CQRS 结合在更复杂的系统中可以将规约模式与 CQRS命令查询职责分离架构结合。规约专门用于定义查询端的复杂条件使查询模型更加清晰。性能优化复杂的规约组合可能导致 SQL 语句冗长。定期监控生成的 SQL确保其能有效利用数据库索引。对于特别复杂的查询有时编写一个优化的存储过程或视图可能是更务实的选择。依赖注入GenericRepositoryT和具体的规约类通常不需要注册到 DI 容器。规约是瞬态对象在需要时new即可。仓储接口IGenericRepositoryT需要注册。12. 总结与后续方向通过本文的探讨你应该已经认识到用规范模式“清理” EF Core 查询本质上是对查询逻辑进行领域建模。它将散落的、隐式的业务规则提升为显式的、可测试的、可复用的软件组件。回顾核心收益清晰度查询条件有了自己的“家”代码库结构一目了然。可复用性核心业务规则如“已发布”被封装一次处处使用。可测试性规约逻辑可以脱离数据库进行单元测试。可组合性通过AndSpecification、OrSpecification可以灵活构建复杂查询。你可以继续深化的方向实现Select投影规约将查询结果的形状DTO也封装进规约实现从数据库到 API 模型的直接高效映射。集成LinqKit使用PredicateBuilder来更优雅、安全地组合多个规约的Criteria表达式。构建规约构建器对于高度动态的查询界面可以设计一个流畅接口Fluent API的构建器来动态组装规约。探索 Ardalis.Specification这是一个非常成熟、功能丰富的规约模式实现库Ardalis.Specification和Ardalis.Specification.EntityFrameworkCore提供了开箱即用的组合规约、排序、分页、缓存甚至二级缓存支持非常适合在生产项目中直接采用。从今天开始审视你项目中的那些冗长的Where语句思考它们能否被提取成一个有意义的Specification类。这一步小小的重构将为你的数据访问层带来持久的秩序与健壮性。
你是否遇到过这样的场景一个看似简单的列表查询随着业务发展查询条件越来越多Where子句像滚雪球一样膨胀最终变成一个几百行的“巨无霸”方法或者同样的过滤逻辑如“只查询已发布且对当前用户可见的文章”在控制器、服务层、仓储层被重复编写稍一改动就牵一发而动全身这不是架构问题而是查询逻辑的组织问题。在 EF Core 项目中我们花费大量时间编写DbContext和 LINQ却很少系统性地思考如何让查询代码像业务逻辑一样清晰、可复用、易测试。结果就是项目中期开始数据访问层逐渐变得难以维护成为滋生 Bug 和性能问题的温床。本文要解决的核心痛点正在于此。我们将深入探讨如何运用规范模式来“清理”你的 EF Core 查询。这不是简单的代码美化而是一种从根本上提升数据访问代码质量的设计范式。你将看到通过将查询条件封装为独立、可组合的“规范”对象那些散落各处、重复混乱的 LINQ 代码将变得井然有序。读完本文你将能清晰地回答规范模式是什么为什么它比直接在服务层写 LINQ 更好如何一步步在 EF Core 中实现它以及在真实项目中应用时有哪些必须注意的“坑”和最佳实践让我们开始这场代码清理之旅。1. 这篇文章真正要解决的问题混乱的查询逻辑在典型的 ASP.NET Core 三层架构中数据访问逻辑的归宿往往是模糊的。很多开发者会不假思索地将 LINQ 查询写在服务层甚至控制器中// 反例查询逻辑侵入服务层 public class ArticleService { private readonly AppDbContext _context; public async TaskListArticle GetPublishedArticlesForUser(int userId, DateTime? fromDate) { var query _context.Articles .Where(a a.Status ArticleStatus.Published) .Where(a a.IsDeleted false) .Where(a a.AuthorId userId || a.Visibility Visibility.Public); if (fromDate.HasValue) { query query.Where(a a.PublishDate fromDate.Value); } return await query.OrderByDescending(a a.PublishDate).ToListAsync(); } }这段代码功能上没问题但它隐藏了四个严重隐患不可复用已发布、未删除、对用户可见这个核心业务规则可能在GetArticlesForDashboard、GetArticlesForRssFeed等方法中再次出现。一旦规则变化例如增加“审核通过”状态你需要修改所有地方。难以测试要单元测试这个服务方法你必须构建一个完整的DbSetArticle模拟或者直接操作内存数据库测试成本很高。职责混杂服务层本应关注业务协调和流程现在却充斥着数据过滤的具体细节。阻碍优化当你想为这个复杂的组合条件添加数据库索引或者分析其执行计划时发现查询逻辑分散在各处难以统一分析和优化。规范模式要解决的正是这种“查询逻辑无处安放”的架构尴尬。它将查询条件提升为一等公民封装成可独立定义、测试、组合和复用的对象从而让数据访问层像业务层一样清晰、健壮。2. 基础概念什么是规范模式规范模式源于领域驱动设计中的一个概念规格。其核心思想是将业务规则特别是用于选择和验证的规则封装成一个独立的、可测试的谓词对象。在 EF Core 的上下文中一个“规范”就是一个定义了Where条件的对象。但它不止于此一个完整的规范通常还可以包含Include贪婪加载OrderBy/ThenBy排序Skip/Take分页甚至投影Select你可以把它想象成LINQ 查询的乐高积木。每个积木规范代表一个明确的业务意图如“已发布”、“属于某个用户”。你可以单独使用它们也可以轻松地将它们拼接起来构建出复杂的查询而无需重复编写或复制粘贴 LINQ 表达式。与仓储模式的对比 很多项目用仓储模式来封装数据访问。基础仓储IRepositoryT提供了GetById,GetAll,Add,Update等通用操作。这很好但它没有解决“复杂查询”的问题。你可能会在仓储中定义无数个像GetPublishedArticlesByUser这样的具体方法导致仓储接口爆炸。规范模式与仓储模式是互补的。一个良好的实践是基础仓储处理简单的 CRUD而规范则负责描述复杂的、动态的查询条件并通过一个通用的ApplySpecification方法应用到查询上。3. 环境准备与前置条件在开始实现之前请确保你的开发环境已就绪。开发环境要求IDE/编辑器Visual Studio 2022 或 JetBrains Rider 或 VS Code。.NET SDK.NET 6.0, .NET 7.0 或 .NET 8.0。本文示例基于 .NET 8但核心概念适用于所有支持 EF Core 的版本。数据库SQL Server / PostgreSQL / MySQL / SQLite 等均可。EF Core 是数据库提供程序无关的。项目与依赖创建一个新的 ASP.NET Core Web API 项目或使用现有项目。通过 NuGet 包管理器或 CLI 安装必要的依赖# 在你的项目目录下执行 dotnet add package Microsoft.EntityFrameworkCore.SqlServer # 以 SQL Server 为例 dotnet add package Microsoft.EntityFrameworkCore.Tools # 用于迁移可选示例领域模型为了后续演示我们定义一个简单的博客领域模型// 文件路径Models/Article.cs namespace CleanEfCoreQuery.Models; public class Article { public int Id { get; set; } public string Title { get; set; } string.Empty; public string Content { get; set; } string.Empty; public ArticleStatus Status { get; set; } public DateTime PublishDate { get; set; } public bool IsDeleted { get; set; } public Visibility Visibility { get; set; } public int AuthorId { get; set; } public User Author { get; set; } null!; // 导航属性 public ListComment Comments { get; set; } new(); } public enum ArticleStatus { Draft, Published, Archived } public enum Visibility { Private, Public } // 文件路径Models/User.cs public class User { public int Id { get; set; } public string Name { get; set; } string.Empty; public ListArticle Articles { get; set; } new(); } // 文件路径Models/Comment.cs public class Comment { public int Id { get; set; } public string Text { get; set; } string.Empty; public int ArticleId { get; set; } public Article Article { get; set; } null!; }对应的AppDbContext请自行配置。准备好这些我们就可以开始构建规范模式的核心了。4. 核心构建定义规范接口与基类规范模式的核心是接口。我们首先定义一个最基础的规范接口它只做一件事将一个 LINQ 表达式应用到IQueryableT上。// 文件路径Specifications/ISpecification.cs namespace CleanEfCoreQuery.Specifications; public interface ISpecificationT { // 核心定义查询的过滤条件 ExpressionFuncT, bool? Criteria { get; } // 定义需要贪婪加载的导航属性 ListExpressionFuncT, object Includes { get; } // 定义排序规则 ListExpressionFuncT, object OrderByExpressions { get; } ListExpressionFuncT, object OrderByDescendingExpressions { get; } // 定义分页 int? Take { get; } int? Skip { get; } }这个接口定义了规范的“能力”。但直接实现这个接口会很繁琐我们需要一个基类来提供通用的属性和构建方法。// 文件路径Specifications/BaseSpecification.cs namespace CleanEfCoreQuery.Specifications; public abstract class BaseSpecificationT : ISpecificationT { // 实现接口属性 public ExpressionFuncT, bool? Criteria { get; private set; } public ListExpressionFuncT, object Includes { get; } new(); public ListExpressionFuncT, object OrderByExpressions { get; } new(); public ListExpressionFuncT, object OrderByDescendingExpressions { get; } new(); public int? Take { get; private set; } public int? Skip { get; private set; } // 受保护的构建方法供子类在构造函数中调用 protected void ApplyCriteria(ExpressionFuncT, bool criteria) { Criteria criteria; } protected void AddInclude(ExpressionFuncT, object includeExpression) { Includes.Add(includeExpression); } protected void AddOrderBy(ExpressionFuncT, object orderByExpression) { OrderByExpressions.Add(orderByExpression); } protected void AddOrderByDescending(ExpressionFuncT, object orderByDescendingExpression) { OrderByDescendingExpressions.Add(orderByDescendingExpression); } protected void ApplyPaging(int skip, int take) { Skip skip; Take take; } }现在创建新规范变得非常简单继承BaseSpecificationT并在构造函数中通过调用基类方法定义规则。5. 实现规范从简单到复杂让我们用具体的业务需求来演示如何创建规范。示例1一个简单的“已发布文章”规范// 文件路径Specifications/Articles/PublishedArticlesSpecification.cs namespace CleanEfCoreQuery.Specifications.Articles; public class PublishedArticlesSpecification : BaseSpecificationArticle { public PublishedArticlesSpecification() { // 定义核心过滤条件 ApplyCriteria(a a.Status ArticleStatus.Published !a.IsDeleted); // 定义默认排序 AddOrderByDescending(a a.PublishDate); } }示例2一个更复杂的“用户可见文章”规范这个规范需要接收外部参数当前用户ID并组合更复杂的逻辑。// 文件路径Specifications/Articles/ArticlesVisibleToUserSpecification.cs namespace CleanEfCoreQuery.Specifications.Articles; public class ArticlesVisibleToUserSpecification : BaseSpecificationArticle { public ArticlesVisibleToUserSpecification(int currentUserId) { // 复合条件已发布、未删除并且作者是当前用户 或 文章是公开的 ApplyCriteria(a a.Status ArticleStatus.Published !a.IsDeleted (a.AuthorId currentUserId || a.Visibility Visibility.Public)); // 包含作者信息 AddInclude(a a.Author); // 包含评论列表 AddInclude(a a.Comments); AddOrderByDescending(a a.PublishDate); } }示例3一个可复用的“分页”规范分页是一个横切关注点可以单独抽离。// 文件路径Specifications/Common/PaginationSpecification.cs namespace CleanEfCoreQuery.Specifications.Common; public class PaginationSpecificationT : BaseSpecificationT { public PaginationSpecification(int pageNumber, int pageSize) { // 计算 Skip 和 Take ApplyPaging((pageNumber - 1) * pageSize, pageSize); } }关键点每个规范类都代表一个明确的、可测试的、单一的业务意图。PublishedArticlesSpecification的意图就是“获取已发布的文章”我们可以为其编写独立的单元测试验证其Criteria是否正确。6. 应用规范构建规约评估器定义了规范之后我们需要一个工具能将规范应用到 EF Core 的DbSet上生成最终的IQueryableT。这个工具通常称为SpecificationEvaluator或规约评估器。// 文件路径Specifications/Evaluators/SpecificationEvaluator.cs namespace CleanEfCoreQuery.Specifications.Evaluators; public class SpecificationEvaluator { public static IQueryableT GetQueryT( IQueryableT inputQuery, ISpecificationT specification) where T : class { var query inputQuery; // 1. 应用过滤条件 (Where) if (specification.Criteria ! null) { query query.Where(specification.Criteria); } // 2. 应用贪婪加载 (Include) // 注意Include 需要处理多层嵌套这里简化处理 query specification.Includes .Aggregate(query, (current, include) current.Include(include)); // 3. 应用排序 (OrderBy) if (specification.OrderByExpressions.Any()) { IOrderedQueryableT? orderedQuery null; var firstOrderBy specification.OrderByExpressions.First(); orderedQuery query.OrderBy(firstOrderBy); foreach (var orderBy in specification.OrderByExpressions.Skip(1)) { orderedQuery orderedQuery.ThenBy(orderBy); } query orderedQuery ?? query; } // 4. 应用降序排序 (OrderByDescending) - 处理逻辑类似略 // ... 实际代码需要处理 OrderBy 和 OrderByDescending 的混合与优先级 // 5. 应用分页 (Skip/Take) if (specification.Skip.HasValue) { query query.Skip(specification.Skip.Value); } if (specification.Take.HasValue) { query query.Take(specification.Take.Value); } return query; } }这个评估器是连接规范与 EF Core 的桥梁。它接收一个初始的IQueryableT和一个规范对象然后按顺序应用规范中定义的所有操作返回一个新的IQueryableT。这里的关键是它返回的仍然是IQueryable这意味着查询还没有真正执行EF Core 的延迟加载特性得以保留我们还可以继续组合其他操作。7. 集成到仓储层通用规约仓储现在我们将规范模式与仓储模式结合。我们创建一个通用的RepositoryT并为其添加一个能接受规范的方法。// 文件路径Data/IGenericRepository.cs namespace CleanEfCoreQuery.Data; public interface IGenericRepositoryT where T : class { TaskT? GetByIdAsync(int id); TaskIReadOnlyListT ListAllAsync(); // 核心方法根据规约获取列表 TaskIReadOnlyListT ListAsync(ISpecificationT spec); // 核心方法根据规约获取单个实体或默认值 TaskT? GetFirstOrDefaultAsync(ISpecificationT spec); TaskT AddAsync(T entity); Task UpdateAsync(T entity); Task DeleteAsync(T entity); }// 文件路径Data/GenericRepository.cs using CleanEfCoreQuery.Specifications; using CleanEfCoreQuery.Specifications.Evaluators; using Microsoft.EntityFrameworkCore; namespace CleanEfCoreQuery.Data; public class GenericRepositoryT : IGenericRepositoryT where T : class { protected readonly AppDbContext _context; public GenericRepository(AppDbContext context) { _context context; } public virtual async TaskT? GetByIdAsync(int id) { return await _context.SetT().FindAsync(id); } public virtual async TaskIReadOnlyListT ListAllAsync() { return await _context.SetT().ToListAsync(); } // 使用规约的核心方法 public virtual async TaskIReadOnlyListT ListAsync(ISpecificationT spec) { // 1. 获取基础查询DbSet var query _context.SetT().AsQueryable(); // 2. 应用规约 var evaluatedQuery SpecificationEvaluator.GetQuery(query, spec); // 3. 执行查询 return await evaluatedQuery.ToListAsync(); } public virtual async TaskT? GetFirstOrDefaultAsync(ISpecificationT spec) { var query _context.SetT().AsQueryable(); var evaluatedQuery SpecificationEvaluator.GetQuery(query, spec); return await evaluatedQuery.FirstOrDefaultAsync(); } // ... 其他 CRUD 方法 }8. 完整示例在服务层中使用规约让我们回到开头的ArticleService看看如何使用规约来重构它。重构后的服务层// 文件路径Services/ArticleService.cs namespace CleanEfCoreQuery.Services; public class ArticleService { private readonly IGenericRepositoryArticle _articleRepository; public ArticleService(IGenericRepositoryArticle articleRepository) { _articleRepository articleRepository; } public async TaskListArticle GetPublishedArticlesForUser(int userId, DateTime? fromDate) { // 1. 创建核心业务规约 var spec new ArticlesVisibleToUserSpecification(userId); // 2. 可选动态组合额外的过滤条件 // 如果业务允许可以创建一个可组合的规约这里演示另一种思路创建新规约 if (fromDate.HasValue) { // 假设我们有一个更灵活的规约构建器这里为演示我们创建一个新的组合规约 // 在实际项目中你可能会使用“组合规约”模式AndSpecification, OrSpecification var finalSpec new ArticlesVisibleToUserWithDateFilterSpecification(userId, fromDate.Value); return await _articleRepository.ListAsync(finalSpec); } // 3. 执行查询 return (await _articleRepository.ListAsync(spec)).ToList(); } } // 文件路径Specifications/Articles/ArticlesVisibleToUserWithDateFilterSpecification.cs // 演示如何通过继承或组合来创建更具体的规约 public class ArticlesVisibleToUserWithDateFilterSpecification : ArticlesVisibleToUserSpecification { public ArticlesVisibleToUserWithDateFilterSpecification(int currentUserId, DateTime fromDate) : base(currentUserId) // 调用基类构造复用基础条件 { // 获取基类已有的条件表达式 var baseCriteria Criteria; // 组合新的条件在原有条件上追加日期过滤 // 注意这里需要处理表达式树的组合是进阶话题。 // 更简单的做法是重写整个 Criteria或者使用专门的组合规约类。 // 以下为概念性代码实际实现更复杂 // ExpressionFuncArticle, bool dateFilter a a.PublishDate fromDate; // Criteria baseCriteria.And(dateFilter); // 需要 ExpressionExtensions } }更优雅的组合方式组合规约对于动态条件更好的方式是实现AndSpecificationT和OrSpecificationT。// 文件路径Specifications/Composite/AndSpecification.cs public class AndSpecificationT : BaseSpecificationT { public AndSpecification(ISpecificationT left, ISpecificationT right) { // 使用 ExpressionVisitor 或第三方库如 LinqKit来组合表达式树 // 这是一个简化示例实际组合逻辑较复杂 // var parameter Expression.Parameter(typeof(T), “x”); // var combinedExpr Expression.AndAlso( // Expression.Invoke(left.Criteria, parameter), // Expression.Invoke(right.Criteria, parameter)); // Criteria Expression.LambdaFuncT, bool(combinedExpr, parameter); } }在服务层中你可以这样使用var visibleSpec new ArticlesVisibleToUserSpecification(userId); var dateSpec new ArticlesPublishedAfterSpecification(fromDate.Value); var combinedSpec new AndSpecificationArticle(visibleSpec, dateSpec); var results await _articleRepository.ListAsync(combinedSpec);9. 运行结果与效果验证假设数据库中有以下数据IdTitleStatusAuthorIdVisibilityPublishDateIsDeleted1文章APublished1Public2024-01-01false2文章BDraft1Private2024-01-02false3文章CPublished2Public2024-01-03false4文章DPublished2Private2024-01-04false当currentUserId 2时调用ArticlesVisibleToUserSpecification生成的SQL概念SELECT * FROM Articles WHERE Status 1 AND IsDeleted 0 AND (AuthorId 2 OR Visibility 1) ORDER BY PublishDate DESC返回结果文章C作者是2已发布公开文章D作者是2已发布私有。文章A作者是1对用户2不可见因为它是私有的。包含导航属性查询会自动LEFT JOIN到Users表和Comments表填充Author和Comments属性避免了 N1 查询问题。验证方式单元测试你可以直接对规约类进行单元测试验证其Criteria表达式树是否正确无需依赖数据库。[Fact] public void PublishedArticlesSpecification_Criteria_IsCorrect() { var spec new PublishedArticlesSpecification(); var articlePublished new Article { Status ArticleStatus.Published, IsDeleted false }; var articleDraft new Article { Status ArticleStatus.Draft, IsDeleted false }; var func spec.Criteria!.Compile(); // 将表达式树编译为委托 Assert.True(func(articlePublished)); Assert.False(func(articleDraft)); }集成测试在内存数据库或测试数据库中使用GenericRepository和规约执行查询验证返回的数据是否符合业务预期。日志查看在开发环境启用 EF Core 的敏感数据日志查看实际生成的 SQL 语句确认Include和Where条件是否正确应用。10. 常见问题与排查思路问题现象可能原因排查方式解决方案查询结果为空但数据库有数据1. 规约的Criteria表达式逻辑错误。2. 多个Criteria在组合时逻辑关系AND/OR错误。3. 导航属性未正确加载导致过滤条件依赖的导航属性为null。1. 单元测试规约的Criteria。2. 输出规约的Criteria.ToString()查看表达式树。3. 检查Includes列表是否包含了过滤条件所需的导航属性。1. 修正业务逻辑。2. 使用LinqKit等库进行可靠的表达式组合。3. 在规约中添加必要的AddInclude。出现NullReferenceException在Criteria表达式中访问了可能为null的导航属性而未使用空条件运算符。检查规约中Criteria表达式特别是涉及导航属性链如a.Author.Profile.Name的部分。在表达式中使用?.空条件运算符或在规约中预先Include确保导航属性已加载。生成的 SQL 性能低下1.Includes过多或过深导致复杂连接。2. 规约组合导致 SQL 条件过于复杂索引失效。1. 使用 SQL Server Profiler 或 EF Core 日志查看生成的 SQL。2. 分析执行计划。1. 按需加载使用投影Select代替贪婪加载不需要的字段。2. 考虑将复杂规约拆分为多个查询或在数据库层面优化索引。分页或排序结果不正确1. 多个OrderBy优先级处理错误。2. 分页前排序不稳定如按非唯一字段排序。1. 检查SpecificationEvaluator中排序逻辑确保OrderBy和OrderByDescending正确应用了ThenBy。2. 确保排序字段组合能唯一确定顺序或增加一个唯一字段如Id作为最终排序条件。1. 完善评估器的排序逻辑。2. 在规约中明确添加最终排序条件如AddOrderBy(a a.Id)。无法组合两个规约的条件直接使用And/Or连接两个ExpressionFuncT, bool对象比较复杂。表达式树是不可变的需要借助工具进行组合。引入LinqKit库使用PredicateBuilder或Expand()方法或者实现自己的AndSpecification/OrSpecification。11. 最佳实践与工程建议保持规约的单一职责一个规约类应只代表一个明确的业务意图。不要创建GetDashboardDataSpecification这种包含无数条件的“上帝规约”。为规约编写单元测试规约是纯业务逻辑的体现不依赖外部资源非常适合单元测试。测试其Criteria是否能正确过滤内存中的对象集合。谨慎使用Include贪婪加载是性能杀手。只在当前业务场景确实需要完整对象图时才使用Include。考虑使用投影Select来只查询需要的字段这可以显著提升查询性能并减少内存占用。你可以将投影逻辑也封装进规约。考虑规约的命名命名应体现其业务意图而非技术细节。例如ActiveUsersSpecification比UsersWhereIsActiveTrueSpecification更好。处理动态查询对于高度动态的查询如高级搜索规约模式可能不是最优解。此时可以考虑使用动态 LINQ 库如System.Linq.Dynamic.Core或显式构建IQueryable并在服务层组合。规约模式更适合于那些定义良好、可复用的业务查询单元。与 CQRS 结合在更复杂的系统中可以将规约模式与 CQRS命令查询职责分离架构结合。规约专门用于定义查询端的复杂条件使查询模型更加清晰。性能优化复杂的规约组合可能导致 SQL 语句冗长。定期监控生成的 SQL确保其能有效利用数据库索引。对于特别复杂的查询有时编写一个优化的存储过程或视图可能是更务实的选择。依赖注入GenericRepositoryT和具体的规约类通常不需要注册到 DI 容器。规约是瞬态对象在需要时new即可。仓储接口IGenericRepositoryT需要注册。12. 总结与后续方向通过本文的探讨你应该已经认识到用规范模式“清理” EF Core 查询本质上是对查询逻辑进行领域建模。它将散落的、隐式的业务规则提升为显式的、可测试的、可复用的软件组件。回顾核心收益清晰度查询条件有了自己的“家”代码库结构一目了然。可复用性核心业务规则如“已发布”被封装一次处处使用。可测试性规约逻辑可以脱离数据库进行单元测试。可组合性通过AndSpecification、OrSpecification可以灵活构建复杂查询。你可以继续深化的方向实现Select投影规约将查询结果的形状DTO也封装进规约实现从数据库到 API 模型的直接高效映射。集成LinqKit使用PredicateBuilder来更优雅、安全地组合多个规约的Criteria表达式。构建规约构建器对于高度动态的查询界面可以设计一个流畅接口Fluent API的构建器来动态组装规约。探索 Ardalis.Specification这是一个非常成熟、功能丰富的规约模式实现库Ardalis.Specification和Ardalis.Specification.EntityFrameworkCore提供了开箱即用的组合规约、排序、分页、缓存甚至二级缓存支持非常适合在生产项目中直接采用。从今天开始审视你项目中的那些冗长的Where语句思考它们能否被提取成一个有意义的Specification类。这一步小小的重构将为你的数据访问层带来持久的秩序与健壮性。
)
