ASP.NET Core Web API

网友投稿 354 2022-06-06

1.简单介绍

ASP.NET Core Web API 是 ASP.NET Core MVC 的一个功能。ASP.NET Core MVC 包含了对 Web API 的支持。可以构建多种客户端的 HTTP 服务。ASP.NET Core Web API可用于在 .NET Core 上构建 RESTful 应用程序。

框架包含对 HTTP 内容协商的支持，内置支持以 JSON 或 XML 格式化的数据。编写自定义格式化程序已添加对自有格式的支持。

使用链接生成对超媒体的支持。启用对跨资源共享（CORS）的支持，以便 Web API 可以在多个 Web应用程序之间共享。

例如，新建一个 API 项目，默认包含一个 ValuesController：

[Route("api/[controller]")]
    [ApiController]
    public class ValuesController : ControllerBase
    {
        // GET api/values
        [HttpGet]
        public ActionResult<IEnumerable<string>> Get()
        {
            return new string[] { "value1", "value2" };
        }

        // GET api/values/5
        [HttpGet("{id}")]
        public ActionResult<string> Get(int id)
        {
            return "value";
        }

        // POST api/values
        [HttpPost]
        public void Post([FromBody] string value)
        {
        }

        // PUT api/values/5
        [HttpPut("{id}")]
        public void Put(int id, [FromBody] string value)
        {
        }

        // DELETE api/values/5
        [HttpDelete("{id}")]
        public void Delete(int id)
        {
        }
    }

默认包含了 GET，POST，PUT，DELETE 这几个 HTTP 请求操作。这里直接使用特性路由，在控制器上注明 [Route("api/[controller]")]。调试并打开浏览器输入 https://localhost:5000/api/values ，会返回数据。

2.自定义格式化（Format）

ASP.NET Core MVC内建支持对相应数据的格式，用来修正格式或生成客户端指定的格式。

1.特定格式的操作结果

某些操作结果的类型是特定的格式，比如 JsonResult 或 ContentResult 。操作可以总是返回格式为特定格式的具体结果。比如返回 JsonResult 时将返回 JSON 格式化数据，而不管客户端要求的是什么格式。

操作并不要求返回任何特定的类型， MVC 支持任何对象作为返回值。如果操作返回的是 IActionResult 的某个实现，并且控制器继承自 Controller ，那么可以使用更多辅助方法。如果不是，则将使用合适的 IOutputFormatter 实现序列化对象。

若要从继承 Controller 基类的控制器返回特定格式的数据，可以使用内置的辅助方法 Json 来返回 JSON 格式，使用 Content 来返回纯文本。操作方法的返回类型必须是指定的结果类型（如 JsonResult）或 IActionResult。

[HttpGet]
        public JsonResult Get()
        {
            return Json(new User());
        }

以上代码 Content-Type 将返回 application/json。

要想返回纯文本格式的数据，则使用 ContentResult 以及 Content 辅助方法：

[HttpGet]
        public ContentResult Get()
        {
            return Content("result");
        }

以上代码 Content-Type 将返回 test/plan 。也可以使用一个字符串相应类型来实现这个行为：

[HttpGet]
        public string Get()
        {
            return "result";
        }

对于具有多个返回类型或选项的复杂操作，请选择 IActionResult 作为返回类型。

2.配置格式化程序

如果应用程序想支持默认 JSON 之外的格式，可以在 project.json 文件中添加这些额外的依赖项，并配置 MVC 来支持。输入和输出的格式是可以隔离的。输入格式通过使用模型绑定，输出格式通过格式化响应。

3.添加对 XML 格式的支持

要添加对 XML 格式的支持，需要先安装 Microsoft.AspNetCore.Mvc.Formatters.Xml 包，然后在 ConfigureServices 中配置 XmlSerializerFormatters ：

services.AddMvc()
                .AddXmlSerializerFormatters()
                .SetCompatibilityVersion(CompatibilityVersion.Version_2_1);

或者可以只添加输出格式：

services.AddMvc(options => {
                options.OutputFormatters.Add(new XmlSerializerOutputFormatter());
            })
                //.AddXmlSerializerFormatters()
                .SetCompatibilityVersion(CompatibilityVersion.Version_2_1);

这两种方法都将使用 System.Xml.Serialization.XmlSerializer 序列化结果。还可以通过添加其他相关格式来使用 System.Runtime.Serialization.DataContractSerializer :

services.AddMvc(options => {
                options.OutputFormatters.Add(new XmlDataContractSerializerOutputFormatter());
            })
                //.AddXmlSerializerFormatters()
                .SetCompatibilityVersion(CompatibilityVersion.Version_2_1);

4.强制特定格式化

若是想为某个操作限制响应格式，则可以使用 [Produces] 过滤器。[Produces] 过滤器可以为这个控制器或 Action 指定响应格式：

[HttpGet("{id}", Name = "Get")]
        [Produces("application/json")]
        public string Get(int id)
        {
            return "value";
        }

对于一些特殊情况，可能不想使用内建的格式化实现。默认情况下，返回类型为 string 时将格式化为 text/plain 。这种行为可以通过移除 TextOutputFormatter 来改变：

public void ConfigureServices(IServiceCollection services)
        {
            services.AddMvc(options => {
                options.OutputFormatters.RemoveType<TextOutputFormatter>();
                options.OutputFormatters.RemoveType<HttpNoContentOutputFormatter>();
            }).SetCompatibilityVersion(CompatibilityVersion.Version_2_1);
        }

上面移除了 TextOutputFormatter 和 HttpNoContentOutputFormatter，当返回类型为 string 时，将返回 406 Not Acceptable。如果存在 XML 格式化程序，则将格式化响应结果。

