学习ASP.NET Core(08)-过滤搜索与分页排序

上一篇我们介绍了AOP的基本概览，并使用动态代理的方式添加了服务日志；本章我们将介绍过滤与搜索、分页与排序并添加对应的功能

注：本章内容大多是基于solenovex的使用 ASP.NET Core 3.x 构建 RESTful Web API视频内容，若想进一步了解相关知识，请查看原视频

一、过滤与搜索

1、定义

1、什么是过滤？意思就是把某个字段的名字及希望匹配的值传递给系统，系统根据条件限定返回的集合内容；

按点外卖的例子来说，食物类别、店铺评分、距离远近等过滤条件提供给你，您自个儿根据需求筛选，系统返回过滤后的内容给你；

2、什么是搜索？意思就是把需要搜索的值传递给系统，系统按照其内部逻辑查找符合条件的数据，完成后将数据添加到集合中返回；

还是按点外卖的例子来说，一哥们张三特别喜欢吃烧烤，他在搜索栏中搜索烧烤，会出现什么？食物类别是烧烤的，店铺名称是烧烤的，甚至会有商品名称包含烧烤的，当然具体出现什么还要看系统的内部逻辑；

3、相同点及差异

相同点：过滤和搜索的参数并不是资源的一部分，而是使用者根据实际需求自行添加的；
差异：过滤一般是一个完整的集合，根据条件把匹配或不匹配的数据移除；

搜索一般是一个空集合，根据条件把匹配或不匹配的数据往里面添加

2、实际应用

1、在前面的章节我们有提到过数据模型的概览，即用户看到的和存储在数据库的可能不是一个字段，所以在实际进行过滤或搜索操作时，用户只能针对他看到的资源的字段进行过滤或搜索操作，所以内部逻辑要考虑到这一点；

2、在实际开发中，会有添加字段的情况，那就意味着过滤/搜索的条件是会变化的，为了适应这种不确定性，我们可以针对过滤/搜索条件建立对应的类，在类的内部添加过滤/搜索条件。

3、实际应用时过滤和搜索经常会配合使用

3、基于项目的添加

3.1、添加参数类

我们在Model层添加一个Parameters文件夹，这里计划以文章作为演示，所以我们添加一个ArticleParameters类，添加过滤字段和搜索字段，如下：

using System;

namespace BlogSystem.Model.Parameters

{

    public class ArticleParameters

    {

        //过滤条件——距离时间

        public DistanceTime DistanceTime { get; set; }

        //搜索条件

        public string SearchStr { get; set; }

    }

    public enum DistanceTime

    {

        Week = 1,

        Month = 2,

        Year = 3,

    }

}

3.2、添加接口

在IBLL层的IArticleService中添加对应的过滤搜索方法，其返回值是文章集合，如下：

        /// <summary>

        /// 文章过滤及搜索

        /// </summary>

        /// <param name="parameters"></param>

        /// <returns></returns>

        Task<List<ArticleListViewModel>> GetArticles(ArticleParameters parameters);

3.3、方法实现

在BLL层的ArticleService中实现上一步新增的接口方法，如下：

        /// <summary>

        /// 文章过滤及搜索

        /// </summary>

        /// <param name="parameters"></param>

        /// <returns></returns>

        public async Task<List<ArticleListViewModel>> GetArticles(ArticleParameters parameters)

        {

            if (parameters == null) throw new ArgumentNullException(nameof(parameters));

            var resultList = _articleRepository.GetAll();

            var dateTime = DateTime.Now;

            //过滤条件，判断枚举是否引用

            if (Enum.IsDefined(typeof(DistanceTime), parameters.DistanceTime))

            {

                switch (parameters.DistanceTime)

                {

                    case DistanceTime.Week:

                        dateTime = dateTime.AddDays(-7);

                        break;

                    case DistanceTime.Month:

                        dateTime = dateTime.AddMonths(-1);

                        break;

                    case DistanceTime.Year:

                        dateTime = dateTime.AddYears(-1);

                        break;

                }

                resultList = resultList.Where(m => m.CreateTime > dateTime);

            }

            //搜索条件，暂时添加标题和内容

            if (!string.IsNullOrWhiteSpace(parameters.SearchStr))

            {

                parameters.SearchStr = parameters.SearchStr.Trim();

                resultList = resultList.Where(m =>

                    m.Title.Contains(parameters.SearchStr) || m.Content.Contains(parameters.SearchStr));

            }

            //返回最终结果

            return await resultList.Select(m => new ArticleListViewModel

            {

                ArticleId = m.Id,

                Title = m.Title,

                Content = m.Content,

                CreateTime = m.CreateTime,

                Account = m.User.Account,

                ProfilePhoto = m.User.ProfilePhoto

            }).ToListAsync();

        }

