ASP.NET Web API入门介绍（一）-开发框架文库

ASP.NET Web API入门介绍（一）

随着项目的复杂度越来越高，各种第三方系统的数据交互也越来越频繁，不可避免的就要用到Web API接口，这里Web API是一个比较宽泛的概念。本文提到Web API特指ASP.NET Web API。本文以一些简单的小例子，简述ASP.NET Web API的相关基础知识，仅供学习分享使用，如有不足之处，还请指正。

什么是RESTful?

REST全称是Representational State Transfer，中文意思是表述状态转移。REST本身并没有创造新的技术、组件或服务，而隐藏在RESTful背后的理念就是使用Web的现有特征和能力，更好地使用现有Web标准中的一些准则和约束。如果一个架构符合REST的约束条件和原则，我们就称它为RESTful架构。对于RESTful，原作者是这样描述的【我这篇文章的写作目的，就是想在符合架构原理的前提下，理解和评估以网络为基础的应用软件的架构设计，得到一个功能强、性能好、适宜通信的架构。】

综合上面的解释，我们总结一下什么是RESTful架构：

每一个URI代表一种资源；
客户端和服务器之间，传递这种资源的某种表现层；
客户端通过四个HTTP动词，对服务器端资源进行操作，实现"表现层状态转化"。

什么是Web API?

ASP.NET Web API基于C#构建安全的符合REST风格的API。通过ASP.NET Web API，可以快速创建在各个客户端进行调用的服务，包括Web浏览器端和移动端等。如下所示：

ASP.NET Web API入门介绍（一）

为什么要用Web API?

ASP.NET Web API是一个框架，可以很容易构建达成了广泛的HTTP服务客户端，包括浏览器和移动设备。是构建RESTful应用程序的理想平台的.NET框架。在系统架构中的地位，如下所示：

ASP.NET Web API入门介绍（一）

创建ASP.NET Web API项目

文件--新建--项目打开【创建新项目】窗口，然后选择【ASP.NET Web应用程序（.NET Framework）】，点击下一步，如下所示：

ASP.NET Web API入门介绍（一）

进入【配置新项目】窗口，输入项目名称，选择项目保存路径，然后点击【创建】，如下所示：

ASP.NET Web API入门介绍（一）

进入【创建新的ASP.NET Web应用程序】创建，选择【空】，然后添加【MVC,Web API】核心引用，然后点击【创建】如下所示：

ASP.NET Web API入门介绍（一）

稍等片刻，项目即创建成功，目录结构如下所示：

App_Start目录下RouteConfig.cs为MVC核心引用，主要用于注册MVC路由配置
App_Start目录下WebApiConfig.cs为Web API的核心引用，主要用于注册Web API的路由配置。
默认创建了Controllers，Models，Views三个目录，分别用于存放三层架构各自的内容。

ASP.NET Web API入门介绍（一）

创建第一个接口

在Controllers文件夹，右键--添加--Web API控制器类，如下所示：

ASP.NET Web API入门介绍（一）

然后输入控制器名称，以Controller结尾，点击【确定】，如下所示：

ASP.NET Web API入门介绍（一）

通过模板创建的控制器，自动添加了示例代码，且默认继承ApiController，如下所示：

 1 namespace WebApiDemo.Controllers
 2 {
 3     public class StudentController : ApiController
 4     {
 5         // GET api/<controller>
 6         public IEnumerable<string> Get()
 7         {
 8             return new string[] { "value1", "value2" };
 9         }
10 
11         // GET api/<controller>/5
12         public string Get(int id)
13         {
14             return "value";
15         }
16 
17         // POST api/<controller>
18         public void Post([FromBody] string value)
19         {
20         }
21 
22         // PUT api/<controller>/5
23         public void Put(int id, [FromBody] string value)
24         {
25         }
26 
27         // DELETE api/<controller>/5
28         public void Delete(int id)
29         {
30         }
31     }
32 }

定制API

为了进行测试，首先新建Model类Student，如下所示：

 1 using System;
 2 using System.Collections.Generic;
 3 using System.Linq;
 4 using System.Text;
 5 using System.Threading.Tasks;
 6 
 7 namespace WebApiDemo.Models
 8 {
 9     public class Student
10     {
11         public int Id { get; set; }
12 
13         public string Name { get; set; }
14 
15         public int Age { get; set; }
16 
17         public bool Sex { get; set; }
18     }
19 }

