这篇“.NetCore3.1WebAPI基础知识有哪些”文章的知识点大部分人都不太理解,所以小编给大家总结了以下内容,内容详细,步骤清晰,具有一定的借鉴价值,希望大家阅读完这篇文章能有所收获,下面我们一起来看看这篇“.NetCore3.1WebAPI基础知识有哪些”文章吧。随着近几年前后端分离、微服务等模式的兴起,.Net Core也似有如火如荼之势 ,自16年发布第一个版本到19年底的3.1 LTS版本,以及将发布的.NET 5,.NET Core一路更迭,在部署和开发工具上也都支持了跨平台应用。一直对.Net Core有所关注,但未涉及太多实际应用,经过一番学习和了解后,于是分享出来。本文主要以.Net Core Web API为例,讲述.Net Core的基本应用及注意事项,对于想通过WebAPI搭建接口应用的开发者,应该能提供一个系统的轮廓和认识,同时和更多的.Net Core开发者交流互动,探本勘误,加强对知识的理解,并帮助更多的人。开发环境:Visual Studio 2019为解决前后端苦于接口文档与实际不一致、维护和更新文档的耗时费力等问题,swagger应运而生,同时也解决了接口测试问题。话不多说,直接说明应用步骤。新建一个ASP.NET Core Web API应用程序,版本选择.ASP.NET Core 3.1;通过Nuget安装包:Swashbuckle.AspNetCore,当前示例版本5.5.0;在Startup类的ConfigureServices方法内添加以下注入代码:Startup类的Configure方法添加如下代码:Ctrl+F5进入浏览,按上述配置修改路径为:http://localhost:***/api/index.html,即可看到Swagger页面:然而到这里还没完,相关接口的注释说明我们看不到,通过配置XML文件的方式继续调整代码如下,新增代码见加粗部分:上述代码通过反射生成与Web API项目相匹配的XML文件名,AppContext.BaseDirectory属性用于构造 XML 文件的路径,关于OpenApiInfo内的配置参数用于文档的一些描述,在此不作过多说明。
然后右键Web API项目、属性、生成,配置XML文档的输出路径,以及取消不必要的XML注释警告提醒(增加1591):这样,我们以三斜杠(///)方式给类方法属性等相关代码添加注释后,刷新Swagger页面,即可看到注释说明。
如果不想将XML文件输出为debug下的目录,譬如想要放在项目根目录(但不要修改成磁盘绝对路径),可调整相关代码如下,xml文件的名字也可以改成自己想要的:同时,调整项目生成的XML文档文件路径为:..CoreAPI_DemoCoreAPI_Demo.xml4.隐藏相关接口
对于不想暴漏给Swagger展示的接口,我们可以给相关Controller或Action头加上:[ApiExplorerSettings(IgnoreApi = true)]5.调整系统默认输出路径
项目启动后,默认会访问自带的weatherforecast,如果想调整为其他路径,譬如打开后直接访问Swagger文档,那么调整Properties目录下的launchSettings.json文件,修改launchUrl值为api(前述配置的RoutePrefix值):以读取appsettings.json文件为例,当然你也定义其他名称的.json文件进行读取,读取方式一致,该文件类似于Web.config文件。为方便示例,定义appsettings.json文件内容如下:1、配置文件的基本读取以上介绍了2种读取配置信息的方式,如果要在Controller内使用,类似地,进行注入并调用如下:2、读取配置文件到自定义对象以SystemConfig节点为例,定义类如下:调整代码如下:然后Controller内进行注入调用:3、绑定到静态类方式读取定义相关静态类如下:调整Startup类构造函数如下:接下来,诸如直接使用:MySettings.Setting.UploadPath 即可调用。接口一般少不了文件上传,相比.netframework框架下webapi通过byte数组对象等复杂方式进行文件上传,.Net Core WebApi有了很大变化,其定义了新的IFormFile对象来接收上传文件,直接上Controller代码:后端代码前端调用接下来通过前端调用上述上传接口,在项目根目录新建wwwroot目录(.net core webapi内置目录 ),添加相关js文件包,然后新建一个index.html文件,内容如下:上述通过构建FormData和ajaxSubmit两种方式进行上传,需要注意的是contentType和processData两个参数的设置;另外允许一次上传多个文件,需设置multipart属性。在访问wwwroot下的静态文件之前,必须先在Startup类的Configure方法下进行注册:启动项目,通过访问路径:http://localhost:***/index.html,进行上传测试,成功后,将在wwwroot下的Files目录下看到上传的文件。定义统一返回格式为了方便前后端使用约定好的数据格式,通常我们会定义统一的数据返回,其包括是否成功、返回状态、具体数据等;为便于说明,定义一个数据返回类如下:这样,我们将每一个action接口操作封装为ApiResult格式进行返回。新建一个ProductController示例如下:Produces:定义数据返回的方式,给每个Controller打上[Produces(“application/json”)]标识,即表示以json方式进行数据输出。ApiController:确保每个Controller有ApiController标识,通常,我们会定义一个基类如:BaseController,其继承自ControllerBase,并将其打上[ApiController]标识,新建的controller都继承该类;Route:路由访问方式,如不喜欢RESTful方式,可加上Action,即:[Route(“api/[controller]/[action]”)];HTTP 请求:结合前面配置的Swagger,必须确保每个Action都有具体的请求方式,即必须是HttpGet、HttpPost、HttpPut、HttpDelete中的一种,通常情况下,我们使用HttpGet、HttpPost足以。如此,即完成的数据返回的统一。解决T时间格式.Net Core Web Api默认以首字母小写的类驼峰式命名返回,但遇到DateTime类型的数据,会返回T格式时间,如要解决T时间格式,定义一个时间格式转换类如下:然后在Startup类的ConfigureServices中调整services.AddControllers代码如下:模型验证在ASP.NET MVC已存在,使用方式基本一致。指对向接口提交过来的数据进行参数校验,包括必填项、数据格式、字符长度、范围等等。一般的,我们会将POST提交过来的对象定义为一个实体类进行接收,譬如定义一个注册类如下:Display标识提示字段的名称,Required表示必填,StringLength限制字段的长度,当然还有其他一些内置特性,具体可参考官方文档,列举一些常见的验证特性如下:[CreditCard]:验证属性是否具有信用卡格式。 需要 JQuery 验证其他方法。[Compare]:验证模型中的两个属性是否匹配。[EmailAddress]:验证属性是否具有电子邮件格式。[Phone]:验证属性是否具有电话号码格式。[Range]:验证属性值是否在指定的范围内。[RegularE免费云主机域名xpression]:验证属性值是否与指定的正则表达式匹配。[Required]:验证字段是否不为 null。 有关此属性的行为的详细信息,请参阅 [Required] 特性。[StringLength]:验证字符串属性值是否不超过指定长度限制。[Url]:验证属性是否具有 URL 格式。[Remote]:通过在服务器上调用操作方法来验证客户端上的输入。上述说明了基本的模型验证使用方法,以这种方式,同时结合T4模板,那么上述模型验证在Web API中是怎么工作的呢?在Startup类的ConfigureServices添加如下代码:添加注册示例Action代码:如此,通过配置ApiBehaviorOptions的方式,并读取验证错误信息的第一条信息并返回,即完成了Web API中Action对请求参数的验证工作,关于错误信息Message的返回,也可略作封装,在此略。虽然.Net Core WebApi有自带的日志管理功能,但不一定能较容易地满足我们的需求,通常会采用第三方日志框架,典型的如:NLog、Log4Net,简单介绍NLog日志组件的使用;NLog的使用① 通过NuGet安装包:NLog.Web.AspNetCore,当前项目版本4.9.2;② 项目根目录新建一个NLog.config文件,关键NLog.config的其他详细配置,可参考官方文档,这里作简要配置如下;③ 调整Program.cs文件如下;其中Main函数里的捕获异常代码配置省略也是可以的,CreateHostBuilder下的UseNLog为必设项。Controller通过注入调用如下:本地测试后,即可在debug下看到logs目录下生成的日志文件。使用.Net Core少不了和依赖注入打交道,这也是.Net Core的设计思想之一,关于什么是依赖注入(DI),以及为什么要使用依赖注入,这里不再赘述,先来看一个简单示例的依赖注入。Startup类进行注册:请求 IProductRepository 服务并用于调用 GetAll 方法:通过使用DI模式,来实现IProductRepository 接口。其实前述已多次出现通过构造函数进行注入调用的示例。生命周期 Transient:每一次请求都会创建一个新实例;Scoped:每个作用域生成周期内创建一个实例;Singleton:单例模式,整个应用程序生命周期内只创建一个实例;这里,需要根据具体的业务逻辑场景需求选择注入相应的生命周期服务。实际应用中,我们会有很多个服务需要注册到ConfigureServices内,一个个写入显然繁琐,而且容易忘记漏写,一般地,我们可能会想到利用反射进行批量注入,并通过扩展的方式进行注入,譬如:诚然,这样配合系统自带DI注入是能完成我们的批量注入需求的。但其实也有更多选择,来帮我们简化DI注册,譬如选择其他第三方组件:Scrutor、Autofac…1、Scrutor的使用Scrutor是基于微软注入组件的一个扩展库,简单示例如下:以上代码通过Scan方式批量注册了以Repository、Service结尾的接口服务,其生命周期为Transient,该方式等同于前述的以反射方式的批量注册服务。关于Scrutor的其他用法,大家可以参见官方文档,这里只做下引子。2、Autofac一般情况下,使用MS自带的DI或采用Scrutor,即可满足实际需要,如果有更高的应用需求,如要求属性注入、甚至接管或取代MS自带的DI,那么你可以选择Autofac,关于Autofac的具体使用,在此不作详叙。MemoryCache使用按官方说明,开发人员需合理说用缓存,以及限制缓存大小,Core运行时不会根据内容压力限制缓存大小。对于使用方式,依旧还是先行注册,然后控制器调用:上述代码缓存了一个时间,并设置了滑动过期时间(指最后一次访问后的过期时间)为3秒;如果需要设置绝对过期时间,将SetSlidingExpiration 改为SetAbsoluteExpiration即可。浏览刷新,每3秒后时间将更新。附一个封装好的Cache类如下:定义异常处理中间件这里主要针对全局异常进行捕获处理并记录日志,并以统一的json格式返回给接口调用者;说异常处理前先提下中间件,关于什么是中间件,在此不在赘述,一个中间件其基本的结构如下:下面我们定义自己的全局异常处理中间件,代码如下:然后在Startup类的Configure方法里添加上述扩展的中间件,见加粗部分:在HandleExceptionAsync方法中,为方便开发和测试,这里将系统的错误返回给了接口调用者,实际生产环境中可统一返回固定的错误Message消息。异常状态码的处理关于http状态码,常见的如正常返回的200,其他401、403、404、502等等等等,因为系统有时候并不总是返回200成功,对于返回非200的异常状态码,WebApi也要做到相应的处理,以便接口调用者能正确接收,譬如紧接下来的JWT认证,当认证令牌过期或没有权限时,系统实际会返回401、403,但接口并不提供有效的可接收的返回,因此,这里列举一些常见的异常状态码,并以200方式提供给接口调用者,在Startup类的Configure方法里添加代码如下:代码很简单,这里使用系统自带的异常处理中间件UseStatusCodePages,当然,你还可以自定义过滤器处理异常,不过不推荐,简单高效直接才是需要的。关于.NET Core的异常处理中间件,还有其他诸如 UseExceptionHandler、UseStatusCodePagesWithRedirects等等,不同的中间件有其适用的环境,有的可能更适用于MVC或其他应用场景上,找到合适的即可。题外话:大家也可以将UseStatusCodePages处理异常状态码的操作封装到前述的全局异常处理中间件中。关于什么是JWT,在此不作赘述。实际应用中,为了部分接口的安全性,譬如需要身份认证才能访问的接口资源,对于Web API而言,一般会采用token令牌进行认证,服务端结合缓存来实现。那为什么要选择JWT认证呢?原因无外乎以下:服务端不进行保存、无状态、适合移动端、适合分布式、标准化等等。关于JWT的使用如下:通过NuGget安装包:Microsoft.AspNetCore.Authentication.JwtBearer,当前示例版本3.1.5;ConfigureServices进行注入,默认以Bearer命名,这里你也可以改成其他名字,保持前后一致即可,注意加粗部分,代码如下:appsettings.json添加JWT配置节点(见前述【配置文件】),添加JWT相关认证类:采用前述绑定静态类的方式读取JWT配置,并进行注入:给Swagger添加JWT认证支持,完成后,Swagger页面会出现锁的标识,获取token后填入Value(Bearer token形式)项进行Authorize登录即可,Swagger配置JWT见加粗部分:Starup类添加Configure注册,注意,需放到 app.UseAuthorization();前面:这样,JWT就基本配置完毕,接下来实施认证登录和授权,模拟操作如下:上述代码模拟登录操作(账号密码登录,成功后设置有效期一天),生成token并返回,前端调用者拿到token后以诸如localstorage方式进行存储,调取授权接口时,添加该token到header(Bearer token)进行接口请求。接下来,给需要身份授权的Controller或Action打上Authorize标识:如果要添加基于角色的授权,可限制操作如下:不同的角色信息,可通过登录设置ClaimTypes.Role进行配置;当然,这里只是简单的示例说明角色服务的应用,复杂的可通过注册策略服务,并结合数据库进行动态配置。这样,一个简单的基于JWT认证授权的工作就完成了。前后端分离,会涉及到跨域问题,简单的支持跨域操作如下:添加扩展支持Startup类添加相关注册如下:这样,一个简单跨域操作就完成了,你也可以通过设置WithOrigins、WithMethods等方法限制请求地址来源和请求方式。以上就是关于“.NetCore3.1WebAPI基础知识有哪些”这篇文章的内容,相信大家都有了一定的了解,希望小编分享的内容对大家有帮助,若想了解更多相关的知识内容,请关注百云主机行业资讯频道。
相关推荐: Vue中vee-validate插件怎么安装使用
这篇文章主要介绍“Vue中vee-validate插件怎么使用”的相关知识,小编通过实际案例向大家展示操作过程,操免费云主机域名作方法简单快捷,实用性强,希望这篇“Vue中vee-validate插件怎么使用”文章能帮助大家解决问题。Vue具体轻量级框架、简单…
免责声明:本站发布的图片视频文字,以转载和分享为主,文章观点不代表本站立场,本站不承担相关法律责任;如果涉及侵权请联系邮箱:360163164@qq.com举报,并提供相关证据,经查实将立刻删除涉嫌侵权内容。