ASP.NET Core 2 学习笔记(十二)REST-Like API

简介: 原文:ASP.NET Core 2 学习笔记(十二)REST-Like APIRestful几乎已算是API设计的标准,通过HTTP Method区分新增(Create)、查询(Read)、修改(Update)和删除(Delete),简称CRUD四种数据存取方式,简约又直接的风格,让人用的爱不释手。
原文: ASP.NET Core 2 学习笔记(十二)REST-Like API

Restful几乎已算是API设计的标准,通过HTTP Method区分新增(Create)、查询(Read)、修改(Update)和删除(Delete),简称CRUD四种数据存取方式,简约又直接的风格,让人用的爱不释手。
本篇将介绍如何通过ASP.NET Core实践REST-Like API。

为什么是REST-Like 而不是 REST?

本文API设计未符合HATEOAS(Hypermedia As The Engine Of Application State)原则,所以不得称为RESTful API。

RESTful API 有四个重要的原则要遵守:

  1. Level 0
    使用HTTP做为资料传输的媒介。
  2. Level 1
    不要提供一个包山包海的API,而是要区分资源,每个资源都该有对应的API。
  3. Level 2
    透过HTTP Method区分新增(Create)、查询(Read)、修改(Update)跟删除(Delete)。
  4. Level 3
    对同资源可以用链结表达的方式,向下延伸查询或修改。
    参考:HATEOAS

HTTP Method

REST-Like API 对数据的操作行为,通过HTTP Method 分为以下四种方式:

  • 新增(Create)
    用HTTP POST通过Body传递JSON或XML格式的数据给Server。例如:

POST http://localhost:5000/api/users
{
   "id": 1,
   "name": "SnailDev"
}
  • 查询(Read)
    用HTTP GET通过URL带查询参数。通常查询单一资源会用路由参数(Routing Parameter)带上唯一值(Primary Key);多笔查询会用复数,而查询条件用Query String。例如:

# 单笔查询
GET http://localhost:5000/api/users/1
# 多笔查询
GET http://localhost:5000/api/users
# 多笔查询带条件
GET http://localhost:5000/api/users?q=SnailDev
  • 修改(Update)
    修改数据如同查询跟新增的组合,用HTTP PUT通过URL带路由参数,找到要修改的目标;再通过Body传递JSON或XML格式的数据给Server。例如:

PUT http://localhost:5000/api/users/1
{
   "name": "SnailDev"
}
  • 删除(Delete)
    删除数据同查询,用HTTP DELETE通过URL带路由参数,找到要删除的目标。例如:

DELETE http://localhost:5000/api/users/1

HTTP Method Attribute

ASP.NET Core 2 学习笔记(六)MVC 有提到,过去ASP.NET MVC把MVC及Web API的套件分开,但在ASP.NET Core中MVC及Web API用的套件是相同的。所以只要装Microsoft.AspNetCore.Mvc套件就可以用Web API了。路由方式也跟ASP.NET Core 2 学习笔记(七)路由 介绍的RouteAttribute差不多,只是改用HTTP Method Attribute。

HTTP Method Attribute 符合RESTful 原则的路由设定方式如下:

[Route("api/[controller]s")]
public class UserController : Controller
{
    [HttpGet]
    public List<UserModel> Get(string q)
    {
        // ...
    }

    [HttpGet("{id}")]
    public UserModel Get(int id)
    {
        // ...
    }

    [HttpPost]
    public int Post([FromBody]UserModel user)
    {
        // ...
    }

    [HttpPut("{id}")]
    public void Put(int id, [FromBody]UserModel user)
    {
        // ...
    }

    [HttpDelete("{id}")]
    public void Delete(int id)
    {
        // ...
    }
}

目前ASP.NET Core 还没有像ASP.NET MVC 的MapHttpAttributeRoutes 可以绑Http Method 的全局路由,都要在Action 加上HTTP Method Attribute。

SerializerSettings

 用以下代码,说明SerializerSettings

public class UserModel
{
    public int Id { get; set; }
    public string Name { get; set; }
    public string Email { get; set; }    
    public string PhoneNumber { get; set; }
    public string Address { get; set; }
}

// ...

[Route("api/[controller]s")]
public class UserController : Controller
{
  [HttpGet("{id}")]
  public UserModel Get(int id)
  {
      return new UserModel {
          Id = 1,
          Name = "SnailDev"
      };
  }
}

camel Case

过去ASP.NET Web API 2预设是Pascal Case;而ASP.NET Core预设是使用camel Case。
若想要指定用ContractResolver,可以在Startup.csConfigureServices加入MVC服务时,使用AddJsonOptions设定如下:

