RESTful API ASP.NET Core 标签

  • 一句话的事儿:说白了就是通过API创建一些别人不关心的内部逻辑只在乎功能的那些玩意,与此同时,RESTful只是Roy Fielding博士定义的一种API风格,普遍被行业接受而已。

Web API 与RESTful API 简介

先决条件

预备知识:ASP.NET Core 和 C#
工具:Visual Studio 2019最新版(VSCode、VS for Mac,Rider等也凑合),POSTMAN

Web API

Web API通常是指“使用HTTP协议并通过网络调用的API”,由于它使用了HTTP协议,所以需要通过URI信息来指定端点。

API是Application Programming Interface的缩写,是软件的外部接口。也就是说,针对某个软件,人们可以知道它的外部功能,但并不知道(也不需要知道)它的内部运作细节,为了从外部调用某些功能,需要指定软件的调用规范等信息,这样的规范就是API。
所以Web API就是一个Web系统,通过访问URI可以与其进行信息交互。

大多数的 Web API 并不是 RESTful API

REST一词是在2000年首次出现的,它是由Roy Fielding博士在《架构风格以及基于网路的软件架构设计》这篇论文中提到的。他为REST风格的API制定了一套约束规范或者叫架构风格。
所以准确的说,只有符合了Roy Fielding架构风格的Web API才能称作是RESTful API。但是在实际开发中,有时候也有不完全符合Roy Fielding架构风格的情形出现,针对这点我将会在稍后的文章中介绍。

MVC模式与RESTful API

本系列文章中我将使用ASP.NET Core 3.0 MVC 来构建 RESTful API。

MVC(Model-View-Controller)我认为是一种主要用来构建UI的架构模式。对于MVC模式其实有很多种解释存在,但是无论那种解释,它们都会强调松耦合和关注点分离(separation of concerns)。
也是由于这两点的存在,程序的可测试性会大大提高,程序各部分的可复用性也很高。
更多关于MVC的介绍,可以看一下微软的官方文档:https://docs.microsoft.com/zh-cn/aspnet/core/mvc/overview?view=aspnetcore-3.0

注意:MVC不是一个完整的应用程序架构,我认为它主要是用在展示层。所以实现UI就是MVC的一部分工作。

如何把MVC映射到API

我认为API同样可以看作是UI,它就是为API消费者所提供的UI。
让我们把MVC的三部分分别对应到API:

  • Model,它负责处理程序数据的逻辑。这里的Model可以包含在当前级别获取从存储获取数据的逻辑。但是有一些Model不包含任何逻辑,例如API所使用的DTO(Data transfer objects),这类的Model会被串行化到响应的body里面。
  • View,它是程序里负责展示数据的那部分。在构建API的时候,View就是数据或资源的展示。现在通常使用JSON格式。
  • Controller,它负责View和Model之间的交互。包括处理用户输入,用API的术语来讲,和API交互的“用户”就是指API的消费者,这类用户通常是另一个程序,例如Angular的SPA程序。


    下面看看MVC这三部分的依赖关系:
    image.png
    Controller和View依赖于Model,Controller依赖于View,这也是分离的一个好处。
    换句话说,Controller会选取适当的View来展现给用户,并一同把用户请求的Model数据带回去。

    当API消费者发出请求的时候,在Controller上面的Action将会被触发,Controller会把接收到的输入数据发送给负责业务处理逻辑或数据访问逻辑的那部分程序。然后Controller会把Model返回给View,这里的View就是资源的展示(通常是JSON格式)。

    接下来我们就是用这套概念和ASP.NET Core 3.0 来创建RESTful API。
    但是请注意,通过ASP.NET Core MVC或API模板建立出来的新项目,我们并不会直接得到RESTful(REST架构风格)的API。我们必须在这个基础上,自己构建RESTful的API,因为之前已经提到了,标准的RESTful API有很多约束和规范。

image.png
image.png
image.png
image.png
image.png

创建ASP.NET Core 3.0 Web API项目

  1. 创建项目,选择 Create a new project

image.png

  1. 搜索ASP.NET Core—>点击Click

image.png

  1. 创建项目的解决方案名称为Routine,项目名称为Routine.API —>点击Create
  2. image.png
  3. 相关项目的配置选项 —>点击Create

image.png

  1. 创建成功