3.4、控制层调用

在BlogSystem.Core项目的ArticleController中添加筛选/搜索方法，如下：

        /// <summary>

        /// 通过过滤/搜索查询符合条件的文章

        /// </summary>

        /// <param name="parameters"></param>

        /// <returns></returns>

        [HttpGet]

        public async Task<IActionResult> GetArticles(ArticleParameters parameters)

        {

            var list = await _articleService.GetArticles(parameters);

            return Ok(list);

        }

3.5、问题与功能实现

运行后选择对应的筛选条件，输入对应的查询字段，查询发现出现如下错误：TypeError: Failed to execute 'fetch' on 'Window': Request with GET/HEAD method c，还记得上一节提到的对象绑定吗？跳转查看，这里我们需要手动指定查询参数的来源为[FromQuery]，修改并编译后重新运行，输入过滤和搜索条件，成功执行

二、分页

1、分页说明

通常在集合资源比较大的情况下，会进行翻页查询，来避免可能出现的性能问题；
系统默认情况下就应该进行分页，且操作对象应该是底层的数据；
一般情况下查询参数分为每页的个数PageSize和页码PageNumber，且会通过QueryString传递；

2、实际应用

我们应该对每页的个数PageSize进行控制，防止用户录入一个比较大的数字；
我们应该设定一个默认值，用户不指定页码和数量的情况下则按默认数值进行查询
分页应该在过滤和搜索之后进行，否则结果会不准确

3、一般实现

3.1、添加默认参数

在添加过滤和搜索功能时，我们添加了一个ArticleParameters类用来放置条件参数，同样我们可以把分页相关的参数放置在这个类里面，如下：

3.2、逻辑方法调整

我们选择过滤与搜索时添加的ArticleService类中的GetArticles方法，在最终tolist前进行分页操作，如下：

4、进阶实现

4.1、说明

除了数据集合外，我们可以将前后页的链接，当前页码，当前页面的数量，总记录数，总页数等信息一并返回

返回的信息放在哪里也是一个问题，部分开发者习惯将上述信息放置在Http响应的Body中，虽然使用上没有任何问题，但是翻页信息不是资源表述的一部分，所以从RESTful风格看它破坏了自我描述性信息约束，API的消费者不知到如何使用application/json这个媒体类型来解释响应内容，而针对这类问题我们一般将此类信息放在Http响应Header的X-Pagination中

4.2、实现

1、首先我们在BlogSystem.Model项目中新建一个Helpers文件夹，并在其中新建一个PageList类，先将需要返回的翻页信息声明为属性，并在构造函数中初始化这些信息，信息对应的数据则由一个异步的静态方法提供，具体实现如下：

using System;

using System.Collections.Generic;

using System.Linq;

using System.Threading.Tasks;

using Microsoft.EntityFrameworkCore;

namespace BlogSystem.Model.Helpers

{

    public class PageList<T> : List<T>

    {

        //当前页码

        public int CurrentPage { get; }

        //总页码数

        public int TotalPages { get; }

        //每页数量

        public int PageSize { get; }

        //结果数量

        public int TotalCount { get; }

        //是否有前一页

        public bool HasPrevious => CurrentPage > 1;

        //是否有后一页

        public bool HasNext => CurrentPage < TotalPages;

        //初始化翻页信息

        public PageList(List<T> items, int count, int pageNumber, int pageSize)

        {

            TotalCount = count;

            PageSize = pageSize;

            CurrentPage = pageNumber;

            TotalPages = (int)Math.Ceiling(count / (double)pageSize);

            AddRange(items);

        }

        //创建分页信息

        public static async Task<PageList<T>> CreatePageMsgAsync(IQueryable<T> source, int pageNumber, int pageSize)

        {

            var count = await source.CountAsync();

            var items = await source.Skip((pageNumber - 1) * pageSize).Take(pageSize).ToListAsync();

            return new PageList<T>(items, count, pageNumber, pageSize);

        }

    }

}

2、我们将IArticleService中的GetArticles方法的返回值，以及ArticelService中的GetArticle方法修改如下：

Task<PageList<ArticleListViewModel>> GetArticles(ArticleParameters parameters);

3、当前页的前一页和后一页的链接信息如何获得？我们可以借助Url类的link方法，前提是对应的方法有它自身的名字，将ArticleController中的GetArticles方法命个名，并添加名字为CreateArticleUrl的方法来生成link，具体实现如下；其中UriType是一个枚举类型，我们将它放在了Model层的Helpers文件夹下

