ASP.NET Core WebAPI开发：从基础到实战

原创于 2025-11-28 09:06:13 发布 · 190 阅读

4 ·

CC 4.0 BY-SA版权

文章标签：

#服务器 #运维 #c# #.netcore #restful #asp.net #.net

net 专栏收录该内容

1 篇文章

订阅专栏

一、WebAPI基础

1.什么是前后端分离

前后端分离是现在流行的一种开发模式，即前端负责渲染HTML页面，后端负责返回前端所需的数据，而不再控制前端的效果，用户看到什么样的效果，从后端请求的数据如何加载到前端中，都由前端自己决定。在前后端分离开发模式下，前端与后端的耦合度相对较低，在这种模式中，通常将后端开发的每个视图都称为一个接口，或者API，前端通过访问接口/API来对后端数据进行增删改查等操作。

前后端分离的好处

高工作效率，分工更加明确
降低服务器负载，系统性能提升
增强代码的可维护性

说明

虽然使用前后端分离开发模式有很多的优点，但是当后端接口发生改变时，会比较麻烦，而且，使用前后端分离开发模式，需要前后端开发人员统一对项目进行联调（开发+测试+联调），这也可能会影响项目的整体效率，并增加运维成本。

因此，如果团队人员齐全、分工明确、研发技能储备足够，并且项目比较大，建议使用前后端分离开发模式；而如果团队人员比较少，而且项目又比较小，则不用必须采用前后端分离开发模式。

2.ASP.NET Core中的WebAPI

WebAPI是一种用于创建Web应用程序的API（应用程序接口），它通常用于在Web应用程序中提供数据和功能。WebAPI使用HTTP协议来发送请求和接收响应，比如在开发项目时经常需要调用第三方数据接口（例如天气预告、地图定位等等），这里的所谓第三方数据接口就可以用ASP.NET Core WebAPI进行开发。

ASP.NET Core WebAPI基于REST风格，搭建在HTTP协议之上，本质上是一种HTTP服务，它支持使用控制器，不需要编写前端页面，前后端完全分离，它只关注返回数据；而ASP.NET Core MVC大部分需要返回前端页面，是一套完整的Web框架。因此，在开发项目时，如果需要前后端分离开发，或者需要与手机APP、微信小程序以及其他应用程序进行交互，则应该使用ASP.NET Core WebAPI。

3.RESTful基础

REST全称是Representational State Transfer（表征性状态转移），它是2000年由罗伊·菲尔丁提出的一种Web服务设计原则，其基于HTTP，可以使用XML格式或JSON格式定义。如果一个系统的设计符合REST原则，则可以称这个系统是RESTful风格的。RESTful具有高度的可扩展性和可维护性，适用于前后端分离开发，因此WebAPI接口非常适合于按照RESTful服务的统一标准来进行开发。

RESTful的开发规范

URL链接一般采用https协议进行传输；
接口中带API关键字；
接口名称尽量使用名词；
通过请求方式决定对资源进行什么操作（获取数据：GET请求；新增数据：POST请求；删除数据：DELETE请求；修改数据：PUT、PATCH请求）；
URL地址中带过滤参数（指定？后面携带的数据）；
响应体中返回错误信息；
根据响应状态码确定是否请求成功（1xx：表示请求正在处理，一般看不到；2xx：表示请求处理成功，如200、201等；
3xx：重定向，如302、301等；4xx：客户端错误，如403、404等；5xx ：服务端错误）；
响应中带链接；
针对不同操作，服务器向用户返回的结果应该符合下列规范： GET/collection：返回资源对象的列表，是一个数组（[{},{}]）； GET/collection/resource：返回新生成的资源对象（{}）； POST/collection：返回新生成的资源对象（{}）； PUT/collection/resource：返回完整的资源对象（{}）； PATCH/collection/resource：返回完整的资源对象（{}）； DELETE/collection/resource：返回一个空文档。