// ...
public class Startup
{
    public void ConfigureServices(IServiceCollection services)
    {        
        services.AddMvc()
                .AddJsonOptions(options => 
                {
                    options.SerializerSettings.ContractResolver 
                        = new CamelCasePropertyNamesContractResolver();
                });
        // 同以下写法:
        // services.AddMvc();
    }
}

访问http://localhost:5000/api/users/1会返回JSON如下:

{
    "id": 1,
    "name": "SnailDev",
    "email": null,
    "phoneNumber": null,
    "address": null
}

Pascal Case

若想保持跟ASP.NET Web API 2一样使用Pascal Case,ContractResolver则改用DefaultContractResolver

// ...
public class Startup
{
    public void ConfigureServices(IServiceCollection services)
    {        
        services.AddMvc()
                .AddJsonOptions(options => 
                {
                    options.SerializerSettings.ContractResolver 
                        = new DefaultContractResolver();
                });
    }
}

DefaultContractResolver名称是延续ASP.NET,虽然名称叫Default,但在ASP.NET Core它不是Default。CamelCasePropertyNamesContractResolver才是ASP.NET Core的Default ContractResolver。

访问http://localhost:5000/api/users/1会返回JSON如下:

{
    "Id": 1,
    "Name": "SnailDev",
    "Email": null,
    "PhoneNumber": null,
    "Address": null
}

Ignore Null

上述两个JSON 回传,都带有null 的字段。在序列化的过程,找不到字段会自动转成null,传送的过程忽略掉也没错,反而可以节省到一点流量。

// ...
public class Startup
{
    public void ConfigureServices(IServiceCollection services)
    {        
        services.AddMvc()
                .AddJsonOptions(options => 
                {
                    options.SerializerSettings.NullValueHandling 
                        = Newtonsoft.Json.NullValueHandling.Ignore;
                });
    }
}

访问http://localhost:5000/api/users/1会返回JSON如下:

{
    "id": 1,
    "name": "SnailDev"
}

示例程序

Startup.cs

public class Startup
{
    public void ConfigureServices(IServiceCollection services)
    {
        services.AddMvc()
                .AddJsonOptions(options => {
                    options.SerializerSettings.NullValueHandling
                        = Newtonsoft.Json.NullValueHandling.Ignore;
                });
    }

    public void Configure(IApplicationBuilder app)
    {
        app.UseMvc();
    }
}

Models\ResultModel.cs

namespace MyWebsite.Models
{
    public class ResultModel
    {
        public bool IsSuccess { get; set; }
        public string Message { get; set; }
        public object Data { get; set; }
    }
}

用一个ResultModel 来包装每个API 回传的内容,不论调用Web API 成功失败都用此对象包装,避免直接throw exception 到Client,产生HTTP Status 200 以外的状态。 

Controllers/UserController.cs

using System.Collections.Generic;
using System.Linq;
using System.Text.RegularExpressions;
using Microsoft.AspNetCore.Mvc;
using MyWebsite.Models;

namespace MyWebsite.Controllers
{
    [Route("api/[controller]s")]
    public class UserController : Controller
    {
        private static List<UserModel> _users = new List<UserModel>();

        [HttpGet]
        public ResultModel Get(string q)
        {
            var result = new ResultModel();
            result.Data = _users.Where(c => string.IsNullOrEmpty(q) 
                                         || Regex.IsMatch(c.Name, q, RegexOptions.IgnoreCase));
            result.IsSuccess = true;
            return result;
        }

        [HttpGet("{id}")]
        public ResultModel Get(int id)
        {
            var result = new ResultModel();
            result.Data = _users.SingleOrDefault(c => c.Id == id);
            result.IsSuccess = true;
            return result;
        }

        [HttpPost]
        public ResultModel Post([FromBody]UserModel user)
        {
            var result = new ResultModel();
            user.Id = _users.Count() == 0 ? 1 : _users.Max(c => c.Id) + 1;
            _users.Add(user);
            result.Data = user.Id;
            result.IsSuccess = true;
            return result;
        }

        [HttpPut("{id}")]
        public ResultModel Put(int id, [FromBody]UserModel user)
        {
            var result = new ResultModel();
            int index;
            if ((index = _users.FindIndex(c => c.Id == id)) != -1)
            {
                _users[index] = user;
                result.IsSuccess = true;
            }
            return result;
        }

        [HttpDelete("{id}")]
        public ResultModel Delete(int id)
        {
            var result = new ResultModel();
            int index;
            if ((index = _users.FindIndex(c => c.Id == id)) != -1)
            {
                _users.RemoveAt(index);
                result.IsSuccess = true;
            }
            return result;
        }
    }
}

执行结果

通过Postman 测试API。

  • 新增(Create)

  • 查询(Read)

  • 修改(Update)

  • 删除(Delete)

