上一篇我们介绍了过滤与搜索、分页与排序，并在一个控制器方法中完成了对应功能的添加；本章我们将介绍数据塑形与HATEOAS的概念，并添加对应的功能
注：本章内容大多是基于solenovex的使用 ASP.NET Core 3.x 构建 RESTful Web API视频内容，若想进一步了解相关知识，请查看原视频
一、数据塑形
1、定义介绍
数据塑形就是指API用户自由地选择自己需要的字段。举个例子，若一个Dto/ViewModel中存在很多字段，但API用户只需要其中的几个，那我们返回API用户需要的字段就可以了，不需要全部返回。通常情况下我们会添加一个数据塑形字段如fields，并采用QueryString的形式让API用户选择所需字段，如/api/article?fields=title,content
2、集合资源实现
1、这里还是以ArticleController控制器中的GetArticles方法做示例，其对应ArticleService中的逻辑方法返回的是ArticleListViewModel，这里我们需要将其改变为动态类型ExpandoObject，这里我们需要针对IEnumerable进行方法的扩展。我们在Commen层的Helpers文件夹中添加一个名为IEnumerableExtensions的类，实现逻辑如下：
using System;
using System.Collections.Generic;
using System.Dynamic;
using System.Linq;
using System.Reflection;
namespace BlogSystem.Common.Helpers
{
//数据塑形——针对集合的扩展方法
public static class IEnumerableExtensions
{
public static IEnumerable ShapeDataList(this IEnumerable source, string fields)
{
if (source == null)
{
throw new ArgumentNullException(nameof(source));
}
var expandoObjectList = new List(source.Count());
var propertyInfoList = new List();
//field无字段则反射全部
if (string.IsNullOrWhiteSpace(fields))
{
var propertyInfos = typeof(TSource).GetProperties(BindingFlags.Public | BindingFlags.Instance);
propertyInfoList.AddRange(propertyInfos);
}
else //field有字段则去除空格并判断后添加至list
{
var fieldAfterSplit = fields.Split(",");
foreach (var field in fieldAfterSplit)
{
var propertyName = field.Trim();
var propertyInfo =
typeof(TSource).GetProperty(propertyName, BindingFlags.IgnoreCase
| BindingFlags.Public | BindingFlags.Instance);
if (propertyInfo == null)
{
throw new Exception($"Property:{propertyName}没有找到：{typeof(TSource)}");
}
propertyInfoList.Add(propertyInfo);
}
}
foreach (TSource obj in source)
{
var shapedObj = new ExpandoObject();
//根据获取的属性额值添加到shapedObj中
foreach (var propertyInfo in propertyInfoList)
{
var propertyValue = propertyInfo.GetValue(obj);
((IDictionary)shapedObj).Add(propertyInfo.Name, propertyValue);
}
expandoObjectList.Add(shapedObj);
}
return expandoObjectList;
}
}
}
2、另外，我们需要在Model层的ArticleParameters类中添加属性字段public string Fields { get; set; }
3、在最终的实现层ArticleController的GetArticles方法中，将最终返回的list修改如下：
return Ok(list.ShapeDataList(parameters.Fields));
4、同样需要考虑到将生成的三个分页url中加入对应的field字段 fields=parameters.Fields
5、在field中录入希望得到的字段信息，实现效果如下：
3、单个资源实现
1、这里以ArticleController控制器中的GetArticleByArticleId方法做示例，我们需要针对ExpandoObject进行方法的扩展。我们在Commen层的Helpers文件夹中添加一个名为ObjectExtensions的类，实现逻辑与集合资源类似，但是出于性能的考虑，集合资源是将属性信息单独提取出来进行处理，而单个资源则是依次进行判断处理，具体实现如下：
using System;
using System.Collections.Generic;
using System.Dynamic;
using System.Reflection;
namespace BlogSystem.Common.Helpers
{
//数据塑形——单个资源
public static class ObjectExtensions
{
public static ExpandoObject ShapeData(this TSource source, string fields)
{
if (source == null)
{
throw new ArgumentNullException(nameof(source));
}
var expandoObj = new ExpandoObject();
if (string.IsNullOrWhiteSpace(fields))
{
var propertyInfos = typeof(TSource).GetProperties(BindingFlags.Public | BindingFlags.IgnoreCase |
BindingFlags.Instance);
foreach (var propertyInfo in propertyInfos)
{
var propertyValue = propertyInfo.GetValue(source);
((IDictionary)expandoObj).Add(propertyInfo.Name, propertyValue);
}
}
else
{
var fieldAfterSplit = fields.Split(",");
foreach (var field in fieldAfterSplit)
{
var propertyName = field.Trim();
var propertyInfo =
typeof(TSource).GetProperty(propertyName, BindingFlags.IgnoreCase
| BindingFlags.Public | BindingFlags.Instance);
if (propertyInfo == null)
{
throw new Exception($"在{typeof(TSource)}上没有找到{propertyName}这个属性");
}
var propertyValue = propertyInfo.GetValue(source);
((IDictionary)expandoObj).Add(propertyInfo.Name, propertyValue);
}
}
return expandoObj;
}
}
}
2、ArticleController控制器中的GetArticleByArticleId修改如下：
3、实现效果如下
4、异常处理
1、这里我们发现，在输入不存在的字段时，虽然会返回错误提示，但是错误代码为500，这显然是不合理的，这个是客户端引起的错误，应当返回4xx错误。我们在Commen层的Helpers文件夹中添加一个名为PropertyCheckService的类，并定义名为IPropertyCheckService的接口，以达到复用的效果，实现逻辑如下：
using System.Reflection;
namespace BlogSystem.Common.Helpers
{
//判断字段是否存在的服务
public class PropertyCheckService : IPropertyCheckService
{
public bool TypeHasProperties(string fields)
{
if (string.IsNullOrWhiteSpace(fields))
{
return true;
}
var fieldAfterSplit = fields.Split(",");
foreach (var field in fieldAfterSplit)
{
var propertyName = field.Trim();
var propertyInfo =
typeof(T).GetProperty(propertyName, BindingFlags.IgnoreCase
| BindingFlags.Public | BindingFlags.Instance);
if (propertyInfo == null)
{
return false;
}
}
return true;
}
}
}
namespace BlogSystem.Common.Helpers
{
public interface IPropertyCheckService
{
bool TypeHasProperties(string fields);
}
}
2、在BlogSystem.Core项目的StartUp类的ConfigureServices方法中进行上面接口的注入，如下：services.AddTransient
3、在对应的ArticleController方法中进行接口的注入，在获取集合资源的方法中添加判断逻辑，如下：
在获取单个资源的方法中添加判断逻辑，如下：
5、其他说明
数据塑形功能还可以实现父子资源的联合查询，高级过滤等，实际应用中还是需要根据需求进行变化。上述我们只是从功能出发自定义实现，实际上我们可以使用已经实现并封装好了的插件，如微软的OData，有兴趣的朋友可以自行研究。
二、HATEOAS
1、定义介绍
HATEOAS的全程是Hypermedia As The Engine Of Application State，即超媒体作为应用程序状态引擎。它是作为REST统一界面约束中的一个子约束，是REST架构中最重要，最复杂的约束，也是构建成熟REST服务的核心。
它是REST的Richardson成熟度模型中最成熟的一个层次，达到一成熟的的API不仅在响应中包含资源，也包含与之相关的链接，这些链接不仅易于被发现，而且可以通过这些链接发现当前资源所支持的动作，这些动作又能驱动应用程序状态的改变。
2、实际应用
1、上面我们提到HATEOAS会在响应中包含链接，实际上我们正是通过这些链接告知客户端，服务端能提供哪些服务，客户端只需要检查这些链接即可。所以我们要做的就是展示这些link，而每个链接包含三个属性—href、rel和method
- href：用户可以检查资源或者改变应用状态的URL
- rel：描述href指向资源和现有资源的关系
- method：请求该URL要使用的HTTP方法
举个例子，当获取一本图书资源时，服务器能够判断该图书是否能够被借阅，如果可以，则链接中应当包含请求借阅的API的URL和HTTP方法
2、实现HATEOAS我们需要针对集合资源和单个资源进行不同的考虑，而实现方案有两种，静态类型方法和动态类型方案：
静态类型方案：返回的资源中全部包含link，通过继承同一个基类进行实现；
动态类型方案：使用匿名类或之前使用过的动态类型对象ExpandoObject实现，单个资源使用ExpandoObject，而集合资源使用匿名类
3、单个资源实现
这里我们采用动态类型方案进行实现，处理的对象是ArticleController类中的GetArticleByArticleId方法
1、首先我们在Modle层建立一个HATEOAS文件夹，里面添加一个LinkDto类，添加如下信息：
namespace BlogSystem.Model.HATEOAS
{
public class LinkDto
{
public string Href { get; }
public string Rel { get; }
public string Method { get; }
public LinkDto(string href, string rel, string method)
{
Href = href;
Rel = rel;
Method = method;
}
}
}
2、在ArticelController中添加创建link的方法CreateLinksForArticle，我们在内部添加了自身link和删除文章、编辑文章的link，前提是需要为方法命名，如 [Httpxxx(Name = nameof(xxx))]，实现逻辑如下：
//实现HATEOAS单个资源的简单方法
private IEnumerable CreateLinksForArticle(Guid articleId, string fields)
{
var links = new List();
if (string.IsNullOrWhiteSpace(fields))
{
links.Add(new LinkDto(Url.Link(nameof(GetArticleByArticleId), new { articleId }), "self", "Get"));
}
else
{
links.Add(new LinkDto(Url.Link(nameof(GetArticleByArticleId), new { articleId, fields }), "self", "Get"));
}
//删除文章的link
links.Add(new LinkDto(Url.Link(nameof(RemoveArticle), new { articleId, fields }), "delete_article need_auth", "DELETE"));
//编辑文章的link
links.Add(new LinkDto(Url.Link(nameof(EditArticle), new { articleId }), "edit_article need _auth", "PATCH"));
return links;
}
3、修改ArticleController类中的GetArticleByArticleId方法，如下：
4、实现效果，如下：
4、集合资源实现
1、同样我们在ArticelController中添加创建link的方法CreateLinksForArticles，该方法返回信息是包括分页信息及前后页信息的，所以我们要借助CreateArticleUrl方法，但是在返回当前页面信息时因为页面枚举类UrlType没有添加当前页，所以无法获取，修改枚举类，实现CreateLinksForArticles方法，如下：
namespace BlogSystem.Model.Helpers
{
public enum UrlType
{
PreviousPage,
NextPage,
CurrentPage
}
}
//实现HATEOAS集合资源的简单方法，将自身的前一页信息和后一页信息也放到headoas中
private IEnumerable CreateLinksForArticles(ArticleParameters parameters, bool hasPrevious, bool hasNext)
{
var links = new List();
links.Add(new LinkDto(CreateArticleUrl(parameters, UrlType.CurrentPage), "self", "GET"));
if (hasPrevious)
{
links.Add(new LinkDto(CreateArticleUrl(parameters, UrlType.PreviousPage), "Previous", "GET"));
}
if (hasNext)
{
links.Add(new LinkDto(CreateArticleUrl(parameters, UrlType.NextPage), "Next", "GET"));
}
return links;
}
2、主要注意的是集合类型的结果是每条记录都有其自身的HATEOAS，并且每条记录HATEOAS都应该有前后页的信息，所以我们要先删除之前添加的创建前后页面url的逻辑，如下：
3、修改ArticleController类中的GetArticles方法中返回结果的逻辑，实现如下：
4、实现效果如下图所示，集合自身添加前后分页信息，集合内部元素有自身支持方法的links
5、异常处理
可以发现集合资源与其内部元素是依靠articleId来建立联系的，如果使用数据塑形功能但是没有添加articleId字段，系统会产生异常，所以这里我们在数据塑形前加个判断逻辑，如下：
6、其他说明
1、在实际生产中，HATEOAS经常会与单页应用一起被提到，而单页应用往往会存在一个"根"页面。我们这里就不实现了，感兴趣的朋友可以自己研究下，本章一开始提到的视频内容中也是有实现过程的。
2、为方便大家更好的理解，我们从https://www.jianshu.com/p/ecd6a4a7a2e4摘抄了部分内容，如下：
前后端分离的开发模式进一步细化了分工，但同时也引入了不少重复的工作，例如一些业务规则在后端必须实现的情况下，前端也需要再实现一遍以获得更好的用户体验。HATEOAS虽然不是唯一消除这些重复的方法，但作为一种架构原则，它更容易让团队找到消除重复的“套路”。
在非HATOEAS的项目中，由于URI是在客户端硬编码的，即使你把它们设计的非常漂亮（准确的HTTP动词，以复数命名的资源，禁止使用动词等等），也不能帮助你更容易地修改它们，因为你的重构需要前端开发者的配合，而他/她不得不停下手头的其他工作。但在采用了HATEOAS的项目中，这很容易，因为客户端是通过Link来查找API的URI，所以你可以在不破坏API Scheme的情况下修改它的URI。当然，你不可能保证所有API的URI都是通过Link来获取的，你需要安排一些Root Resource，例如 /api/currentLoggedInUser，否则客户端没有办法发起第一次请求。
三、内容协商
1、定义介绍
在实现HATEOAS时，我们得到的返回结果是{values:[xx,xx,xx...],links:[xx,xx...]}格式的，它是相同资源的不同表述方式，所以服务器应当根据客户端请求的媒体类型(Media Type)返回与之对应的表述资源，否则将破坏自我描述性约束。
2、实际应用
这里我们应当创建一个新的媒体类型，来应对这类情况。通常我们会使用供应商特定媒体类型(Vendor-special media type)，缩写为application/vnd.companyName.hateoas+json
- vnd为Vendor的缩写，表示媒体类型是供应商特定的
- companyName为自定义的Vendor标识，通常为公司的名称，当然也可以包括额外的信息
- hateoas是媒体类型的名称，它表示返回的响应里面包含链接信息
- +json表示数据为Json格式，它会告知客户端应当如何处理响应信息
3、功能实现
1、这里我们处理的对象是ArticleController类中的GetArticleByArticleId方法，修改如下：
2、这里使用PostMan测试返回406错误，控制台显示没有对应的输出格式，所以这里我们在startup中添加全局的支持，如下：
3、最终实现如下：
4、其他说明
媒体类型的可以应用在不同的情况下，下面再介绍两种，这里就不实现了，感兴趣的朋友可以自己研究下，本章一开始提到的视频内容中也是有实现过程的。
4.1、Vendor-Specific Media Type输入
在上面的方法中，我们完成了根据特定的媒体类型输出不同表述数据的功能；实际上与之对应的还有输入功能的实现，我们通过设置Content-Type Header来接受不同的媒体类型的输入。比如说编辑文章功能，一般来说只是编辑文章内容，但是在一些情况下我们还希望可以更新创建时间CreateTime，也就是通过输入不同的媒体类型来实现不同的功能。
4.2、带有语义的媒体类型Semantic Media Types
我们还可以通过使用带有语义的媒体类型来告知API使用者数据的语义，比如说希望看到简洁数据和完整数据两类信息，就可以设置两个媒体类型，而不同的媒体类型则可以应对不同的数据结果。
本章完~
该项目源码已更新上传至GitHub，有需要的朋友可以下载使用：https://github.com/Jscroop/BlogSystem
本人知识点有限，若文中有错误的地方请及时指正，方便大家更好的学习和交流。
本文部分内容参考了网络上的视频内容和文章，仅为学习和交流，视频地址如下：
solenovex，ASP.NET Core 3.x 入门视频
solenovex，使用 ASP.NET Core 3.x 构建 RESTful Web API