image.png

  1. 删除两个默认的Controller,即weatherforecastcontroller,weatherforecast
  2. ASP.NET Core 请求管道

image.png

  1. 更改Properties配置

    1. {
    2. "$schema": "http://json.schemastore.org/launchsettings.json",
    3. "profiles": {
    4. "Routine.API": {
    5. "commandName": "Project",
    6. "launchBrowser": true,
    7. "launchUrl": "weatherforecast",
    8. "applicationUrl": "http://localhost:5000",
    9. "environmentVariables": {
    10. "ASPNETCORE_ENVIRONMENT": "Development"
    11. }
    12. }
    13. }
    14. }
  2. 此时启动一下程序

image.png

  1. 这是因为我们之前把weather删除的原因,导致找不到对应的controller
  2. 增加轻量级数据库SQL Lite,通过NUGET安装

image.png

  1. 接着安装Microsoft.EntityFrameCore.Tools用于迁移使用

image.png

  1. 安装结果如下:

image.png

  1. 创建实体数据文件夹Entities —>并创建实体Company,Employee,Gender (目的是创建数据源模型)

Company

  1. using System;
  2. using System.Collections.Generic;
  3. using System.Linq;
  4. using System.Threading.Tasks;
  5. namespace Routine.API.Entities
  6. {
  7. public class Company
  8. {
  9. public Guid Id { get; set; }
  10. public string Name { get; set; }
  11. public string Introduction { get; set; }
  12. public ICollection<Employee> Employees { get; set; }
  13. }
  14. }

Employee

  1. using System;
  2. using System.Security.AccessControl;
  3. namespace Routine.API.Entities
  4. {
  5. public class Employee
  6. {
  7. public Guid Id { get; set; }
  8. public Guid CompanyId { get; set; }
  9. public string EmployeeNo { get; set; }
  10. public string FirstName { get; set; }
  11. public string LastName { get; set; }
  12. public Gender Gender { get; set; }
  13. public DateTime DateOfBirth { get; set; }
  14. public Company Company { get; set; }
  15. }
  16. }

