用ASP.NET Core 2.0 建立规范的 REST API -- GET 和 POST
2021-04-08 18:24
标签:匿名类 知识 not found nal 过滤 employee develop web table 本文转自:https://www.cnblogs.com/cgzl/archive/2018/05/23/9047626.html 本文所需的一些预备知识可以看这里: http://www.cnblogs.com/cgzl/p/9010978.html 和 http://www.cnblogs.com/cgzl/p/9019314.html 本文介绍的是使用ASP.NET Core建立Richardson成熟度为2级的伪RESTful web API, 本文介绍的是GET和POST. 使用的项目是(右键另存为, 然后把后缀名改为zip): https://images2018.cnblogs.com/blog/986268/201805/986268-20180516191053536-1701412182.jpg 首先, 资源应该使用名词, 它是个东西, 不是动作. 例如: 所以资源应该使用的是名词. 如果是非分层结构的资源, 那么它不应该这样命名: api/xxx/xxx/users, 而应该使用 api/users. 如果是单个资源, 不应该这样 api/id/users, 而应该是 api/users/{userId}. (资源名是否复数还是根据个人习惯吧). 例如 api/department/{departmentId}/emoloyees, 这就表示了department (部门)和 员工(employee)之前是主从关系. 而 api/department/{departmentId}/emoloyees/{employeeId}, 就表示了该部门下的某个员工. 而过滤, 排序等不是资源, 所以这样写 api/users/orderby/username 是不正确的. 过滤排序这类的参数是可以作为查询参数传递进来的, 正确的写法应该是: api/users?orderby=username. 但是有时候, RPC风格的方法调用很难映射成规范的资源命名, 所以有时可以打破规范 例如 api/users/{userId}/totalsalaries. 如果使用int型作为ID的话, 大部分时候是没有问题的, 但是如果您使用的数据库的ID是自增整型的, 如果你替换数据库了, 然后把原有数据迁移到新数据库了, 那么现有数据的ID就会发生变化, 那么相当于所有的资源的地址发生了变化, 这就违反了这个: 资源的URI应该永远都是一样的. 所以GUID应该作为ID来使用. (但是我为了省事, 还是使用自增int作为ID吧??). 使用GUID作为主键的好处就是: 针对项目里的Country这个资源, 请参考下面这个列表: 这里GET可以理解为获取(查询)资源, POST为添加资源, PUT为整体更新资源, PATCH为局部更新资源, DELETE为删除资源. 这里需要提的是后两个: 首先需要建立一个CountryController: 注意在CountryController上面标注的[Route]属性标签,它的值是整个Controller下所有的Action的路由前缀,可以写成固定的地址,也可以写成"api/[controller]", 其中[controller]这部分会变成这个Controller的名字,这里也就是"api/country". 如果使用[controller]的话,如果Controller重构后名字改了,那么该Controller的路由地址也就是资源的地址也就改了,这样很不好,所以建议还是写成固定的地址不要使用[controller]。 GET 所有的Country: (AutoMapper的使用方法这里就不介绍了) GET 一个Country: 这两个方法里返回的都是JsonResult,这看起来没什么问题,因为我们想要的就是JSON格式的结果。以第二个方法为例,使用POSTMAN测试,如果能查询到数据: 这是没有问题的,但是如果查询一个不存在的资源: 这就有问题了,如果查询不到资源,那么返回的应该是404 NOF FOUND 而不是200 OK. 状态码是非常重要的,因为只有状态码会告诉API的消费者: 下面再列举一下web API会用到的状态码: 200级别,表示成功: 400级别,表示客户端引起的错误: 500级别,服务器错误: 回到刚才的那两个方法,默认情况下 JsonResult会返回200 OK状态码,可以去修改JsonResult以支持其它的状态码。但是Controller里提供了一些帮助方法返回IActionResult并指定特定的状态码,针对200,就是Ok()方法。 这时就不需要手动返回JsonResult了。 这里需要注意的是,针对集合的内容协商,如果集合是空的,也不应该返回404,因为这个Country资源是存在的,只不过它的内容是空的而已。 然后看一下GET 特定单个资源: 针对单个资源,如果没有找到,就需要返回404 Not Found,这时就可以使用Controller的帮助方法 NotFound(). 当Action发生异常的时候,默认情况下ASP.NET Core会返回500: 但还是自己处理一下比较好,可以在Action里面使用try catch: 这里由于是服务器的错误,所以应该返回500状态码 Internal Server Error。 注意这里不应该返回Exception,因为这是程序的内部实现细节,再说它对客户来说也没什么用。 此外,我们还可以全局处理异常。 在Startup里面的Configure方法: 使用app.UseExceptionHandler(),里面可以自定义一些逻辑。如果这地方代码比较多的话,可以把它封装成一个扩展方法,然后使用app.Usexxx的形式调用。 回头我把Action里面的try catch去掉试试,但是这里要注意把环境变量ASPNETCORE_ENVIRONMENT的值改成Production(其实不是Development就可以): 这是一个典型的情景,一个国家包含多个城市,这就是父子关系。 首先看一下domain model: 这个应该很简单。 此外还要建立CityResource,Repository和IRepository,注册配置,种子数据等等,这些就不贴了。 下面建立CityController 前面提到过,针对父子、主从关系的资源,其子资源的路由地址应该是上面这样的,由于该Controller下所有的Action的路由前缀都是一样的,所以把这个路由放到了Controller级别作为所有Action的前缀。 而GET方法本身比较简单,没什么说的,里面涉及的一些方法请自行编写。 看看运行结果: 如果找不到Country,则返回404: 下面GET 单个city: 注意,单个资源找不到就应该返回404,而空集合怎不是,这个前面也提过。 找到资源的结果: 找不到country或者city的时候都应该返回404,就不贴图了。 简单来说就是,如果资源支持多种展现格式,那么消费者可以选择它想要的格式。 这里就要用到media type,它可以通过请求的Accept Header来传递,常见的有: application/json 和 application/xml...等等 在没有指定Accept Header的情况下,就该返回一个默认的格式,在ASP.NET Core 2.0里面就是application/json。 当请求的media type不可用的时候,并且消费者不支持默认格式,这时服务器就应该返回 406 Not Acceptable 状态码。 ASP.NET Core 支持输出和输入两种格式化器。 输出的media type在accept header里面,而输入的media type在content-type header里面。 看一下当前的情况,请求的Accept Header为application/json时: 请求的Accept Header为application/xml时: 它们返回的都是json格式的。 因为服务器(项目)现在不支持xml,所以返回了默认的json格式,但严格来说,这样做不正确,所以需要处理一下。 在Startup里,ConfigureServices方法: 把这个ReturnHttpNotAcceptable属性设为true,如果想要的格式不支持,那么就会返回406 Not Acceptable: 不指定Accept Header的情况下就返回默认的json格式: 下面,为项目添加Xml输出格式的支持: 再试试: 这时就成功的返回了xml。 首先了解一下方法的安全性和幂等性。 安全性是指方法执行后并不会改变资源的表述。 幂等性是指方法无论执行多少次都会得到同样的结果。 下面是HTTP方法的安全性和幂等性列表: 参考这个列表可以帮助决定在某种情况下用哪种HTTP方法。 下面看看创建Country的代码: 这个代码很简单,数据是从请求的body带进来的。 需要注意的是返回什么,如果POST操作执行成功的话,标准的做法是返回201 Created 状态码。 在这里就可以使用CreatedAtRoute() 这个方法,它允许响应里带着Location Header,在这个Location Header里包含着一个uri,通过这个uri就可以GET到我们刚刚创建好的资源(Country)。 这个方法的第一个参数是一个路由名,使用这个路由名可以用来生成刚才提到的uri。在本例里,这个路由名应该对应的是GetCountry这个Action方法,所以为这个Action添加路由名: 这样就和Post方法返回中用到的路由名一致了,第二个参数是一个匿名类里面有个属性id,它会编程路由里的参数,最后一个参数是响应会返回的数据。 下面进行测试,发送请求的时候别忘了设置Content-type为applicaiton/json: 然后是数据: 然后发送请求,查看响应的body部分: 再看响应的header: 这里可以看到Location Header的uri,通过这个uri,你就可以GET到这个刚刚创建的Country资源,这里我就不测试了。 如果再次执行这个POST操作,看看结果: 这次返回的数据的id为6,与前面不一样,所以POST不是幂等的,它每次执行后的结果是不一样的。 Country的创建做完了,现在可以创建City了。 这个跟上面的差不多,只不过注意需要一下路由的参数即可。 测试: 这是个常见的需求,一个Country和它下属的Cities同时被传递进来,然后在Action里一同创建。 首先需要修改CountryAddResource: 然后,就没有然后了,所有的映射操作都交给AutoMapper和EntityFramework Core了。。 测试: 然后GET这两个Cities: 这次我要一次性添加一个集合的Countries。 由于Country的集合相当于是另外一种资源,所以可以把它放到单独的Controller里面,不放也没问题。 这个其实也没什么特别的,注意传进来的参数是IEnumerable。为了方便,暂时先返回OK()。 测试: OK, 下面解决返回的问题. 我们要返回的是CreatedAtRoute方法, 由于里面要包含可以返回该集合资源的路由地址, 所以需要创建一个Action, 它的参数应该是POST方法返回数据的Id的集合. 但是由于路由参数不支持集合形式, 只能以字符串形式传递, 所以可以做成这样的路由参数: api/xx/(1,2,3,4,5). 而Action方法呢, 接受的参数应该是Id的集合, 应该是一个集合类型, 所以我们可以使用ModelBinder把id字符串转化为id的集合: 然后, 还需要对应这个POST Action 做一个GET集合的Action 方法: 这个Action所期待的参数类型是Id的集合, 而实际传入的是id的字符串, 通过ArrayModelBinder来实现转化. 最后修改POST方法的返回: 测试一下: 然后再GET这个链接: OK 如果POST到这个地址 http://localhost:5000/api/countries/{id}, 那么, 如果该id的资源不存在, 则应该返回404; 如果该id的资源存在, 则应该返回409 Conflict. (POST不是幂等性的, 它无法多次请求都产生同样的结果). 测试一下id的资源不存在的情况: 在测试一下Id的资源存在的情况: 还是404, 这个不行, 所以需要手动处理: 看看结果: OK, 无论是Id存在的资源还是不存在的资源都会返回正确的状态码. 之前讲过如何返回xml的格式, 下面介绍一下如何使用xml格式进行请求, 首先在Startup.cs里面添加这个: 然后, 需要把请求的Content-Type设为application/xml: 我就不适用xml数据进行测试了. 这次先到这, 随后会写DELETE, UPDATE, PATCH. 本文的源码地址: https://github.com/solenovex/ASP.NET-Core-2.0-RESTful-API-Tutorial 用ASP.NET Core 2.0 建立规范的 REST API -- GET 和 POST 标签:匿名类 知识 not found nal 过滤 employee develop web table 原文地址:https://www.cnblogs.com/yanglang/p/9081529.htmlRESTful API 资源 (Resource) 的命名指导规范
命名应该可以体现资源的结构
应该使用什么类型作为ID
通过HTTP方法与资源交互
建立Controller
GET 资源
状态码
处理异常
GET 父子关系的资源
内容协商
创建资源
创建子资源
同时创建父子资源
创建集合资源
如果POST到单个资源的地址
支持输入其它类型的Content-Type
上一篇:windows开机启动bat文件
下一篇:无法从命令行或调试器启动服务,必须首先安装Windows服务(使用installutil.exe),然后用ServerExplorer、Windows服务器管理工具或NET START命令启动它
文章标题:用ASP.NET Core 2.0 建立规范的 REST API -- GET 和 POST
文章链接:http://soscw.com/essay/72972.html