Web API入参，响应规范

入参绑定

入参应该定义成实体，而不是多个参数，方便扩展。[FromBody]和[FromUrl]特性也最好加上。

public ActionResult<Pet> Create([FromBody] Pet pet)

public class Pet
{
    public string Name { get; set; }

    [FromQuery] // Attribute is ignored.
    public string Breed { get; set; }
}

入参校验

简单的入参校验可通过模型验证特性来简化处理，如[Required]、[Range]等。

public class Movie
{
    public int Id { get; set; }

    [Required]
    [StringLength(100)]
    public string Title { get; set; }

    [Range(0, 999.99)]
    public decimal Price { get; set; }

    [Required]
    public Genre Genre { get; set; }

    public bool Preorder { get; set; }
}

响应

数据格式

一般Json数据格式返回，参考格式如下。

{
        "Code":1000,
        "Message":"处理成功",
        "Data"：{}
}

根据系统之间约定的Code判断处理情况，如参数缺失等，Message作为提示信息，而不是使用http状态码。根据需要也可附带timestamp记录返回的时间。

Controller的返回类型

虽然返回的数据格式是Json，但Controller的返回类型不建议使用JsonResult，IActionResult等，推荐使用ActionResult< T >或直接返回实体T，再通过AOP返回Json，可在Swagger下正常展示实体的字段。

public ActionResult<Product> GetById(int id)
{
    if (!_repository.TryGetProduct(id, out var product))
    {
        return NotFound();
    }
    return product;
}

返回枚举值还是文本

当需要对该值进行展示外的逻辑处理时，就应该返回枚举值，反之，直接返回文本可以简化前端的处理。