RESTful举例

二、ASP.NET Core WebAPI项目搭建

1.创建ASP.NET Core WebAPI项目

2.ASP.NET Core WebAPI项目演示

三、ASP.NET Core WebAPI项目分析

1.ControllerBase类

ControllerBase类表示无视图支持的MVC控制器的基类，其位于Microsoft.AspNetCore.Mvc命名空间中，MVC项目中控制器类继承的Controller类是其子类，由于Controller类中包含了对视图的支持，而WebAPI则专注于提供数据，而不用展示数据，因此，创建WebAPI项目时，其控制器类通常继承自ControllerBase类，而不是Controller类。

链接：https://learn.microsoft.com/zh-cn/dotnet/api/microsoft.aspnetcore.mvc.controllerbase?view=aspnetcore-7.0

2.[ApiController]和[Route("[controller]")]

[ApiController]

[ApiController]属性本质上指的是Microsoft.AspNetCore.Mvc命名空间下的ApiControllerAttribute类，用来为使用它的类型和所有派生类型提供HTTP API响应，其可应用于控制器类，以启用WebAPI的以下功能：

属性路由要求；
自动HTTP 400响应；
绑定源参数推理；
Multipart/form-data请求推理；
错误状态代码的问题详细信息。

说明

如果将[ApiController]属性应用于程序集，则程序集中的所有控制器都将应用[ApiController]属性，即程序集中的所有控制器都将被视为具有API行为的控制器。

[Route("[controller]")]

[Route]属性本质上指的是Microsoft.AspNetCore.Mvc命名空间下的RouteAttribute类，它用来指定控制器上的属性路由，属性路由用来指定访问WebAPI接口时的地址，其在使用时，可以不带参数，也可以带参数，如果带参数，支持“[controller]”和“[action]”两个参数，如果要使用其他参数，则需要使用大括号“{}”，如“[Route("{id?}")]”；另外，[Route]属性既可以用于Controller类型，也可能用于单个Action方法上。

3.[HttpGet]请求及其他HTTP请求

使用[HttpGet]属性修饰接口方法，表示该接口方法用来处理GET请求。[HttpGet]是WebAPI中的一种HTTP方法，用于从Web应用程序中获取数据，它通常用于从服务器检索数据，并将其返回给客户端。在[HttpGet]请求中，数据通常以JSON或XML格式返回。[HttpGet]属性实质上是指Microsoft.AspNetCore.Mvc命名空间下的HttpGetAttribute类，其作用于API接口方法时，有两种形式，分别如下：

4.Swagger

Swagger是一个规范和完整的框架，用于生成、描述、调用和可视化RESTful风格的Web服务，由于Swagger项目已于2015年捐赠给OpenAPI计划，自此它也被称为OpenAPI，这两个名称可以互换使用。Swagger使计算机和用户无需直接访问源代码即可了解REST API的功能，其主要目标如下：

尽量减少连接后端分离服务所需的工作量。
减少准确记录服务所需的时间。

在.NET Core中，通常使用Swashbuckle生成ASP.NET Core WebAPI的Swagger文档，Swashbuckle是一个开源项目，使用时，需要使用以下命令安装相应的Nuget包：

Install-Package Swashbuckle.AspNetCore

Swashbuckle有3个主要组成部分，分别如下：

Swashbuckle.AspNetCore.Swagger：将SwaggerDocument对象公开为JSON终结点的Swagger对象模型和中间件。
Swashbuckle.AspNetCore.SwaggerGen：从路由、控制器和模型直接生成SwaggerDocument对象的Swagger生成器，它通常与Swagger终结点中间件结合，以自动公开Swagger JSON。
Swashbuckle.AspNetCore.SwaggerUI：Swagger UI工具的嵌入式版本，它解释Swagger JSON以构建描述WebAPI功能的可自定义的丰富体验，并且包括针对公共方法的内置测试工具。