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架构：

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

什么是Web API?

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

为什么要用Web API?

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

创建ASP.NET Web API项目

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

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

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

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

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

 创建第一个接口

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

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

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

namespace WebApiDemo.Controllers
{
    public class StudentController : ApiController
    {
        // GET api/<controller>
        public IEnumerable<string> Get()
        {
            return new string[] { "value1", "value2" };
        }

        // GET api/<controller>/5
        public string Get(int id)
        {
            return "value";
        }

        // POST api/<controller>
        public void Post([FromBody] string value)
        {
        }

        // PUT api/<controller>/5
        public void Put(int id, [FromBody] string value)
        {
        }

        // DELETE api/<controller>/5
        public void Delete(int id)
        {
        }
    }
}

 定制API

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

using System;
using System.Collections.Generic;
using System.Linq;
using System.Text;
using System.Threading.Tasks;

namespace WebApiDemo.Models
{
    public class Student
    {
        public int Id { get; set; }

        public string Name { get; set; }

        public int Age { get; set; }

        public bool Sex { get; set; }
    }
}

1. GET方式

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

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

// GET api/<controller>
public IEnumerable<Student> Get()
{
      return new Student[] { new Student() {
           Id=1,
           Name="Alan.hsiang",
           Age=20,
           Sex=true
       }, new Student() {
           Id=2,
           Name="Json.hsiang",
           Age=18,
           Sex=false
        } };
}

// GET api/<controller>/5
public Student Get(int id)
{
      return new Student()
       {
            Id = 1,
            Name = "Alan.hsiang",
            Age = 20,
            Sex = true
        };
}

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

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

 

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

 

2. POST方式

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

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

}

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

 

3. PUT方式

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

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

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

 

4. DELETE方式

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

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

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

 

 总结

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

• 访问路径，符合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方式的请求方法，且参数格式，个数不同，应该如何匹配，如下所示：

// GET api/<controller>
public IEnumerable<Student> Get()
{
      return new Student[] { new Student() {
           Id=1,
           Name="Alan.hsiang",
           Age=20,
           Sex=true
        }, new Student() {
           Id=2,
           Name="Json.hsiang",
           Age=18,
           Sex=false
        } };
}

// GET api/<controller>/5
public Student Get(int id)
{
     return new Student()
     {
          Id = 1,
          Name = "Alan.hsiang",
          Age = 20,
          Sex = true
       };
}

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

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

 

同一方式，不同名称 

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

 首先增加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进行测试，直接报错，称找到了两个符合格式的资源的，如下所示：

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

namespace WebApiDemo
{
    public static class WebApiConfig
    {
        public static void Register(HttpConfiguration config)
        {
            // Web API 配置和服务

            // Web API 路由
            config.MapHttpAttributeRoutes();

            config.Routes.MapHttpRoute(
                name: "DefaultApi",
                routeTemplate: "api/{controller}/{id}",
                defaults: new { id = RouteParameter.Optional }
            );
        }
    }
}

 

Route特性

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

[Route("api/Student/QueryStudent/{id}")]
[HttpGet]
public Student QueryStudent(int id, string name)
{
     return new Student()
     {
          Id = id,
          Name = name + "---1",
          Age = 22,
          Sex = true
     };
}

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

 

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

 

路由前缀 

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

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

namespace WebApiDemo.Controllers
{
    [RoutePrefix("api/Teacher")]
    public class TeacherController : ApiController
    {
        public string Get(int id, string name) {
            return string.Format("[Get]正在查找的老师id={0}，姓名={1}", id, name);
        }

        [Route("query/{id}")]
        [HttpGet]
        public string QueryTeacher(int id, string name) {
            return string.Format("[Query]正在查找的老师id={0}，姓名={1}", id, name);
        }
    }
}

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

 

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

 

 备注

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

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

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

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

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

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

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