基于 Controller 的 Web API
ASP.NET Wep API 的请求架构
客户端发送Http请求,Contoller响应请求,并从数据库读取数据,序列化数据,然后通过 Http Response返回序列化的数据。
ControllerBase 类
Web API 的所有controllers 一般继承于 ControllerBase 类,而不是Controller 类。
因为 Controller 类也继承自ControllerBase 类,但是支持views,而API一般不需要这个功能。
ControllerBase 提供了很多处理Http Request 和 Response方法,比如返回201结果的CreatedAtAction(表示成功创建资源):
[HttpPost]
[ProducesResponseType(StatusCodes.Status201Created)]
[ProducesResponseType(StatusCodes.Status400BadRequest)]
public ActionResult<Pet> Create(Pet pet)
{pet.Id = _petsInMemoryStore.Any() ? _petsInMemoryStore.Max(p => p.Id) + 1 : 1;_petsInMemoryStore.Add(pet);return CreatedAtAction(nameof(GetById), new { id = pet.Id }, pet);
}
其他一些主要方法:
- Ok(),返回空的 http code 200
- File(),返回文件和 http code 200,或者返回部分文件和 http code 206,或者不支持的Range和http code 416
- PhysicalFile(),返回文件和 http code 200,或者返回部分文件和 http code 206,或者不支持的Range和http code 416
- CreatedAtAction(),返回 http code 201
- AcceptedAtAction(),返回 http code 202
- NoContent(),返回 http code 204
- Content(),返回具体结果,plain-text 格式
- RedirectToActionPermanent(),返回 http code 301
- RedirectToPagePermanent(),返回 http code 301
- RedirectToPage(),返回 http code 302
- RedirectToRoute(),返回 http code 302
- RedirectToAction(),返回 http code 302
- RedirectToActionPreserveMethod(),返回 http code 307
- RedirectToPagePreserveMethod(),返回 http code 307
- RedirectToActionPermanentPreserveMethod(),返回 http code 308
- RedirectToPagePermanentPreserveMethod(),返回 http code 308
- BadRequest(),返回 http code 400
- Problem(),返回 http code 400
- ValidationProblem(),返回 http code 400
- Unauthorized(),返回 http code 401
- Challenge(),返回 http code 401 或 403
- Forbid() ,返回 http code 403
- NotFound(),返回 http code 404
- Conflict() ,返回 http code 409
- UnprocessableEntity(),返回 http code 422
- SignIn()
- SignOut()
- StatusCode(Int32)
重要的属性
- ControllerContext
- HttpContext,获取当前action的HttpContext
- Url,IUrlHelper对象
- Request,获取当前action的HttpRequest
- Response,获取当前action的HttpResponse
- RouteData,获取当前action的RouteData
- User,获取当前action关联的User的ClaimsPrincipal
重要的Attributes
标识 Action的功能,包括:
- [ApiController],表示这个Action为HTTP API responses服务。包括:
- 必须要指定 [Route(“[controller]”)]
- 自动验证model
- 自动bind,包括[FromBody]等
- 推断 multipart/form-data 的类型
- [Area],指定Route
- [Bind],
- Route,指定Route
- [Consumes],指定action 接收的数据类型,比如 [Consumes(“application/xml”)], [Consumes(“application/json”)],[Consumes(“application/x-www-form-urlencoded”)]
- [Produces],指定action 返回的数据类型
- [HttpGet],
- [HttpDelete],
- [HttpPost],
- [HttpPut],
- [HttpPatch],
- [HttpOptions],
- [HttpHead],
- [NonAction],表示不是Action方法
- [NonController],表示不是NonController方法
- [FromBody],标识参数或属性可以绑定Body,比如:
- public IActionResult Action3([FromBody] Product product, [FromBody] Order order)
- [FromHeader],
- [FromForm],
格式化Action 的返回结果
Action 不一定要返回某个特定类型,ASP.NET Core 支持任何对象类型。
Actions 可以忽略 HttpRequest的Header的Accept,返回自己想要的类型。
如果返回结果类型不是IActionResult,那么会被序列化。
ControllerBase.Ok 默认返回Json类型。
Http Reponse 的 content-type: application/json; charset=utf-8.
[HttpGet]
public IActionResult Get()=> Ok(todoItemStore.GetList());
而下面这个,Content-Type是text/plain。
[HttpGet("Version")]
public ContentResult GetVersion()=> Content("v1.0.0");
协商结果类型
当HttpRequest 指定了Header的Accept,而 Action返回的类型是JSON时,会发生结果协商。
ASP.NET Core 默认支持的结果类型:
- application/json
- text/json
- text/plain
- 当Header的Accept中指定了一个类型是Action支持的类型时,则返回这个类型。
- 如果Action不支持指定的类型,且设置了MvcOptions.ReturnHttpNotAcceptable为true,则返回406。
- 用Action中第一个formatter 返回结果。
- 当Header的Accept中没有指定类型时,用Action中第一个formatter 返回结果。
- 当Header的Accept中包含"/"时,会被忽略,由Action决定。
- 当请求来自于浏览器时,Accept 会被忽略,由Action决定,默认返回JSON。
- 当请求来自于浏览器时,Accept 会被忽略,如果Host设置了RespectBrowserAcceptHeader为true,则使用浏览器的header。
如果 Action返回的结果是复杂类型时,.NET 会创建一个 ObjectResult,封装结果,然后序列化成协商的结果类型。比如:
[HttpGet("{id:long}")]
public TodoItem? GetById(long id)=> _todoItemStore.GetById(id);
设置成XML结果类型
var builder = WebApplication.CreateBuilder(args);builder.Services.AddControllers().AddXmlSerializerFormatters();
设置成使用json.net的结果类型
默认的JSON格式是基于System.Text.Json的。
var builder = WebApplication.CreateBuilder(args);builder.Services.AddControllers().AddNewtonsoftJson();