什么是REST
REST 是 Representational State Transfer 的缩写. 它是一种架构的风格, 这种风格基于一套预约义的规则, 这些规则描述了网络资源是如何定义和寻址的.web
一个实现了REST这些规则的服务就叫作RESTful的服务.api
最先是由Roy Fielding提出的.浏览器
RPC 风格
/getUsers /getUser?id=1 /createUser /deleteUser?id=4 /updateUser?name=dave
上面这些节点是针对User的CRUD操做. 缓存
这种样式风格的web服务更倾向于叫作RPC风格的服务.服务器
在RPC的世界里, 节点仅仅就是能够在远程被触发的函数, 而在REST的世界里, 节点就是实体, 也叫作资源.网络
REST的原则/约束
REST有6大原则/约束, 每个原则都是对API有正面或负面影响的设计决定.架构
RESTful API 最关心的有这几方面: 性能, 可扩展性, 简洁性, 互操做性, 通信可见性, 组件便携性和可靠性.app
这些方面被封装在REST的6个原则里, 它们是: 框架
1. 客服端-服务端约束: 客户端和服务端是分离的, 它们能够独自的进化.async
2. 无状态: 客户端和服务段的通讯必须是无状态的, 状态应包含在请求里的. 也就是说请求里要包含服务端须要的全部的信息, 以便服务端能够理解请求并能够创造上下文.
3. 分层系统: 就像其它的软件架构同样, REST也须要分层结构, 可是不容许某层直接访问不相邻的层.
4. 统一接口: 这里分为4点, 他们是: 资源标识符(URI), 资源的操做(也就是方法Method, HTTP动词), 自描述的响应(能够认为是媒体类型Media-Type), 以及状态管理(超媒体做为应用状态的引擎 HATEOAS, Hypermedia as the Engine of Application State).
5. 缓存: 缓存约束派生于无状态约束, 它要求从服务端返回的响应必须明确代表是可缓存的仍是不可缓存的.
6. 按需编码: 这容许客户端能够从服务端访问特定的资源而无须知晓如何处理它们. 服务端能够扩展或自定义客户端的功能.
只有知足了这6个原则的系统才能够真正称得上是RESTful的, 其实大部分系统的RESTful API并非RESTful的, 但这样并不表明这些API就很差, 利弊须要开发人员去衡量.
Richardson 成熟度模型
Richardson 成熟度模型表明着你的API是否足够成熟, 分为4个级别, 0表明最差, 3表明最好.
0级, 天花沼泽:
这里HTTP协议只是被用来进行远程交互, 协议的其他部分都用错了, 都是RPC风格的实现(例如SOAP, 尤为是使用WCF的时候).
例如:
POST (查询数据信息) http://host/myapi POST (建立数据) http://host/myapi
1级, 资源:
这级里, 每一个资源都映射到一个URI上了, 可是HTTP方法并无正确的使用, 结果的复杂度不算过高.
例如这两个查询:
POST
http://host/api/authors
POST
http://host/api/authors/{id}
2级, 动词:
正确使用了HTTP动词, 状态码也正确的使用了, 同时也去掉了没必要要的变种.
例如:
GET http://host/api/authors 200 Ok (authors) POST (author representation) http://host/api/authors 201 Created (author)
3级, 超媒体:
API支持超媒体做为应用状态的引擎 HATEOAS, Hypermedia as the Engine of Application State, 引入了可发现性.
例如:
GET http://host/api/authors 200 Ok (返回了authors 和 驱动应用程序的超连接)
介绍ASP.NET Core
略.
可是, 你须要知道如下概念: .NET Core, .NET Standard.
还须要会使用下列工具: .NET Core CLI, Visual Studio 2017/Visual Studio Code/Visual Studio for Mac
ASP.NET Core 支持建立Web API, 但并非直接支持RESTful的 Web API.
ASP.NET Core的基本知识
这部分仍是须要简单的介绍下, 若是已经会了, 请略过本文其他部分.
建立ASP.NET Core项目
打开VS2017, 选择ASP.NET Core Web Application项目模板, 写好名字, OK.
选择空模板, OK:
项目创建好了, 结果以下:
而后咱们看一下项目文件, 右键编辑MyRestful.Api:
这里, SDK属性表示了咱们使用的是哪一个SDK, 而目标框架是.NET Core 2.0.
(提示: 若是须要指向多个目标框架的话可使用TargetFrameworks元素, 注意多了个s)
看一下Program.cs:
Main方法是程序的入口. 而Web的宿主是经过BuildWebHost函数来实例化的, 它调用了WebHost.CreateDefaultBuilder方法, 很明显这是一个建造者模式, 它最终会构建出一个web宿主.
调用WebHost.CreateDefaultBuilder会返回一个IWebHostBuilder, 它容许咱们进行一些配置动做.
程序启动
UseStartup方法会注册一个类, 这个类负责配置整个程序的启动过程. 这里默认用的是Startup类.
Startup类有两个方法 ConfigureServices (这个能够没有) 和 Configure (这个必须有):
在Configure方法里, 配置应该遵循Add/Use的风格样式, 首先定义须要什么, 而后定义如何使用它.
而在ConfigureServices方法里, 全部程序级的依赖项均可以在这里注册到默认的IoC容器里, 把它们添加到IServiceCollection便可.
Configure方法才是真正负责配置HTTP请求管道的方法, 而且运行时也须要它.
IApplicationBuilder的扩展方法Run会传递一个RequestDelegate, 其内部功能就是回写Hello World.
ASP.NET Core还容许咱们按约定为指定环境创建单独的启动配置. 启动类能够经过这个函数定义UseStartup(startupAssemblyName: xxx); 运行时会在这个指定的组件查找叫作Startup, Startup[环境名]的类, 其中[环境名]就是ASPNETCORE_ENVIRONMENT这个环境变量的值. 若是能找到指定环境的类, 那么它将覆盖默认的启动类.
例如 环境变量值若是是Developmen的话, 那么运行时就会尝试寻找Startup和StartupDevelopment类, 该约定在启动类里面的方法名上也有效, 环境特定的启动类里的两个方法分别是 Configure[环境名]和Configure[环境名]Services.
除了以前讲的Run方法外, IApplicationBuilder还有一个Use扩展方法.
Use扩展方法接受RequestDelegate做为参数来提供HttpContext, 同时接受也为下一层准备的RequestDelegate参数.
须要注意的是, Run方法和Use方法定义的顺序很是重要, 运行时将会精确的按照建立的顺序来执行.
服务器
ASP.NET Core 服务器的做用是响应客户端发过来的请求, 这些请求会做为HttpContext传递进来. ASP.NET Core 内置两种服务器:
Kestrel, 它是跨平台的服务器, 基于Libuv.
HTTP.sys, 它是仅限Windows系统的服务器, 基于HTTP.sys内核驱动.
下面就是从客户端发请求到应用程序的流图:
其中Kestrel能够做为一个独立进程自行托管, 也能够在IIS里. 可是仍是建议使用IIS或Nginx等做为反向代理服务器. 在构建API或微服务时, 这些服务器能够做为网关使用, 由于它们会限制对外暴露的东西也能够更好的与现有系统集成, 因此它们会提供额外的防护层,
使用反向代理服务器(IIS)以后的流图以下:
让web宿主工做于IIS以后须要使用IWebHostBuilder的UseIISIntegration这个扩展方法.
除了内置的两种服务器, 您还可使用自定义的服务器, 使用IWebHostBuilder的UserServer扩展方法, 它接受一个实现了IServer接口的实例, 您的自定义服务器须要实现该接口. 这里就不讲了.
中间件
在应用程序请求管道内装配的组件就是中间件, 它们负责处理经过管道的请求和响应.
在HTTP请求管道的上下文里, 中间件能够叫作请求委托, 它们是由Run, Map 和 Use 扩展方法共同组建而成的.
每一个中间件能够在它被调用以前和以后执行可选的逻辑, 同时也能够决定该请求是否能够被送到管道的下一个中间件那里.
请求在中间件里的流图以下:
看一下这个例子:
若是我在浏览器地址输入 http://localhost:5000/return, 那么结果就是Returned!
若是输入 http://localhost:5000/end, 那么是The End.
若是输入 http://localhost:5000/xxx?value=1234, 结果是 the number is 1234
若是输入 http://localhost:5000/xxx?value=abcde, 结果是 Hello, the value is abcde!
注意: 应用程序管道里的请求委托(中间件)定义的顺序是很是重要的, 请求的时候按定义的顺序执行, 而响应的顺序正好相反.
中间件最好不要像上面同样写在Startup类里, 每一个中间件应该放在单独的类里.
我把上例中检查是否为数字的中间件写在一个单独的类里:
这种中间件没有实现特定的接口或者继承特定类, 它更像是Duck Typing (你走起路来像个鸭子, 叫起来像个鸭子, 那么你就是个鸭子).
而后在Startup的Configure方法里调用app.UseMiddleware<NumberMiddleware>()便可:
路由
在ASP.NET Core里,使用路由中间件RouterMiddleware来处理路由.
想要使用路由, 一样也是遵循 Add/Use 这个模式.
首先在ConfigureServices方法里添加(Add):
而后在Configure方法里使用(Use):
UseRouter这个扩展方法能够接受IRouter或者Action<IRouterBuilder>做为参数.
例如:
当发送 http://localhost:5000/ GET请求的时候, 返回 Default route.
当 GET http://localhost:5000/user/dave的时候, 返回 Hi dave
当 POST http://localhost:5000/user/dave的时候, 返回 Hi, posted name is dave
其中{name}, 是名为name的参数.
若是写成"user/{name}/{age:number}", 那么age这个参数的必须能够被解析为数值型.
而"user/{name}/{gender?}", 这里的gender参数能够没有.
Controller
HTTP请求经过管道最终到达Action并返回的流图以下：
默认状况下Controller放在ASP.NET Core项目的Controllers目录下。
在ASP.NET Core项目里能够经过多种方式来建立Controller，固然最建议的方式仍是经过继承AspNetCore.Mvc.Controller这个抽象类来创建Controller。
例如：
上例中类名能够不是以Controller结尾。
还有其它的方式建立Controller，按约定类名以Controller结尾的POCO类也会被认为是Controller，例如：
针对POCO类， 即便名称不是以Controller结尾，仍然能够把它做为Controller，这就须要在类上面添加 [Controller] 这个属性：
若是某个类的名字以Controller结尾， 可是你不想把它看成Controller，那么就应该为该类标注 [NonController] 这个属性：
实际上， 看源码就能够知道 Controller 继承于 ControllerBase:
而ControllerBase上面标注着 [Controller] 属性。
Action
在Controller里面，可使用public修饰符来定义Action，一般会带有参数，能够返回任何类型，可是大多数状况下应该返回IActionResult。Action的方法名要么是以HTTP的动词开头，要么是使用HTTP动词属性标签，包括：[HttpGet], [HttpPut], [HttpPost], [HttpDelete], [HttpHead], [HttpOptions], [HttpPatch].
例如：
其中某个方法名若是刚好是以HTTP的动词开头，那么能够经过标注 [NonAction] 属性来表示这个方法不是Action。
经过继承Controller基类的方法来建立Controller仍是有不少好处的，由于它提供了不少帮助方法，例如：Ok, NotFound, BadRequest等，它们分别对应HTTP的状态码 200, 404, 400；此外还有Redirect，LocalRedirect，RedirectToRoute，Json，File，Content等方法。
为MVC定义路由有两种方式：使用IRouteBuilder或者使用基于属性标签的路由。针对Rest，最好仍是使用基于属性标签的方式。
路由属性标签能够标注在Controller或者Action方法上，例如：
Controller类上标注的路由“api/[controller]”，其中[controller] 就表明该类的名字去掉结尾Controller的部分，也就是“api/person”。
在Controller上使用[Route]属性就定义了该Controller下全部Action的路由基地址，每一个Action能够包含一个或者多个相对的路由模板（地址），这些路由模板能够在[Http...]中定义。可是若是使用 ~ 这个符号的话，该Action的地址将会是绝对路由地址，也就是覆盖了Controller定义的基路由。
实体绑定
传入的请求会映射到Action方法的参数，能够实原始数据类型也能够是复杂的类型例如Dto（data transfer object）或ViewModel。这个把Http请求绑定到参数的过程叫作实体绑定。
例如：
其中id参数是定义在路由里的，而name参数在路由里没有，可是仍然能够从查询参数中把name参数映射出来。
注意路由参数和查询参数的区别，下面这个URL里val1和val2是查询参数，它们是在url的后边使用?和&分隔：
/product?val1=2&val2=10
而针对上面的Action，下面这个URL的路由参数id就是123：
/api/first/123
针对下面这个POST Action：
咱们能够经过几种方式为其传递类型为Person的参数。
可使用查询参数：/api/people?id=1&name=Dave
若是POST Json数据：
那么在Action里面获得的参数person的属性值都是null。这是由于这样的原始数据是包含在请求的Body里面，为了解决这个问题，你须要告诉Action从哪里获取参数，针对这个例子就应该使用 [FromBody] 属性标签：
若是提交的是表单数据，那么就应该使用[FromForm]:
其它的出处还有 [FromHeader], [FromRoute], [FromServices]等。
再看一个FromHeader的例子：
若是使用复杂类型Person来获取person参数好像不行，只能使用原始类型的吧？
实体验证
ASP.NET Core内置的实体验证是经过验证属性标签来实现的，大多数状况下这样会很方便。
例如：
其中Display不是验证标签，可是经过它能够自定义属性的显式名称，在其它错误信息里可使用{0}来引用该名称。
判断实体参数是否符合要求，能够检查ModelState.IsValid属性，这个属性也是由ControllerBase提供的，例如：
发送一个请求：
这是个不合理的参数，返回的是400 BadRequest，带着验证结果：
尽管大多数状况西，验证属性标签都知足要求，可是有时候仍是须要进行一些灵活的验证，你可使用像FluentValidation这样的第三方库，也可使用内置的方式来实现自定义验证。
ASP.NET Core内置支持两种方式来进行自定义验证：经过继承ValidationAttribute来建立自定义验证属性标签，或者让实体实现IValidatebleObject接口。
使用自定义验证属性标签：
把该标签放到name属性上
使用刚才的请求，其结果是：
另外一种方式，在Person类实现IValidatableObject接口
可是我使用这种方法并很差用，不知道我哪里用错了！
过滤器
和中间件同样，ASP.NET Core MVC的过滤器也能够在请求管道的特定阶段的以前或以后执行某些代码。过滤器还能够有子管道，子管道里面包含着其它过滤器。
过滤器和中间件的区别：中间件是应用程序级别的，它能够处理每一个发送过来的请求；而过滤器是针对MVC的，它只会处理发往MVC的请求。
ASP.NET Core MVC的过滤器分为5类：
- 受权过滤器，它是第一个运行的，它的做用就是判断HTTP Context中的用户是否拥有当前请求的权限，若是用户没有权限，那么它就会“短路”管道。
- 资源过滤器，在受权过滤器后运行，在管道其它动做以前，和管道动做都结束后运行。它能够实现缓存或因为性能缘由执行短路操做。它在实体绑定以前运行，因此它也能够对影响实体绑定。
- Action过滤器，它在Action方法调用以前和以后当即执行，它能够操做传进Action的参数和返回的结果。
- 异常过滤器，针对在写入响应Body以前发生的未处理的异常，它能够应用全局的策略，
- 结果过滤器，它能够在每一个Action结果执行以前和以后运行代码，但也只是在Action方法无错误的成功完成后才能够执行。
下图标明了这些过滤器在管道中是如何交互的：
过滤器能够做为属性标签使用，或者也能够在Startup类里面进行全局注册。
例子：
using System.Threading.Tasks;
using Microsoft.AspNetCore.Mvc.Filters;
namespace MyRestful.Api.Filters
{
public class DefaultNameFilter: IActionFilter, IAsyncActionFilter
{
public void OnActionExecuting(ActionExecutingContext context)
{
context.ActionDescriptor.RouteValues["name"] = "Anonymous";
}
public void OnActionExecuted(ActionExecutedContext context)
{
context.HttpContext.Response.Headers["X-Name"] = context.ActionDescriptor.RouteValues["name"];
}
public async Task OnActionExecutionAsync(ActionExecutingContext context, ActionExecutionDelegate next)
{
OnActionExecuting(context);
var result = await next();
OnActionExecuted(result);
}
}
}
全局注册，在Startup里：
public void ConfigureServices(IServiceCollection services)
{
services.AddMvc(options =>
{
options.Filters.Add<DefaultNameFilter>();
});
}
或者自定义一个属性标签，内部的代码是同样的：
using System;
using System.Threading.Tasks;
using Microsoft.AspNetCore.Mvc.Filters;
namespace MyRestful.Api.Filters
{
public class DefaultUserNameFilterAttribute: Attribute, IActionFilter, IAsyncActionFilter
{
public void OnActionExecuting(ActionExecutingContext context)
{
context.ActionDescriptor.RouteValues["name"] = "Anonymous";
}
public void OnActionExecuted(ActionExecutedContext context)
{
context.HttpContext.Response.Headers["X-Name"] = context.ActionDescriptor.RouteValues["name"];
}
public async Task OnActionExecutionAsync(ActionExecutingContext context, ActionExecutionDelegate next)
{
OnActionExecuting(context);
var result = await next();
OnActionExecuted(result);
}
}
}
而后把该标签用在Action方法上便可：
[DefaultUserNameFilter]
[HttpGet("first/{id}")]
public IActionResult FindFirstPerson(int id, string name)
{
return null;
}
格式化响应结果
Action的结果最好使用IActionResult, 但也可使用其余类型，例如IEnumerable<T>等。强制结果输出为特定的类型能够经过调用特定的方法来实现，例如JsonResponse就是输出JSON，ContentResponse就是输出文本。另外也可使用[Produces(xxx)] 这个过滤器，它能够应用于全局，controller或者Action。
在REST服务里，有个词叫内容协商，它表示客户端经过Accept Header里的media-type来指定所需的结果格式。
ASP.NET Core MVC 默认实现并使用JSON格式化，但也支持其它格式，这须要在startup里面注册。
客户端浏览器可能在请求的Accept Headers里提供了多种的格式，可是ASP.NET Core MVC 默认是忽略浏览器的Accept Header的，并使用标准的输出格式。可是修改MvcOptions的RespectBrowserAcceptHeader值为true，能够改变这个行为:
ASP.NET Core还提供了 XML 格式，能够在MvcOptions里面添加：
今天先写到这，尚未切入正题。