現在的 Web 開發大多都是前后端分離的方式，后端介面的正確使用顯得尤為重要，本文講下在 dotNET Core 3.X 下使用 Web API ，
環境
- 作業系統：Mac
- IDE：Rider
- dotNET Core：3.1
創建專案
如果是 Windows 作業系統當然是首選 VS2019 ，在 Mac 中雖然也有 VS2019 For Mac，但還是感覺 Rider 比較好用（除錯和智能提示），在 Rider 中創建 Web API 專案：
3.x 和 2.x 區別
1、Program 類的 IWebHostBuilder 修改為了 IHostBuilder，這一塊的改動如果是直接使用3.x可以不用過于關心，如果是從 2.x升級到3.x，就要注意了，對比結果如下圖：
2、Startup 類的區別如下圖：
最重要的還是在 3.x 中使用的是 services.AddControllers(); 來注冊服務，相比較 2.x 中的 services.AddMvc() 更加輕量級，因為在 AddMvc 方法中添加了很多 WebAPI 不需要的功能，如下圖：
3、3.x 引入了新的JSON API,新的JSON API使用更少的記憶體，擁有更快的執行速度,參考 using System.Text.Json; 就可以使用，如果需要使用原來的功能，需要引入 Nuget包：Microsoft.AspNetCore.Mvc.NewtonsoftJson
另：
-
有關 3.x 中被洗掉的程式集可以參考這里：https://github.com/dotnet/aspnetcore/issues/3755
-
有關 3.x 中性能提升可以參考這篇文章：https://devblogs.microsoft.com/dotnet/performance-improvements-in-net-core-3-0/
[ApiController] 特性
在 3.x 中默認專案模板中會創建的一個名為 WeatherForecastController 的控制器，按照約束控制器類以 Controller 結尾，
可以看到在 WeatherForecastController 類的上面自動添加了 [ApiController] 特性，添加此特性后，會對 Api 功能有所加持，比如：
自動模型狀態驗證
意思是當客戶端傳遞的模型資料不符合要求時，在介面方法中不需要做任何處理，介面會自動回傳 400 的錯誤,看下面的例子：
1、創建 UserController 類，先將 [ApiController] 特性注釋掉；
2、添加 User 類，將 Name 屬性設定為 Required；
public class User
{
[Required]
public string Name { get; set; }
public string Code { get; set; }
}
3、在 UserController 類中添加 AddUser 方法
[HttpPost]
[Route("adduser")]
public ActionResult AddUser(User user)
{
return Ok();
}
4、使用 Postman 呼叫，沒有添加任何引數，回傳的結果為 200
這個結果不是我們所期望的，之前沒有 [ApiController] 特性的時候，需要在介面方法中處理，如下：
[HttpPost]
[Route("adduser")]
public ActionResult AddUser(User user)
{
if (!ModelState.IsValid)
{
return BadRequest((ModelState));
}
return Ok();
}
5、再用 Postman 呼叫，結果如下：
6、現在添加上 [ApiController] 特性，并將 AddUser 中的校驗邏輯去掉，再次使用 Postman，結果如下：
推斷引數系結源
之前需要在引數上添加 [FromBody]、[FromQuery]等特性，現在可以去掉這些特性，系統會自動推斷引數的來源，比如：如果一個引數在 Route 里面定義了，會自動從先從Path 查找，沒找到會從查詢引數上查找然后進行系結，
錯誤狀態碼詳細資訊
之前的版本中，如果介面回傳一個 BadRequest，是沒有內容的，只有狀態碼，如下：
加上 [ApiController] 特性后，結果如下：
基類
在 3.x 中創建控制器后，默認的基類為 ControllerBase ，該類中提供了 OK、BadRequest 等常用方法給我們使用，
在我們實際開發中，通常會自定義添加一個所有 Controller 類的基礎類，一些通用的功能可以放到基類中，比如，對 AutoMapper 的注入，代碼如下：
public class BaseController: ControllerBase
{
private readonly IMapper _mapper;
public BaseController(IMapper mapper)
{
_mapper = mapper;
}
public IMapper Mapper => _mapper;
}
HTTP 方法
先看下面這張圖
按照標準的 RESTful Web API 風格，不同的請求動作需要使用相對應的方法，但實際我們最常用的是 GET 和 POST，查詢使用 GET，其他的操作都是使用 POST，
HTTP 狀態碼
正確的回傳狀態碼有助于客戶端分析請求回傳結果和問題排查，常用的狀態碼如下：
常見的一個問題：由于客戶端引數的問題，導致介面代碼中執行例外了，最侄訓傳了 500，導致排查問題非常復雜，還需要還原問題場景下的資料和入參，正確的做法應該是對引數做相關校驗最侄訓傳相應的 4XX 的狀態碼，
輸入引數
模型系結
介面的輸入引數就是通過模型系結將 HTTP 請求中的值映射到引數中，模型系結有以下六種：
- [FromRoute]：通過路由的 URL 中取值，可以自動推斷；
- [FromQuery]：獲取 URL 地址中的引數，可以自動推斷；
- [FromBody]：從HTTP Body取值，通常用于取JSON, XML，可以自動推斷；
- [FromHeader]：獲取 Request Header 中的引數資訊，需要指定
- [FromForm]：獲取 Content-Type 為 multipart/form-data 或 application/x-www-form-urlencoded 型別的引數，需要指定
- [FromServices]：獲取依賴注入的引數，依賴注入默認是使用建構式注入，但Controller 可能會因為每個Action用到不一樣的 Service 導致很多引數，所以也可以在 Action 注入Service，需要指定，
下面實作一個使用 [FromServices] 的示例：
1、創建 IUserService 介面和 UserService 類，代碼如下：
public interface IUserService
{
string GetUserName(string userId);
}
public class UserService:IUserService
{
public string GetUserName(string userId)
{
return $"UserName:{userId}";
}
}
2、在 Startup 類的 ConfigureServices 方法中添加下面代碼進行注冊
services.AddScoped<IUserService,UserService>();
3、添加 UserController 類，里面添加名為 GetUserName 的 Action 方法
[HttpGet]
public ActionResult<string> GetUserName(string userId, [FromServices]IUserService userService)
{
return Ok($"{userService.GetUserName(userId)}");
}
4、執行結果如下：
引數驗證
引數驗證是非常重要的，否則本來是 4XX 的問題就會變成 5XX 的問題，引數驗證有這么幾種：
- Data Annotations
- 自定義 Attribute
- 實作 IValitableObject 介面
- 使用第三方的驗證庫，比如 FluentValidation
Data Annotations
1、在 User 的物體類上添加相關特性
public class User
{
[Required(ErrorMessage = "姓名不能為空")]
public string Name { get; set; }
[EmailAddress(ErrorMessage = "郵件格式不正確")]
public string Email { get; set; }
}
2、呼叫結果如下：
有關更多的 Data Annotations 特性的使用，可以參考官方檔案：https://docs.microsoft.com/en-us/dotnet/api/system.componentmodel.dataannotations?view=netcore-3.1
IValitableObject 介面
1、將 User 類繼承 IValitableObject 介面，并實作 Validate 方法，代碼如下：
public class User: IValidatableObject
{
[Required(ErrorMessage = "姓名不能為空")]
public string Name { get; set; }
[EmailAddress(ErrorMessage = "郵件格式不正確")]
public string Email { get; set; }
public IEnumerable<ValidationResult> Validate(ValidationContext validationContext)
{
if (Name == Email)
{
yield return new ValidationResult("名稱不能和郵箱相等",
new []{nameof(Name),nameof(Email)});
}
}
}
2、呼叫結果如下：
自定義 Attribute
自定義 Attribute 功能和IValitableObject 介面類似，但可以作用于類級別也能用于屬性級別，更加靈活，
1、創建 NameNotEqualEmailAttribute 類，用來實作判斷 User 類中的名稱和郵箱不能相等
public class NameNotEqualEmailAttribute : ValidationAttribute
{
protected override ValidationResult IsValid(object value,
ValidationContext validationContext)
{
var user = validationContext.ObjectInstance as User;
if (user.Name == user.Email)
{
return new ValidationResult("名稱不能和郵箱相等",
new []{nameof(User)});
}
return ValidationResult.Success;
}
}
2、在 User 類上添加此特性
[NameNotEqualEmail]
public class User
{
[Required(ErrorMessage = "姓名不能為空")]
public string Name { get; set; }
[EmailAddress(ErrorMessage = "郵件格式不正確")]
public string Email { get; set; }
}
3、呼叫結果如下：
FluentValidation
FluentValidation 就不多做介紹了，可以參見官方檔案：https://fluentvalidation.net/
ModelBinder
ModelBinder 是自定義模型系結器，可以對入參的型別進行一些轉換，比如，引數中傳遞 001,002 這樣的字串，在介面中使用 IEnumerable
1、創建 StringToListModelBinder 類，如下：
public class StringToListModelBinder: IModelBinder
{
public Task BindModelAsync(ModelBindingContext bindingContext)
{
if (!bindingContext.ModelMetadata.IsEnumerableType)
{
bindingContext.Result = ModelBindingResult.Failed();
return Task.CompletedTask;
}
var value = https://www.cnblogs.com/oec2003/p/bindingContext.ValueProvider.GetValue(bindingContext.ModelName).ToString();
if (string.IsNullOrWhiteSpace(value))
{
bindingContext.Result = ModelBindingResult.Success(null);
return Task.CompletedTask;
}
var elementType = bindingContext.ModelType.GetTypeInfo().GenericTypeArguments[0];
var converter = TypeDescriptor.GetConverter(elementType);
var values = value.Split(new[] {','}, StringSplitOptions.RemoveEmptyEntries)
.Select(x => converter.ConvertFromString(x.Trim())).ToArray();
var typedValues = Array.CreateInstance(elementType, values.Length);
values.CopyTo(typedValues,0);
bindingContext.Model = typedValues;
bindingContext.Result = ModelBindingResult.Success(bindingContext.Model);
return Task.CompletedTask;
}
2、在 UserController 類中創建 GetUsersByIds 方法
[HttpGet("ids")]
public ActionResult<List<User>> GetUsersByIds(
[ModelBinder(BinderType = typeof(StringToListModelBinder))]IEnumerable<string> ids)
{
if (ids == null)
{
return BadRequest();
}
return Ok();
}
3、呼叫結果
回傳值
回傳 XML 格式
盡管使用 Web API 通常都是使用 JSON 格式，但有些時候需要回傳 XML 格式，默認情況下，即使請求頭中添加了 Accept=application/xml，介面依然會回傳 JSON 格式的結果，想要回傳 XML 格式，修改 Startup 類的 ConfigureServices 方法即可，
services.AddControllers().AddXmlDataContractSerializerFormatters();
結果如下：
錯誤資訊統一回傳
之前的文章中有講過使用過濾器的方式來做到結果的統一回傳，這里介紹另一種方式，使用 ConfigureApiBehaviorOptions ，可以讓我們自定義錯誤資訊的回傳內容和格式，修改 Startup 類中的 ConfigureServices 方法
services.AddControllers()
.AddXmlDataContractSerializerFormatters()
.ConfigureApiBehaviorOptions(setup =>
{
setup.InvalidModelStateResponseFactory = context =>
{
var details = new ValidationProblemDetails(context.ModelState)
{
Type = "http://api.oec2003.com/help",
Title = "物體驗證錯誤",
Status = StatusCodes.Status422UnprocessableEntity,
Detail = "看詳細",
Instance = context.HttpContext.Request.Path,
};
details.Extensions.Add("trachid",context.HttpContext.TraceIdentifier);
return new UnprocessableEntityObjectResult(details)
{
ContentTypes = { "application/problem+json" }
};
};
});
當出現驗證問題時，結果如下：
更多詳細資訊可以看檔案：https://docs.microsoft.com/zh-cn/aspnet/core/web-api/handle-errors?view=aspnetcore-3.1
資料塑形
在 API 中回傳結果到前端時，一般不會直接將底層的 Entity 回傳，會創建相對應的 Dto，比如，用戶的 Entity 是這樣的
public class User
{
public string Name { get; set; }
public string Email { get; set; }
public string Password { get; set; }
}
創建 User 的 Dto 類 UserDto，如下
public class UserDto
{
public string Name { get; set; }
public string Email { get; set; }
}
在介面的 Action 方法中使用 AutoMapper 做下轉換
[HttpGet("{userId}")]
public ActionResult<UserDto> GetUserById(string userId)
{
User user = new User()
{
Name = "oec2003",
Email = "[email protected]",
Password = "123456"
};
return Ok(base.Mapper.Map<UserDto>(user));
}
請求結果如下
同樣的介面在前端不同的場景下需要回傳不一樣的欄位資料，一種方式是創建很多不同的介面，回傳不同的 Dto 的結果，但這樣做非常繁瑣，可以通過 ExpandoObject 來實作按客戶端的需要進行回傳結果，具體步驟如下：
1、因為獲取用戶串列的介面方法的是 List
public static class IEnumerableExtension
{
public static IEnumerable<ExpandoObject> GetData<T>
(this IEnumerable<T> source, string fields)
{
if (source == null)
{
throw new ArgumentNullException(nameof(source));
}
var objectList = new List<ExpandoObject>(source.Count());
var propertyInfoList = new List<PropertyInfo>();
if (string.IsNullOrWhiteSpace(fields))
{
var propertyInfos = typeof(T).GetProperties(BindingFlags.Public |
BindingFlags.Instance);
propertyInfoList.AddRange(propertyInfos);
}
else
{
var fieldSplit = fields.Split(',');
foreach (var field in fieldSplit)
{
var propertyName = field.Trim();
var propertyInfo = typeof(T).GetProperty(propertyName,
BindingFlags.IgnoreCase | BindingFlags.Public | BindingFlags.Instance);
if (propertyInfo == null)
{
throw new Exception($"屬性名：{propertyName} 沒有找到");
}
propertyInfoList.Add(propertyInfo);
}
}
foreach (T t in source)
{
var obj=new ExpandoObject();
foreach (var propertyInfo in propertyInfoList)
{
var value = https://www.cnblogs.com/oec2003/p/propertyInfo.GetValue(t);
((IDictionary) obj).Add(propertyInfo.Name, value);
}
objectList.Add(obj);
}
return objectList;
}
}
2、創建獲取用戶串列的 Action 方法
[HttpGet]
public ActionResult GetUsers([FromBody]string fields)
{
var userList =new List<User>()
{
new User(){ Name = "oec2003",Email = "[email protected]",Password = "123456"},
new User(){ Name = "oec2004",Email = "[email protected]",Password = "123456"},
new User(){ Name = "oec2004",Email = "[email protected]",Password = "123456"}
};
var returnResult = base.Mapper.Map<List<UserDto>>(userList);
//使用擴展方法按需獲取
return Ok(returnResult.GetData(fields));
}
3、查看呼叫結果
回傳一個屬性 Name
回傳所有
最后
本文只是涉及了在 Web API 中比較常用的一些功能點，限于篇幅，每個點并沒有寫的非常深入，也較少涉及原理，但我們在學習程序中，除了實作效果外還應該深入去了解其中細節和原理，
文中示例代碼：https://github.com/oec2003/DotNetCoreThreeAPIDemo
希望本文對您有所幫助，
轉載請註明出處，本文鏈接：https://www.uj5u.com/net/49201.html
標籤：.NET Core
上一篇：C# 結構體