参考

Routing in ASP.NET Core 
Attribute Routing in ASP.NET Core 
Richardson Maturity Model 
HATEOAS

 

老司机发车啦:https://github.com/SnailDev/SnailDev.NETCore2Learning

目录
相关文章
|
14天前
|
开发框架 .NET 开发者
简化 ASP.NET Core 依赖注入(DI)注册-Scrutor
Scrutor 是一个简化 ASP.NET Core 应用程序中依赖注入(DI)注册过程的开源库,支持自动扫描和注册服务。通过简单的配置,开发者可以轻松地从指定程序集中筛选、注册服务,并设置其生命周期,同时支持服务装饰等高级功能。适用于大型项目,提高代码的可维护性和简洁性。仓库地址:&lt;https://github.com/khellang/Scrutor&gt;
36 5
|
2月前
|
存储 开发框架 JSON
ASP.NET Core OData 9 正式发布
【10月更文挑战第8天】Microsoft 在 2024 年 8 月 30 日宣布推出 ASP.NET Core OData 9,此版本与 .NET 8 的 OData 库保持一致,改进了数据编码以符合 OData 规范,并放弃了对旧版 .NET Framework 的支持,仅支持 .NET 8 及更高版本。新版本引入了更快的 JSON 编写器 `System.Text.UTF8JsonWriter`,优化了内存使用和序列化速度。
|
1月前
|
开发框架 .NET C#
在 ASP.NET Core 中创建 gRPC 客户端和服务器
本文介绍了如何使用 gRPC 框架搭建一个简单的“Hello World”示例。首先创建了一个名为 GrpcDemo 的解决方案,其中包含一个 gRPC 服务端项目 GrpcServer 和一个客户端项目 GrpcClient。服务端通过定义 `greeter.proto` 文件中的服务和消息类型,实现了一个简单的问候服务 `GreeterService`。客户端则通过 gRPC 客户端库连接到服务端并调用其 `SayHello` 方法,展示了 gRPC 在 C# 中的基本使用方法。
41 5
在 ASP.NET Core 中创建 gRPC 客户端和服务器
|
22天前
|
开发框架 缓存 .NET
GraphQL 与 ASP.NET Core 集成:从入门到精通
本文详细介绍了如何在ASP.NET Core中集成GraphQL,包括安装必要的NuGet包、创建GraphQL Schema、配置GraphQL服务等步骤。同时,文章还探讨了常见问题及其解决方法,如处理复杂查询、错误处理、性能优化和实现认证授权等,旨在帮助开发者构建灵活且高效的API。
24 3
|
2月前
|
开发框架 .NET API
Windows Forms应用程序中集成一个ASP.NET API服务
Windows Forms应用程序中集成一个ASP.NET API服务
109 9
|
2月前
mcr.microsoft.com/dotnet/core/aspnet:2.1安装libgdiplus
mcr.microsoft.com/dotnet/core/aspnet:2.1安装libgdiplus
35 1
|
3月前
|
开发框架 监控 前端开发
在 ASP.NET Core Web API 中使用操作筛选器统一处理通用操作
【9月更文挑战第27天】操作筛选器是ASP.NET Core MVC和Web API中的一种过滤器,可在操作方法执行前后运行代码,适用于日志记录、性能监控和验证等场景。通过实现`IActionFilter`接口的`OnActionExecuting`和`OnActionExecuted`方法,可以统一处理日志、验证及异常。创建并注册自定义筛选器类,能提升代码的可维护性和复用性。
|
3月前
|
开发框架 .NET 中间件
ASP.NET Core Web 开发浅谈
本文介绍ASP.NET Core,一个轻量级、开源的跨平台框架,专为构建高性能Web应用设计。通过简单步骤,你将学会创建首个Web应用。文章还深入探讨了路由配置、依赖注入及安全性配置等常见问题,并提供了实用示例代码以助于理解与避免错误,帮助开发者更好地掌握ASP.NET Core的核心概念。
111 3
|
2月前
|
开发框架 JavaScript 前端开发
一个适用于 ASP.NET Core 的轻量级插件框架
一个适用于 ASP.NET Core 的轻量级插件框架
|
3月前
|
开发框架 NoSQL .NET
利用分布式锁在ASP.NET Core中实现防抖
【9月更文挑战第5天】在 ASP.NET Core 中,可通过分布式锁实现防抖功能,仅处理连续相同请求中的首个请求,其余请求返回 204 No Content,直至锁释放。具体步骤包括:安装分布式锁库如 `StackExchange.Redis`;创建分布式锁服务接口及其实现;构建防抖中间件;并在 `Startup.cs` 中注册相关服务和中间件。这一机制有效避免了短时间内重复操作的问题。