1. GET方式

在StudentController中，引用Models命名空间中的Student模型，修改Get方法，如下所示：

默认情况下，WebApi模板自动创建了两个Get方法，一个无参，一个有参，分别返回列表和具体实例，进行调整，返回Student数据，如下所示：

 1 // GET api/<controller>
 2 public IEnumerable<Student> Get()
 3 {
 4       return new Student[] { new Student() {
 5            Id=1,
 6            Name="Alan.hsiang",
 7            Age=20,
 8            Sex=true
 9        }, new Student() {
10            Id=2,
11            Name="Json.hsiang",
12            Age=18,
13            Sex=false
14         } };
15 }
16 
17 // GET api/<controller>/5
18 public Student Get(int id)
19 {
20       return new Student()
21        {
22             Id = 1,
23             Name = "Alan.hsiang",
24             Age = 20,
25             Sex = true
26         };
27 }

然后运行VisualStudio，默认端口为44311，通过PostMan进行测试。

不带参数，返回Student列表。如下所示：

ASP.NET Web API入门介绍（一）

带参数的，返回某个具体的Student实例，id可以通过api/Controller/id的方式进行传递。如下所示：

ASP.NET Web API入门介绍（一）

2. POST方式

POST方法主要是通过body表单的方式进行提交，本例修改自带的代码，接收入参Student实例，返回Student字符串，如下所示：

1 // POST api/<controller>
2 public string Post([FromBody] Student value)
3 {
4       return string.Format("学生的ID={0}，姓名={1}，年龄={2}，性别={3}",value.Id,value.Name,value.Age,value.Sex);
5 
6 }

通过Postman，进行访问，访问方式选择POST，Body选择raw，数据格式选择JSON，如下所示：

ASP.NET Web API入门介绍（一）

3. PUT方式

PUT方式一般用于修改数据，本例为了测试，返回接收的ID，如下所示：

1 // PUT api/<controller>/5
2 public int Put(int id, [FromBody] string value)
3 {
4       //为了测试，返回接收到的id
5       return id;
6 }

通过Postman进行测试，请求方式选择PUT，Body内容如果只有一个string类型参数，则参数名为空，如下所示：

ASP.NET Web API入门介绍（一）

4. DELETE方式

DELETE方式一般用于删除数据，本例为了测试，返回一个字符串，如下所示：

1 // DELETE api/<controller>/5
2 public string Delete(int id)
3 {
4       return string.Format("Id={0} 已删除", id);
5 }

通过Postman进行测试，请求方式选择DELETE，如下所示：

ASP.NET Web API入门介绍（一）

总结

通过以上示例的测试，总结如下：

访问路径，符合RESTful的风格，通过请求方式进行区分具体的功能，如下所示：
- GET 请求列表：https://localhost:44311/api/Student
- GET 请求单一实例：https://localhost:44311/api/Student/1
- POST请求：https://localhost:44311/api/Student/
- PUT方式：https://localhost:44311/api/Student/3
- DELETE方式：https://localhost:44311/api/Student/4
请求数据格式：
- GET方式，一般采用URL的方式进行传递参数
- POST，PUT，DELETE方式，采用body传参，格式一般文JSON。

通过以上总结，发现WebAPI与RESTful风格架构不谋而合。

同一方式多个参数

在本例中，如果有多个GET方式的请求方法，且参数格式，个数不同，应该如何匹配，如下所示：

 1 // GET api/<controller>
 2 public IEnumerable<Student> Get()
 3 {
 4       return new Student[] { new Student() {
 5            Id=1,
 6            Name="Alan.hsiang",
 7            Age=20,
 8            Sex=true
 9         }, new Student() {
10            Id=2,
11            Name="Json.hsiang",
12            Age=18,
13            Sex=false
14         } };
15 }
16 
17 // GET api/<controller>/5
18 public Student Get(int id)
19 {
20      return new Student()
21      {
22           Id = 1,
23           Name = "Alan.hsiang",
24           Age = 20,
25           Sex = true
26        };
27 }
28 
29 // GET api/<controller>/5?name=aabbcc
30 public Student Get(int id,string name)
31 {
32       return new Student()
33       {
34            Id = id,
35            Name = name,
36            Age = 22,
37            Sex = true
38         };
39 }