移除了 HttpNoContentOutputFormatter ，当返回某个返回类型为模型对象的操作返回 null 时，将返回 204 No Content 响应。JSON 格式将简单地返回主体信息为 null 的响应，而 XML 格式将返回一个空的带有 xsi:nil="true" 属性的 XML 元素。

5.响应格式 URL 映射

客户端可以在 URL 中请求特定的格式，比如在请求字符串或路径中，或者通过使用特定格式的文件扩展名（比如 .xml 或 .json），需要在 API 所使用的路由中指定：

[FormatFilter]
    public class UserController : Controller
    {
        // GET: api/User
        [HttpGet]
        [Route("[controller]/[action]/{id}.{format?}")]
        public IActionResult GetById(int id)
        {
            return Content("xxx");
        }
}

这个路由配置将允许使用可选的文件扩展名来指定格式。[FormatFilter] 特性将在 RouteData 中检查该格式的值是否存在，并创建响应时将响应数据映射到相应的格式：

RouteFormatter

/User/GetById/5 :默认输出格式

/User/GetById/5.json :JSON格式（如果配置过）

/User/GetById/5.xml; :XML格式（如果配置过）

6.自定义格式化程序 Protocol Buffers （简称 protobuf）

Protocol Buffers 是一种轻便高效的结构化数据存储格式，可用于结构化数据串行化，或者说序列化。它很适合做数据存储或 RPC（远程过程调用协议）数据交换格式。可用于通讯协议，数据存储等领域的语言无关，平台无关，可扩展的序列化结构数据格式。比如实现一个程序返回 protobuf 格式：

创建 API 项目，添加 protobuf-net 引用。

添加 ProtobufFormatter 类：

public class ProtobufFormatter:OutputFormatter
    {
        public string ContentType { get; private set; }
        public ProtobufFormatter()
        {
            ContentType = "application/proto";
            SupportedMediaTypes.Add(MediaTypeHeaderValue.Parse("application/proto"));
        }

        public override Task WriteResponseBodyAsync(OutputFormatterWriteContext context)
        {
            if (context == null)
            {
                throw new ArgumentNullException(nameof(context));
            }
            var response = context.HttpContext.Response;
            Serializer.Serialize(response.Body,context.Object);
            return Task.FromResult(0);
        }

    }

继承 OutputFormatter ，然后实现 WriteResponseBodyAsync 方法，初始化时赋值 ContentType ，并添加支持 MediaType。在 WriteResponseBodyAsync 方法中获取 Response ，调用 protobuf-net 的 Serializer.Serialize 方法将 Object 序列化至输出内容。 protobuf 在序列化时必须指定顺序，添加 User 类，实现 protobuf 实体：

[ProtoContract]
    public class User
    {
        [ProtoMember(1)]
        public int Id { get; set; }
        [ProtoMember(2)]
        public string Name { get; set; }
        [ProtoMember(3)]
        public int Age { get; set; }
    }

类上需要添加 [ProtoContract] 特性，字段上需要 ProtoMember 特性，并指定顺序。然后修改 UserController:

[Route("api/[controller]")]
    [ApiController]
    [FormatFilter]
    public class UserController : Controller
    {
        private IEnumerable<User> users;
        public UserController()
        {
            users = new User[] {
                new User(){ Id=1,Name="Bob",Age = 20},
                new User(){ Id=2,Name="Tom",Age = 22}
            };
        }
        // GET: api/User
        [HttpGet]
        [Produces("application/proto")]
        public IEnumerable<User> Get()
        {
            return users;
        }
}

修改 ConfigureServices ：

public void ConfigureServices(IServiceCollection services)
        {
            services.AddMvc(options => {
                options.OutputFormatters.Add(new ProtobufFormatter());
            }).SetCompatibilityVersion(CompatibilityVersion.Version_2_1);
        }

运行程序，会返回一个二进制文件。

创建一个控制台，检查序列化：

class Program
    {
        static void Main(string[] args)
        {
            HttpClient client = new HttpClient();
            var stream = client.GetStreamAsync("https://localhost:44358/api/User").Result;
            var users = Serializer.Deserialize<List<User>>(stream);
            foreach (var user in users)
            {
                Console.WriteLine($"Id:{user.Id} - Name:{user.Name} - Age:{user.Age}");
            }
            Console.ReadKey();
        }
    }

到此这篇关于ASP.NET Core Web API的文章就介绍到这了。希望对大家的学习有所帮助，也希望大家多多支持。

标签：api

暂时没有评论，来抢沙发吧~

ASP.NET Core Web API

1.简单介绍

2.自定义格式化（Format）

1.特定格式的操作结果

2.配置格式化程序

3.添加对 XML 格式的支持

4.强制特定格式化

5.响应格式 URL 映射

6.自定义格式化程序 Protocol Buffers （简称 protobuf）

java 单机接口限流处理方案

使用SpringBoot实现API接口

Python怎么调用GPT3.5接口

推荐文章

接口调用是什么意思？几种常用接口调用方式

接口设计原则

8款在线 API 接口文档管理工具

api管理系统是什么？

什么是接口调试？接口调试的步骤有哪些？

api 接口管理系统有哪些？

接口测试有几种测试方法

API文档生成工具有哪些？

微服务和api网关区别

交换机配置步骤

最近发表

热评文章

在线接口文档管理工具推荐，支持在线测试，HTTP接口

开源的在线接口文档wiki工具Mindoc的介绍与使

如何优雅的进行接口设计？接口设计的六大原则是什么？

什么是API测试,api检测公司

软件接口设计怎么做？前后端分离软件接口设计思路

接口管理平台推荐，几大接口管理平台总有一款适合你！