工具:html
1.Visual Studio 2017 V15.3.5+linux
2.Postman (Chrome的App)nginx
3.Chrome (最好是)web
关于.net core或者.net core 2.0的相关知识就不介绍了, 这里主要是从头编写一个asp.net core 2.0 web api的基础框架.chrome
我一直在关注asp.net core 和 angular 2/4, 并在用这对开发了一些比较小的项目. 如今我感受是时候使用这两个技术去为企业开发大一点的项目了, 因为企业有时候须要SSO(单点登陆), 因此我一直在等待Identity Server4以及相关库的正式版, 如今匹配2.0的RC版已经有了, 因此这个能够开始编写了.apache
这个系列就是我从头开始创建我本身的基于asp.net core 2.0 web api的后台api基础框架过程, 估计得分几回才能写完. 若是有什么地方错的, 请各位指出!!,谢谢.json
建立项目:
1.选择asp.net core web application.windows
2.选择.net core, asp.net core 2.0, 而后选择Empty (由于是从头开始):设计模式
下面看看项目生成的代码:api
Program.cs
namespace CoreBackend.Api
{
public class Program
{
public static void Main(string[] args)
{
BuildWebHost(args).Run();
}
public static IWebHost BuildWebHost(string[] args) =>
WebHost.CreateDefaultBuilder(args)
.UseStartup<Startup>()
.Build();
}
}
这个Program是程序的入口, 看起来很眼熟, 是由于asp.net core application实际就是控制台程序(console application).
它是一个调用asp.net core 相关库的console application.
Main方法里面的内容主要是用来配置和运行程序的.
由于咱们的web程序须要一个宿主, 因此 BuildWebHost这个方法就建立了一个WebHostBuilder. 并且咱们还须要Web Server.
看一下WebHost.CreateDefaultBuilder(args)的源码:
public static IWebHostBuilder CreateDefaultBuilder(string[] args)
{
var builder = new WebHostBuilder()
.UseKestrel()
.UseContentRoot(Directory.GetCurrentDirectory())
.ConfigureAppConfiguration((hostingContext, config) =>
{
var env = hostingContext.HostingEnvironment;
config.AddJsonFile("appsettings.json", optional: true, reloadOnChange: true)
.AddJsonFile($"appsettings.{env.EnvironmentName}.json", optional: true, reloadOnChange: true);
if (env.IsDevelopment())
{
var appAssembly = Assembly.Load(new AssemblyName(env.ApplicationName));
if (appAssembly != null)
{
config.AddUserSecrets(appAssembly, optional: true);
}
}
config.AddEnvironmentVariables();
if (args != null)
{
config.AddCommandLine(args);
}
})
.ConfigureLogging((hostingContext, logging) =>
{
logging.AddConfiguration(hostingContext.Configuration.GetSection("Logging"));
logging.AddConsole();
logging.AddDebug();
})
.UseIISIntegration()
.UseDefaultServiceProvider((context, options) =>
{
options.ValidateScopes = context.HostingEnvironment.IsDevelopment();
});
return builder;
}
asp.net core 自带了两种http servers, 一个是WebListener, 它只能用于windows系统, 另外一个是kestrel, 它是跨平台的.
kestrel是默认的web server, 就是经过UseKestrel()这个方法来启用的.
可是咱们开发的时候使用的是IIS Express, 调用UseIISIntegration()这个方法是启用IIS Express, 它做为Kestrel的Reverse Proxy server来用.
若是在windows服务器上部署的话, 就应该使用IIS做为Kestrel的反向代理服务器来管理和代理请求.
若是在linux上的话, 可使用apache, nginx等等的做为kestrel的proxy server.
固然也能够单独使用kestrel做为web 服务器, 可是使用iis做为reverse proxy仍是由不少有点的: 例如,IIS能够过滤请求, 管理证书, 程序崩溃时自动重启等.
UseStartup<Startup>(), 这句话表示在程序启动的时候, 咱们会调用Startup这个类.
Build()完以后返回一个实现了IWebHost接口的实例(WebHostBuilder), 而后调用Run()就会运行Web程序, 而且阻止这个调用的线程, 直到程序关闭.
BuildWebHost这个lambda表达式最好不要整合到Main方法里面, 由于Entity Framework 2.0会使用它, 若是把这个lambda表达式去掉以后, Add-Migration这个命令可能就很差用了!!!
Startup.cs
namespace CoreBackend.Api
{
public class Startup
{
// This method gets called by the runtime. Use this method to add services to the container.
// For more information on how to configure your application, visit https://go.microsoft.com/fwlink/?LinkID=398940
public void ConfigureServices(IServiceCollection services)
{
}
// This method gets called by the runtime. Use this method to configure the HTTP request pipeline.
public void Configure(IApplicationBuilder app, IHostingEnvironment env)
{
if (env.IsDevelopment())
{
app.UseDeveloperExceptionPage();
}
app.Run(async (context) =>
{
await context.Response.WriteAsync("Hello World!");
});
}
}
}
其实Startup算是程序真正的切入点.
ConfigureServices方法是用来把services(各类服务, 例如identity, ef, mvc等等包括第三方的, 或者本身写的)加入(register)到container(asp.net core的容器)中去, 并配置这些services. 这个container是用来进行dependency injection的(依赖注入). 全部注入的services(此外还包括一些框架已经注册好的services) 在之后写代码的时候, 均可以将它们注入(inject)进去. 例如上面的Configure方法的参数, app, env, loggerFactory都是注入进去的services.
Configure方法是asp.net core程序用来具体指定如何处理每一个http请求的, 例如咱们可让这个程序知道我使用mvc来处理http请求, 那就调用app.UseMvc()这个方法就行. 可是目前, 全部的http请求都会致使返回"Hello World!".
这几个方法的调用顺序: Main -> ConfigureServices -> Configure
请求管道和中间件(Request Pipeline, Middleware)
请求管道: 那些处理http requests并返回responses的代码就组成了request pipeline(请求管道).
中间件: 咱们能够作的就是使用一些程序来配置那些请求管道 request pipeline以便处理requests和responses. 好比处理验证(authentication)的程序, 连MVC自己就是个中间件(middleware).
每层中间件接到请求后均可以直接返回或者调用下一个中间件. 一个比较好的例子就是: 在第一层调用authentication验证中间件, 若是验证失败, 那么直接返回一个表示请求未受权的response.
app.UseDeveloperExceptionPage(); 就是一个middleware, 当exception发生的时候, 这段程序就会处理它. 而判断env.isDevelopment() 表示, 这个middleware只会在Development环境下被调用.
能够在项目的属性Debug页看到这个设置:
须要注意的是这个环境变量Development和VS里面的Debug Build没有任何关系.
在正式环境中, 咱们遇到exception的时候, 须要捕获并把它记录(log)下来, 这时候咱们应该使用这个middleware: Exception Handler Middleware, 咱们能够这样调用它:
if (env.IsDevelopment())
{
app.UseDeveloperExceptionPage();
}
else
{
app.UseExceptionHandler();
}
UseExceptionHandler是能够传参数的, 但暂时先这样, 咱们在app.Run方法里抛一个异常, 而后运行程序, 在Chrome里按F12就会发现有一个(或若干个, 多少次请求, 就有多少个错误)500错误.
用来建立 Web Api的middleware:
原来的.net使用asp.net web api 和 asp.net mvc 分别来建立 web api和mvc项目. 可是 asp.net core mvc把它们整合到了一块儿.
MVC Pattern
model-view-controller 它的定义是: MVC是一种用来实现UI的架构设计模式. 可是网上有不少解释, 有时候有点分不清究竟是干什么的. 可是它确定有这几个有点: 松耦合, Soc(Separation of concerns), 易于测试, 可复用性强等.
可是MVC绝对不是完整的程序架构, 在一个典型的n层架构里面(presentation layer 展现层, business layer 业务层, data access layer数据访问层, 还有服务处), MVC一般是展现层的. 例如angular就是一个客户端的MVC模式.
在Web api里面的View就是指数据或者资源的展现, 一般是json.
注册并使用MVC
由于asp.net core 2.0使用了一个大而全的metapackage, 因此这些基本的services和middleware是不须要另外安装的.
首先, 在ConfigureServices里面向Container注册MVC: services.AddMvc();
public void ConfigureServices(IServiceCollection services)
{
services.AddMvc(); // 注册MVC到Container
}
而后再Configure里面告诉程序使用mvc中间件:
public void Configure(IApplicationBuilder app, IHostingEnvironment env)
{
if (env.IsDevelopment())
{
app.UseDeveloperExceptionPage();
}
else
{
app.UseExceptionHandler();
}
app.UseMvc();
注意顺序, 应该在处理异常的middleware后边调用app.UseMvc(), 因此处理异常的middleware能够在把request交给mvc之间就处理异常, 更总要的是它还能够捕获并处理返回MVC相关代码执行中的异常.
而后别忘了把app.Run那部分代码去掉. 而后改回到Develpment环境, 跑一下, 试试效果:
Chrome显示了一个空白页, 按F12, 显示了404 Not Found错误.
这是由于我只添加了MVC middleware, 可是它啥也没作, 也没有找到任何可用于处理请求的代码, 因此咱们要添加Controller来返回数据/资源等等.
Asp.net Core 2 Metapackage 和 Runtime Store
Asp.net core 2 metapackage, asp.net core 2.0开始, 全部必须的和经常使用的库也包括少量第三方库都被整和到了这个大而全的asp.net core 2 metapackage里面, 因此开发者就没必要本身挨个库安装也没有版本匹配问题了.
Runtime Store, 有点像之前的GAC, 在系统里有一个文件夹里面包含全部asp.net core 2程序须要运行的库(我电脑的是: C:\Program Files\dotnet\store\x64\netcoreapp2.0), 每一个在这台电脑上运行的asp.net core 2应用只需调用这些库便可.
它的优势是:
- 部署快速, 不须要部署这里面包含的库;
- 节省硬盘空间, 多个应用程序都使用同一个store, 而没必要每一个程序的文件夹里面都部署这些库文件.
- 程序启动更快一些. 由于这些库都是预编译好的.
缺点是: 服务器上须要安装.net core 2.0
可是, 也能够不引用Runtime Store的库, 本身在部署的时候挨个添加依赖的库.
Controller
首先创建一个Controllers目录, 而后创建一个ProductController.cs, 它须要继承Microsoft.AspNetCore.Mvc.Controller
咱们先创建一个方法返回一个Json的结果.
先创建一个Dto(Data Transfer Object) Product:
namespace CoreBackend.Api.Dtos
{
public class Product
{
public int Id { get; set; }
public string Name { get; set; }
public float Price { get; set; }
}
}
而后在Controller里面写这个Get方法:
namespace CoreBackend.Api.Controllers
{
public class ProductController: Controller
{
public JsonResult GetProducts()
{
return new JsonResult(new List<Product>
{
new Product
{
Id = 1,
Name = "牛奶",
Price = 2.5f
},
new Product
{
Id = 2,
Name = "面包",
Price = 4.5f
}
});
}
}
}
而后运行, 并使用postman来进行请求:
请求的网址返回404 Not Found, 由于尚未配置路由 Routing, 因此MVC不知道如何处理/映射这些URI.
Routing 路由
路由有两种方式: Convention-based (按约定), attribute-based(基于路由属性配置的).
其中convention-based (基于约定的) 主要用于MVC (返回View或者Razor Page那种的).
Web api 推荐使用attribute-based.
这种基于属性配置的路由能够配置Controller或者Action级别, uri会根据Http method而后被匹配到一个controller里具体的action上.
经常使用的Http Method有:
- Get, 查询, Attribute: HttpGet, 例如: '/api/product', '/api/product/1'
- POST, 建立, HttpPost, '/api/product'
- PUT 总体修改更新 HttpPut, '/api/product/1'
- PATCH 部分更新, HttpPatch, '/api/product/1'
- DELETE 删除, HttpDelete, '/api/product/1
还有一个Route属性(attribute)也能够用于Controller层, 它能够控制action级的URI前缀.
namespace CoreBackend.Api.Controllers
{
//[Route("api/product")]
[Route("api/[controller]")]
public class ProductController: Controller
{
[HttpGet]
public JsonResult GetProducts()
{
return new JsonResult(new List<Product>
{
new Product
{
Id = 1,
Name = "牛奶",
Price = 2.5f
},
new Product
{
Id = 2,
Name = "面包",
Price = 4.5f
}
});
}
}
}
使用[Route("api/[controller]")], 它使得整个Controller下面全部action的uri前缀变成了"/api/product", 其中[controller]表示XxxController.cs中的Xxx(实际上是小写).
也能够具体指定, [Route("api/product")], 这样作的好处是, 若是ProductController重构之后更名了, 只要不改Route里面的内容, 那么请求的地址不会发生变化.
而后在GetProducts方法上面, 写上HttpGet, 也能够写HttpGet(). 它里面还能够加参数,例如: HttpGet("all"), 那么这个Action的请求的地址就变成了 "/api/product/All".
运行结果:
咱们把获取数据的代码整理成一个ProductService, 而后保证程序运行的时候, 操做的是同一批数据:
namespace CoreBackend.Api.Services
{
public class ProductService
{
public static ProductService Current { get; } = new ProductService();
public List<Product> Products { get; }
private ProductService()
{
Products = new List<Product>
{
new Product
{
Id = 1,
Name = "牛奶",
Price = 2.5f
},
new Product
{
Id = 2,
Name = "面包",
Price = 4.5f
},
new Product
{
Id = 3,
Name = "啤酒",
Price = 7.5f
}
};
}
}
}
而后修改一下Controller里面的代码:
namespace CoreBackend.Api.Controllers
{
[Route("api/[controller]")]
public class ProductController: Controller
{
[HttpGet]
public JsonResult GetProducts()
{
return new JsonResult(ProductService.Current.Products);
}
}
}
也是一样的运行效果.
再写一个查询单笔数据的方法:
[Route("{id}")]
public JsonResult GetProduct(int id)
{
return new JsonResult(ProductService.Current.Products.SingleOrDefault(x => x.Id == id));
}
这里Route参数里面的{id}表示该action有一个参数名字是id. 这个action的地址是: "/api/product/{id}"
测试一下:
若是请求一个id不存在的数据:
Status code仍是200, 内容是null. 由于框架找到了匹配uri的action, 因此不会返回404, 可是咱们若是找不到数据的话, 应该返回404错误才比较好.
Status code
http status code 是reponse的一部分, 它提供了这些信息: 请求是否成功, 失败的缘由.
web api 能涉及到的status codes主要是这些:
200: OK
201: Created, 建立了新的资源
204: 无内容 No Content, 例如删除成功
400: Bad Request, 指的是客户端的请求错误.
401: 未受权 Unauthorized.
403: 禁止操做 Forbidden. 验证成功, 可是无法访问相应的资源
404: Not Found
409: 有冲突 Conflict.
500: Internal Server Error, 服务器发生了错误.
返回Status Code
目前咱们返回的JsonResult继承与ActionResult, ActionResult实现了IActionResult接口.
由于web api不必定返回的都是json类型的数据, 也不必定只返回一堆json(可能还要包含其余内容). 因此JsonResult并不合适做为Action的返回结果.
例如: 咱们想要返回数据和Status Code, 那么能够这样作:
[HttpGet]
public JsonResult GetProducts()
{
var temp = new JsonResult(ProductService.Current.Products)
{
StatusCode = 200
};
return temp;
}
可是每一个方法都这么写太麻烦了.
asp.net core 内置了不少方法均可以返回IActionResult.
Ok, NotFound, BadRequest等等.
因此改一下方法:
namespace CoreBackend.Api.Controllers
{
[Route("api/[controller]")]
public class ProductController : Controller
{
[HttpGet]
public IActionResult GetProducts()
{
return Ok(ProductService.Current.Products);
}
[Route("{id}")]
public IActionResult GetProduct(int id)
{
var product = ProductService.Current.Products.SingleOrDefault(x => x.Id == id);
if (product == null)
{
return NotFound();
}
return Ok(product);
}
}
}
如今, 请求id不存在的数据时, 就返回404了.
若是咱们用chrome直接进行这个请求, 它的效果是这样的:
StatusCode Middleware
asp.net core 有一个 status code middleware, 使用一下这个middleware看看效果:
public void Configure(IApplicationBuilder app, IHostingEnvironment env)
{
if (env.IsDevelopment())
{
app.UseDeveloperExceptionPage();
}
else
{
app.UseExceptionHandler();
}
app.UseStatusCodePages(); // !!!
app.UseMvc();
}
如今更友好了一些.
子资源 Child Resources
有时候, 两个model之间有主从关系, 会根据主model来查询子model.
先改一下model: 添加一个Material做为Product子model. 并在Product里面添加一个集合导航属性.
namespace CoreBackend.Api.Dtos
{
public class Product
{
public int Id { get; set; }
public string Name { get; set; }
public float Price { get; set; }
public ICollection<Material> Materials { get; set; }
}
public class Material
{
public int Id { get; set; }
public int Name { get; set; }
}
}
改下ProductService:
namespace CoreBackend.Api.Services
{
public class ProductService
{
public static ProductService Current { get; } = new ProductService();
public List<Product> Products { get; }
private ProductService()
{
Products = new List<Product>
{
new Product
{
Id = 1,
Name = "牛奶",
Price = 2.5f,
Materials = new List<Material>
{
new Material
{
Id = 1,
Name = "水"
},
new Material
{
Id = 2,
Name = "奶粉"
}
}
},
new Product
{
Id = 2,
Name = "面包",
Price = 4.5f,
Materials = new List<Material>
{
new Material
{
Id = 3,
Name = "面粉"
},
new Material
{
Id = 4,
Name = "糖"
}
}
},
new Product
{
Id = 3,
Name = "啤酒",
Price = 7.5f,
Materials = new List<Material>
{
new Material
{
Id = 5,
Name = "麦芽"
},
new Material
{
Id = 6,
Name = "地下水"
}
}
}
};
}
}
}
建立子Controller
MaterialController:
namespace CoreBackend.Api.Controllers
{
[Route("api/product")] // 和主Model的Controller前缀同样
public class MaterialController : Controller
{
[HttpGet("{productId}/materials")]
public IActionResult GetMaterials(int productId)
{
var product = ProductService.Current.Products.SingleOrDefault(x => x.Id == productId);
if (product == null)
{
return NotFound();
}
return Ok(product.Materials);
}
[HttpGet("{productId}/materials/{id}")]
public IActionResult GetMaterial(int productId, int id)
{
var product = ProductService.Current.Products.SingleOrDefault(x => x.Id == productId);
if (product == null)
{
return NotFound();
}
var material = product.Materials.SingleOrDefault(x => x.Id == id);
if (material == null)
{
return NotFound();
}
return Ok(material);
}
}
}
测试一下, 很成功:
结果的格式
asp.net core 2.0 默认返回的结果格式是Json, 并使用json.net对结果默认作了camel case的转化(大概可理解为首字母小写).
这一点与老.net web api 不同, 原来的 asp.net web api 默认不适用任何NamingStrategy, 须要手动加上camelcase的转化.
我很喜欢这样, 由于大多数前台框架例如angular等都约定使用camel case.
若是非得把这个规则去掉, 那么就在configureServices里面改一下:
public void ConfigureServices(IServiceCollection services)
{
services.AddMvc()
.AddJsonOptions(options =>
{
if (options.SerializerSettings.ContractResolver is DefaultContractResolver resolver)
{
resolver.NamingStrategy = null;
}
});
}
如今就是这样的结果了:
可是仍是默认的比较好.
内容协商 Content Negotiation
若是 web api提供了多种内容格式, 那么能够经过Accept Header来选择最好的内容返回格式: 例如:
application/json, application/xml等等
若是设定的格式在web api里面没有, 那么web api就会使用默认的格式.
asp.net core 默认提供的是json格式, 也能够配置xml等格式.
目前只考虑 Output formatter, 就是返回的内容格式.
试试: json:
xml:
设置header为xml后,返回的仍是json, 这是由于asp.net core 默认只实现了json.
能够在ConfigureServices里面修改Mvc的配置来添加xml格式:
public void ConfigureServices(IServiceCollection services)
{
services.AddMvc()
.AddMvcOptions(options =>
{
options.OutputFormatters.Add(new XmlDataContractSerializerOutputFormatter());
});
}
而后试试:
首先不写Accept Header:
而后试试accept xml :
先写这些..............................