namespace BlogSystem.Model.Helpers

{

    public enum UrlType

    {

        PreviousPage,

        NextPage

    }

}

        //返回前一页面，后一页，以及当前页的url信息

        private string CreateArticleUrl(ArticleParameters parameters, UrlType type)

        {

            var isDefined = Enum.IsDefined(typeof(DistanceTime), parameters.DistanceTime);

            switch (type)

            {

                case UrlType.PreviousPage:

                    return Url.Link(nameof(GetArticles), new

                    {

                        pageNumber = parameters.PageNumber - 1,

                        pageSize = parameters.PageSize,

                        distanceTime = isDefined ? parameters.DistanceTime.ToString() : null,

                        searchStr = parameters.SearchStr

                    });

                case UrlType.NextPage:

                    return Url.Link(nameof(GetArticles), new

                    {

                        pageNumber = parameters.PageNumber + 1,

                        pageSize = parameters.PageSize,

                        distanceTime = isDefined ? parameters.DistanceTime.ToString() : null,

                        searchStr = parameters.SearchStr

                    });

                default:

                    return Url.Link(nameof(GetArticles), new

                    {

                        pageNumber = parameters.PageNumber,

                        pageSize = parameters.PageSize,

                        distanceTime = isDefined ? parameters.DistanceTime.ToString() : null,

                        searchStr = parameters.SearchStr

                    });

            }

        }

对应的Controller方法修改如下：

        /// <summary>

        /// 过滤/搜索文章信息并返回list和分页信息

        /// </summary>

        /// <param name="parameters"></param>

        /// <returns></returns>

        [HttpGet("search", Name = nameof(GetArticles))]

        public async Task<IActionResult> GetArticles([FromQuery]ArticleParameters parameters)

        {

            var list = await _articleService.GetArticles(parameters);

            var previousPageLink = list.HasPrevious ? CreateArticleUrl(parameters, UrlType.PreviousPage) : null;

            var nextPageLink = list.HasNext ? CreateArticleUrl(parameters, UrlType.NextPage) : null;

            var paginationX = new

            {

                totalCount = list.TotalCount,

                pageSize = list.PageSize,

                currentPage = list.CurrentPage,

                totalPages = list.TotalPages,

                previousPageLink,

                nextPageLink

            };

            Response.Headers.Add("Pagination-X", JsonSerializer.Serialize(paginationX));

            return Ok(list);

        }

4.3、实现效果

如下图，可以看到Header中多了一行名为Pagination-X的key，且对应value中存在下一页的url，但是系统默认进行了转义&符号无法正常显示，所以这里我们在传入Header时做如下处理

Response.Headers.Add("Pagination-X", JsonSerializer.Serialize(paginationX, new JsonSerializerOptions

{

    Encoder = JavaScriptEncoder.UnsafeRelaxedJsonEscaping

}));

三、排序

1、排序说明

通常情况下我们会使用QueryString针对多个字段为集合资源进行排序，字段默认为正序，也可以添加desc改变为倒序

2、实际应用

实际应用中字段对应的通常是Dto或ViewModel的字段而非数据库字段，所以可能会存在数据映射的问题；
目前我们只能使用属性名所对应的字符串进行排序，而不是使用lambda表达式；这里我们可以借助Linq的扩展库来解决这个问题，只要Dto/VieModel中存在这个字段，就进行排序，避免我们手动去匹配字符串的对应关系
此外我们需要考虑复用性的问题，可以针对IQueryable新增一个排序的扩展方法

3、一般实现

不考虑上述说明，进行最简单的排序方法

这里我们还是使用ArticleController进行演示，先在Model层Parameters文件夹的ArticleParameters文件中添加排序属性，这里我们添加一项为创建时间，如下：public string Orderby { get; set; } = "CreateTime";
在BLL层的ArticleService的GetArticles方法中添加实如下逻辑，即可完成一般排序

4、进阶实现

一般方法只能实现最简单的一种排序且无法复用，不灵活，下面我们自定义方法实现第一二点中的功能

1、先来看一下具体的实现思路，左边为层级关系，右边为需要实现的类；如果有点晕可以先敲完再完再回头看

2、由于逻辑相对复杂，所以在BlogSystem.Common层的Helpers文件夹中再建立一个SortHelper文件夹；

3、在SortHelper文件夹下建立PropertyMapping类，用来定义属性之间的映射关系，如下：

using System;

using System.Collections.Generic;

namespace BlogSystem.Common.Helpers.SortHelper

{

    //定义属性之间的映射关系

    public class PropertyMapping

    {