Gender

  1. namespace Routine.API.Entities
  2. {
  3. public enum Gender
  4. {
  5. = 1,
  6. = 2
  7. }
  8. }
  1. 创建好数据模型,就需要把这些数据存放到容器中,所以创建文件夹Data,并创建齐操作类RoutineDbContext ```csharp using Microsoft.EntityFrameworkCore; using Routine.API.Entities; using System; using System.Collections.Generic; using System.Linq; using System.Threading.Tasks;

namespace Routine.API.Data { public class RoutineDbContext : DbContext { public RoutineDbContext(DbContextOptions options) : base(options) {

  1. }
  2. public DbSet<Company> Companies { get; set; }
  3. public DbSet<Employee> Employees { get; set; }
  4. //做一些限制 override OnModelCreating
  5. protected override void OnModelCreating(ModelBuilder modelBuilder)
  6. {
  7. modelBuilder.Entity<Company>().Property(x => x.Name).IsRequired().HasMaxLength(100);
  8. modelBuilder.Entity<Company>().Property(x => x.Introduction).IsRequired().HasMaxLength(500);
  9. modelBuilder.Entity<Employee>().Property(x => x.EmployeeNo).IsRequired().HasMaxLength(10);
  10. modelBuilder.Entity<Employee>().Property(x => x.FirstName).IsRequired().HasMaxLength(50);
  11. modelBuilder.Entity<Employee>().Property(x => x.LastName).IsRequired().HasMaxLength(50);
  12. modelBuilder.Entity<Employee>()
  13. .HasOne(x => x.Company)
  14. .WithMany(x => x.Employees)
  15. .HasForeignKey(x => x.CompanyId).OnDelete(DeleteBehavior.Restrict);
  16. modelBuilder.Entity<Company>().HasData(
  17. new Company
  18. {
  19. Id = Guid.Parse("A732F0A4-B087-4783-954C-735205FA9A6E"),
  20. Name = "Micorsoft",
  21. Introduction = "Greate Company"
  22. },
  23. new Company
  24. {
  25. Id = Guid.Parse("C2A2C0B9-17A0-4246-B6AE-40E24D98FEB8"),
  26. Name = "Google",
  27. Introduction = "Don't be evil."
  28. },
  29. new Company
  30. {
  31. Id = Guid.Parse("EEEE8651-338A-46AE-9D82-CFE486F54F3D"),
  32. Name = "Alipapa",
  33. Introduction = "Fubao Company"
  34. });
  35. }
  36. }

}

  1. 16. 创建好数据模型还得具体操作,这里采用接口的方式ICompanyRepository,实现接口是类CompanyRepository
  2. ```csharp
  3. using Routine.API.Entities;
  4. using System;
  5. using System.Collections.Generic;
  6. using System.Linq;
  7. using System.Threading.Tasks;
  8. namespace Routine.API.Services
  9. {
  10. interface ICompanyRepository
  11. {
  12. Task<IEnumerable<Company>> GetCompaniesAsync();
  13. Task<Company> GetCompanyAsync(Guid companyId);
  14. Task<IEnumerable<Company>> GetCompaniesAsync(IEnumerable<Guid> companyIds);
  15. void AddCompany(Company company);
  16. void UpdateCompany(Company company);
  17. void DeleteCompany(Company company);
  18. Task<bool> CompanyExistsAsync(Guid companyId);
  19. Task<IEnumerable<Employee>> GetEmployeesAsync(Guid companyId);
  20. Task<Employee> GetEmployeeAsync(Guid companyId, Guid employId);
  21. void AddEmployee(Guid companyId, Employee employee);
  22. void UpdateEmployee(Employee employee);
  23. void DeleteEmployee(Employee employee);
  24. Task<bool> SaveAsync();
  25. }
  26. }
  1. using Routine.API.Data;
  2. using System;
  3. using System.Collections.Generic;
  4. using System.Linq;
  5. using System.Threading.Tasks;
  6. using Routine.API.Entities;
  7. using Microsoft.EntityFrameworkCore;
  8. namespace Routine.API.Services
  9. {
  10. public class CompanyRepository : ICompanyRepository
  11. {
  12. private readonly RoutineDbContext _context;
  13. public CompanyRepository(RoutineDbContext context)
  14. {
  15. _context = context ?? throw new ArgumentNullException(nameof(context));
  16. }
  17. public async Task<IEnumerable<Company>> GetCompaniesAsync()
  18. {
  19. return await _context.Companies.ToListAsync();
  20. }
  21. public async Task<Company> GetCompanyAsync(Guid companyId)
  22. {
  23. if (companyId == Guid.Empty)
  24. {
  25. throw new ArgumentNullException(nameof(companyId));
  26. }
  27. return await _context.Companies.FirstOrDefaultAsync(x => x.Id == companyId);
  28. }
  29. //通过多个companyIds获取多个公司
  30. public async Task<IEnumerable<Company>> GetCompaniesAsync(IEnumerable<Guid> companyIds)
  31. {
  32. if (companyIds == null)
  33. {
  34. throw new ArgumentNullException(nameof(companyIds));
  35. }
  36. return await _context.Companies
  37. .Where(x => companyIds.Contains(x.Id))
  38. .OrderBy(x => x.Name)
  39. .ToListAsync();
  40. }
  41. public void AddCompany(Company company)
  42. {
  43. if (company == null)
  44. {
  45. throw new ArgumentNullException(nameof(company));
  46. }
  47. company.Id = Guid.NewGuid();
  48. foreach (var employee in company.Employees)
  49. {
  50. employee.Id = Guid.NewGuid();
  51. }
  52. _context.Companies.Add(company);
  53. }
  54. public void UpdateCompany(Company company)
  55. {
  56. //_context.Entry(company).State == EntityState.Modified;
  57. }
  58. public void DeleteCompany(Company company)
  59. {
  60. if (company == null)
  61. {
  62. throw new ArgumentNullException(nameof(company));
  63. }
  64. _context.Companies.Remove(company);
  65. }
  66. public async Task<bool> CompanyExistsAsync(Guid companyId)
  67. {
  68. if (companyId == Guid.Empty)
  69. {
  70. throw new ArgumentNullException(nameof(companyId));
  71. }
  72. return await _context.Companies.AnyAsync(x => x.Id == companyId);
  73. }
  74. public async Task<IEnumerable<Employee>> GetEmployeesAsync(Guid companyId)
  75. {
  76. if (companyId == Guid.Empty)
  77. {
  78. throw new ArgumentNullException(nameof(companyId));
  79. }
  80. return await _context.Employees
  81. .Where(x => x.CompanyId == companyId)
  82. .OrderBy(x => x.EmployeeNo)
  83. .ToListAsync();
  84. }
  85. //获取公司某一位员工
  86. public async Task<Employee> GetEmployeeAsync(Guid companyId, Guid employeeId)
  87. {
  88. if (companyId == Guid.Empty)
  89. {
  90. throw new ArgumentNullException(nameof(companyId));
  91. }
  92. if (employeeId == Guid.Empty)
  93. {
  94. throw new ArgumentNullException(nameof(employeeId));
  95. }
  96. return await _context.Employees
  97. .Where(x => x.CompanyId == companyId && x.Id == employeeId)
  98. .FirstOrDefaultAsync();
  99. }
  100. //添加员工
  101. public void AddEmployee(Guid companyId, Employee employee)
  102. {
  103. if (companyId == Guid.Empty)
  104. {
  105. throw new ArgumentNullException(nameof(companyId));
  106. }
  107. if (employee == null)
  108. {
  109. throw new ArgumentNullException(nameof(employee));
  110. }
  111. employee.CompanyId = companyId;
  112. _context.Employees.Add(employee);
  113. }
  114. //更新员工信息
  115. public void UpdateEmployee(Employee employee)
  116. {
  117. //_context.Entry(employee).State = EntityState.Modified;
  118. }
  119. public void DeleteEmployee(Employee employee)
  120. {
  121. _context.Employees.Remove(employee);
  122. }
  123. public async Task<bool> SaveAsync()
  124. {
  125. return await _context.SaveChangesAsync() >= 0;
  126. }
  127. }
  128. }
  1. 实现了对数据的操作,还需要对其进行容器注册 ```csharp using System; using System.Collections.Generic; using System.Linq; using System.Threading.Tasks; using Microsoft.AspNetCore.Builder; using Microsoft.AspNetCore.Hosting; using Microsoft.AspNetCore.Mvc; using Microsoft.EntityFrameworkCore; using Microsoft.Extensions.Configuration; using Microsoft.Extensions.DependencyInjection; using Microsoft.Extensions.Hosting; using Microsoft.Extensions.Logging; using Routine.API.Data; using Routine.API.Services;

namespace Routine.API { public class Startup { public Startup(IConfiguration configuration) { Configuration = configuration; }

  1. public IConfiguration Configuration { get; }
  2. // This method gets called by the runtime. Use this method to add services to the container.
  3. public void ConfigureServices(IServiceCollection services)
  4. {
  5. services.AddControllers();
  6. services.AddScoped<ICompanyRepository, CompanyRepository>();
  7. services.AddDbContext<RoutineDbContext>(option =>
  8. {
  9. option.UseSqlite("Data Source=routine.db");
  10. });
  11. }
  12. // This method gets called by the runtime. Use this method to configure the HTTP request pipeline.
  13. public void Configure(IApplicationBuilder app, IWebHostEnvironment env)
  14. {
  15. if (env.IsDevelopment())
  16. {
  17. app.UseDeveloperExceptionPage();
  18. }
  19. app.UseRouting();
  20. app.UseAuthorization();
  21. app.UseEndpoints(endpoints =>
  22. {
  23. endpoints.MapControllers();
  24. });
  25. }
  26. }

} ``` :::info 特别值得说明的是,为了演示需要,采用每一次改动后,均会做删除数据库并再次迁移数据的处理哦! :::

  1. 最后还要说明的是,初次启用,需要手动迁移 —
    1. 搜索Package manager
    2. add-migration initial

image.png

  1. 此时运行程序 —>不要关心报错,只要终端显示的log级别是info就不要关心

image.png

  1. 紧接着解决方案中会生成数据库文件

image.png

  1. 最后可以检查这个数据库中的数据是否有正确插入,这里主要插入了三个公司。推荐使用JetBrains的DG,由于时间太晚了,明天晚上再更新吧,晚安,又是一天新的开始,加油(⊙o⊙)

更新,下载DataGrip
image.png
image.png


  • 本文作者:GeekPower - Felix Sun
  • 版权声明: 本博客所有文章除特别声明外,均采用 MIT 许可协议。转载请注明出处!