前两种方式以通过Postman进行测试，现在测试第三种方式，如下所示：

ASP.NET Web API入门介绍（一）

同一方式，不同名称

通过以上示例，可以看出方法名和请求方式是一一对应的，那如果方法名和请求方式不一致呢？

首先增加GetStudent方式，为了区分，在返回的Name值分别写了0和1，如下所示：

// GET api/<controller>/5?name=aabbcc
public Student Get(int id,string name)
{
        return new Student()
        {
            Id = id,
            Name = name+"---0",
            Age = 22,
            Sex = true
         };
}

public Student GetStudent(int id, string name)
{
       return new Student()
       {
            Id = id,
            Name = name+"---1",
            Age = 22,
            Sex = true
        };
}

打开Postman进行测试，直接报错，称找到了两个符合格式的资源的，如下所示：

ASP.NET Web API入门介绍（一）

以上问题，通过查看WebApiConfig.cs即可发现，WebApi注入的routeTemplate是api/{controller}/{id}，没有action做区分，此处和MVC不同。WebApi注册默认路由模板，如下所示：

 1 namespace WebApiDemo
 2 {
 3     public static class WebApiConfig
 4     {
 5         public static void Register(HttpConfiguration config)
 6         {
 7             // Web API 配置和服务
 8 
 9             // Web API 路由
10             config.MapHttpAttributeRoutes();
11 
12             config.Routes.MapHttpRoute(
13                 name: "DefaultApi",
14                 routeTemplate: "api/{controller}/{id}",
15                 defaults: new { id = RouteParameter.Optional }
16             );
17         }
18     }
19 }

Route特性

为了解决两个访问方式相同，参数相同，但是方法名不同，会导致获取报错的问题，WepApi引入了路由特性，如下所示：

 1 [Route("api/Student/QueryStudent/{id}")]
 2 [HttpGet]
 3 public Student QueryStudent(int id, string name)
 4 {
 5      return new Student()
 6      {
 7           Id = id,
 8           Name = name + "---1",
 9           Age = 22,
10           Sex = true
11      };
12 }

如下，通过Postman进行访问，则可以正常访问。默认访问Get(int id,string name)

ASP.NET Web API入门介绍（一）

通过路由特性，访问/api/Student/QueryStudent/4?name=HEX，如下所示：

ASP.NET Web API入门介绍（一）

路由前缀

通过路由特性，完美解决了一个Controller，同一种方式，同时访问两个不同的方法的问题。但是如果每一个路由特性都写全称，也会很繁琐，且容易出错，所以路由前缀，应运而生。

路由前缀修饰Controller，路由特性修饰Action，如下所示：

 1 namespace WebApiDemo.Controllers
 2 {
 3     [RoutePrefix("api/Teacher")]
 4     public class TeacherController : ApiController
 5     {
 6         public string Get(int id, string name) {
 7             return string.Format("[Get]正在查找的老师id={0}，姓名={1}", id, name);
 8         }
 9 
10         [Route("query/{id}")]
11         [HttpGet]
12         public string QueryTeacher(int id, string name) {
13             return string.Format("[Query]正在查找的老师id={0}，姓名={1}", id, name);
14         }
15     }
16 }

这样在访问时，即可区分，默认访问Get方法，如下所示：

ASP.NET Web API入门介绍（一）

通过路由特性，访问Query方法，如下所示：

ASP.NET Web API入门介绍（一）

备注

以上就是ASP.NET Web API基础知识的简单介绍，本文旨在抛砖引玉，共同学习，一起进步。

清平调·其一李白〔唐代〕

云想衣裳花想容，春风拂槛露华浓。若非群玉山头见，会向瑶台月下逢。

清平调·其二李白〔唐代〕

一枝秾艳露凝香，云雨巫山枉断肠。借问汉宫谁得似，可怜飞燕倚新妆。

清平调·其三李白〔唐代〕

名花倾国两相欢，长得君王带笑看。解释春风无限恨，沉香亭北倚阑干。