        //针对可能出现的一对多的情况——如name对应的是firstName+lastName

        public IEnumerable<string> DestinationProperties { get; set; }

        //针对出生日期靠前但是对应年龄大的情况

        public bool Revert { get; set; }

        public PropertyMapping(IEnumerable<string> destinationProperties, bool revert = false)

        {

            DestinationProperties = destinationProperties ?? throw new ArgumentNullException(nameof(destinationProperties));

            Revert = revert;

        }

    }

}

4、在SortHelper文件夹下建立ModelMapping类，用来定义两个类之间的映射关系，如下：

using System;

using System.Collections.Generic;

namespace BlogSystem.Common.Helpers.SortHelper

{

    //定义模型对象之间的映射关系，如xxx对应xxxDto

    public class ModelMapping<TSource, TDestination>

    {

        public Dictionary<string, PropertyMapping> MappingDictionary { get; private set; }

        public ModelMapping(Dictionary<string, PropertyMapping> mappingDictionary)

        {

            MappingDictionary = mappingDictionary ?? throw new ArgumentNullException(nameof(mappingDictionary));

        }

    }

}

5、在SortHelper文件夹下建立PropertyMappingService类，里面是针对属性映射情况的逻辑处理；但在使用ModelMapping时发现无法解析泛型类型，所以我们需要使用一个空的接口来为其打上标签。如下，新增空接口，添加ModelMapping继承此接口：

namespace BlogSystem.Common.Helpers.SortHelper

{

    //标记接口，只用来给对象打上标签

    public interface IModelMapping

    {

    }

}

PropertyMappingService类的实现如下：

using BlogSystem.Model;

using BlogSystem.Model.ViewModels;

using System;

using System.Collections.Generic;

using System.Linq;

namespace BlogSystem.Common.Helpers.SortHelper

{

    //属性映射处理

    public class PropertyMappingService

    {

        //一个只读属性的字典，里面是Dto和数据库表字段的映射关系

        private readonly Dictionary<string, PropertyMapping> _articlePropertyMapping

            = new Dictionary<string, PropertyMapping>(StringComparer.OrdinalIgnoreCase) //忽略大小写

            {

                {"Id",new PropertyMapping(new List<string>{"Id"}) },

                {"Title",new PropertyMapping(new List<string>{"Title"}) },

                {"Content",new PropertyMapping(new List<string>{"Content"}) },

                {"CreateTime",new PropertyMapping(new List<string>{"CreateTime"}) }

            };

        //需要解决ModelMapping泛型关系无法建立问题，可新增的一个空的标志接口

        private readonly IList<IModelMapping> _propertyMappings = new List<IModelMapping>();

        //构造函数——内部添加的是类和类的映射关系以及属性和属性的映射关系

        public PropertyMappingService()

        {

            _propertyMappings.Add(new ModelMapping<ArticleListViewModel, Article>(_articlePropertyMapping));

        }

        //通过两个类的类型获取映射关系

        public Dictionary<string, PropertyMapping> GetPropertyMapping<TSource, TDestination>()

        {

            var matchingMapping = _propertyMappings.OfType<ModelMapping<TSource, TDestination>>();

            var propertyMappings = matchingMapping.ToList();

            if (propertyMappings.Count == 1)

            {

                return propertyMappings.First().MappingDictionary;

            }

            throw new Exception($"无法找到唯一的映射关系：{typeof(TSource)},{typeof(TDestination)}");

        }

    }

}

6、最后由于需要通过依赖注入的方式进行使用，所以需要新增一个接口，添加PropertyMappingService继承此接口：

using System.Collections.Generic;

namespace BlogSystem.Common.Helpers.SortHelper

{

    //实现依赖注入新建的接口——对应的是属性映射服务

    public interface IPropertyMappingService

    {

        Dictionary<string, PropertyMapping> GetPropertyMapping<TSource, TDestination>();

    }

}

7、针对IQueryable新增一个排序的扩展方法IQueryableExtensions，放在Common层的SortHelper文件夹中，最后orderby时需要使用NuGet包安装System.Linq.Dynamic.Core，并引入命名空间，如下：

using System;

using System.Collections.Generic;

using System.Linq;

using System.Linq.Dynamic.Core;

namespace BlogSystem.Common.Helpers.SortHelper

{

    //排序扩展方法

    public static class IQueryableExtensions

    {

        public static IQueryable<T> ApplySort<T>(this IQueryable<T> source, string orderBy, Dictionary<string, PropertyMapping> mappingDictionary)

        {

            if (source == null)

            {

                throw new ArgumentNullException(nameof(source));

            }

            if (mappingDictionary == null)

            {

                throw new ArgumentNullException(nameof(mappingDictionary));

            }

            if (string.IsNullOrWhiteSpace(orderBy))

            {

                return source;

            }

            //分隔orderby字段

            var orderByAfterSplit = orderBy.Split(",");

            foreach (var orderByClause in orderByAfterSplit.Reverse())

            {

                var trimmedOrderByClause = orderByClause.Trim();

                //判断是否以倒序desc结尾

                var orderDescending = trimmedOrderByClause.EndsWith(" desc");

                //获取空格的索引

                var indexOfFirstSpace = trimmedOrderByClause.IndexOf(" ", StringComparison.Ordinal);

                //根据有无空格获取属性

                var propertyName = indexOfFirstSpace ==

                    -1 ? trimmedOrderByClause : trimmedOrderByClause.Remove(indexOfFirstSpace);

                //不含映射则抛出错误

                if (!mappingDictionary.ContainsKey(propertyName))

                {

                    throw new ArgumentNullException($"没有找到Key为{propertyName}的映射");

                }

                //否则取出属性映射关系

                var propertyMappingValue = mappingDictionary[propertyName];

                if (propertyMappingValue == null)

                {

                    throw new ArgumentNullException(nameof(propertyMappingValue));

                }

                //一次取出属性值进行排序

                foreach (var destinationProperty in propertyMappingValue.DestinationProperties.Reverse())

                {

                    if (propertyMappingValue.Revert)

                    {

                        orderDescending = !orderDescending;

                    }

                    //orderby需要安装System.Linq.Dynamic.Core库

                    source = source.OrderBy(destinationProperty + (orderDescending ? " descending" : " ascending"));

                }

            }

            return source;

        }

    }

}

8、在BlogSystem.BLL中的ArticleService类构造函数中注入IPropertyMappingService接口，如下：

9、在ArticleService中使用新增的IQueryable扩展方法实现排序逻辑，如下：

10、在BlogSystem.Core的StartUp类的ConfigureServices方法进行注册，这里我添加在的位置是方法内部的最后位置：

//自定义判断属性隐射关系

services.AddTransient<IPropertyMappingService, PropertyMappingService>();

11、运行后可以通过QueryString的形式，比如：?orderby=createtime或者?orderby=createtime desc或者orderby=createtime desc,title之类的形式进行排序查询（实际上createtime和title的组合无意义，可根据实际情况使用），如下：

5、进阶问题解决

1、在进行分页操作时我们有添加前后页的信息，但是在排序后，前后页面信息是不包括排序信息的，所以我们需要解决这一问题，在ArticleController中的CreateArticleUrl创建的3个Url中添加 orderBy = parameters.Orderby即可；

2、此外我们发现，输入一个不存在的排序字段时虽然弹出了我们预先添加的错误提示，错误代码却是500，但是这一错误并不是服务端引起的，在Common层的PropertyMappingService类中添加判断字段是否存在的逻辑。此外需要在PropertyMappingService对应的接口IPropertyMappingService中添加这一方法，方法逻辑如下：

 		//判断字符串是否存在

        public bool PropertyMappingExist<TSource, TDestination>(string fields)

        {

            var propertyMapping = GetPropertyMapping<TSource, TDestination>();

            if (string.IsNullOrWhiteSpace(fields))

            {

                return true;

            }

            //查询字符串逗号分隔

            var fieldAfterSplit = fields.Split(",");

            foreach (var field in fieldAfterSplit)

            {

                var trimmedFields = field.Trim();//字段去空

                var indexOfFirstSpace = trimmedFields.IndexOf(" ", StringComparison.Ordinal);//获取字段中第一个空格的索引

                //空格不存在，则属性名为其本身，否则移除空格

                var propertyName = indexOfFirstSpace == -1 ? trimmedFields : trimmedFields.Remove(indexOfFirstSpace);

                //只要有一个字段对应不上就返回fasle

                if (!propertyMapping.ContainsKey(propertyName))

                {

                    return false;

                }

            }

            return true;

        }

3、完成上述操作后，在ArticleController的构造函数中注入该服务，并在GetArticles方法中添加判断

4、再次运行，可以发现前后页面信息中已经包括了排序信息，且遇到不存在的字段时也是正常返回客户端异常

本章完~

本人知识点有限，若文中有错误的地方请及时指正，方便大家更好的学习和交流。

本文部分内容参考了网络上的视频内容和文章，仅为学习和交流，视频地址如下：

solenovex，ASP.NET Core 3.x 入门视频

solenovex，使用 ASP.NET Core 3.x 构建 RESTful Web API

声明