Controller

类与构造方法

Controller类需要继承于ApiControllerBase抽象类，该类为Controller下提供一系列返回方法和处理。 对应Controller的构造方法里可以接收所需要业务领域的Service和Logger，具体写法如下

public class IpVisitPrePayController : ApiControllerBase
{
    private readonly IpVisitPrePayService _ipVisitPrePayService;
    private readonly ILogger _logger;

    public IpVisitPrePayController(IpVisitPrePayService ipVisitPrePayService, ILogger<IpVisitPrePayController> logger)
    {
        this._ipVisitPrePayService = ipVisitPrePayService;
        _logger = logger;
    }
    // 控制器代码...
}

API方法

对应API应当标识请求方法类型和具体路由路径，如[HttpPost]和[Route("GetIpVisitPrePay")]，也可以合到一起写作[HttpPost("GetIpVisitPrePay")]。如下面的方法。

目前开放的请求方法类型只有HttpGet和HttpPost

[HttpGet("GetIpVisitPrePay")]
public async Task<ApiResponse> GetIpVisitPrePay(long seq)
{
    var data = await _ipVisitPrePayService.GetIpVisitPrePay(seq);
    if (data != null)
    {
        return SuccessResult(data);
    }
    else
    {
        return FaliedResult("未查询到相关信息");
    }
}

Request 请求

Controller层下的任何对外公开的接口方法的入参都应该遵守如下方案

1. 简单入参，如id等直接使用id即可。
2. 复杂入参，统一建立请求类，请求统一使用record标注为记录类型。同时命名为方法名+Request的名称，例如GetInvoicePageRequest，该类存放在该业务领域对应的Dto项目下的Requests文件夹下
3. 入参应该是完全隔离于数据库的类，没有特殊情况，不允许传入像是IsDeleted，CreateTime，UpdateTime等数据库字段。可以理解为业务用的请求类。

   /// <summary>  
   /// 获取用户列表  
   /// </summary>  
   [HttpPost("GetUsers")]  
   public async Task<ApiResponse> GetUsers(GetUsersRequest request)
   

Request记录构造如下所示，注意事项如下：

1. 统一使用record标注，能减小存储开销，降低GC成本。
2. 尽量使用init而不是set。防止前端参数被篡改。
3. 使用<summary>头标注注释
4. 对入参进行基本验证，使用Validator类即可，具体命名就是Request记录名+Validator，继承AbstractValidator<T>，其中泛型T标注为记录自身。该验证类会在Controller请求中直接验证，如果验证失败会直接返回前端Code=105,MessageType=40的错误消息。（返回结果请参考下面的Response 响应段落）
5. Validator使用FluentValidation方法实现，该类直接写在record记录下即可。具体可参考FluentValidation使用手册。

/// <summary>  
/// 获取用户列表请求
/// </summary>  
public record GetUsersRequest  
{  
    /// <summary>  
    /// 名字  
    /// </summary>  
    public string Name { get; init; }  

    /// <summary>  
    /// 年龄  
    /// </summary>  
    public int Age { get; init; }  

}  
public class GetUserRequestValidator : AbstractValidator<GetUsersRequest>  
{  
    public GetUserRequestValidator()  
    {        RuleFor(x => x.Name)  
            .NotEmpty()  
            .WithMessage("姓名不能为空");  
        RuleFor(x => x.Age)  
            .Must(x => x >= 0 && x < 200)  
            .WithMessage("请输入正常年龄");  
    }

Request Attribute 请求属性

在HttpPost的情况下，不带任何标记的参数默认是从Body传入的，如果需要获取Query上的参数，则需要标记为[FromQuery],如果同时需要Body和Query里的参数，可以写成这样。

 public async Task<ApiResponse> GetUsers(GetUsersRequest request, [FromQuery] UsersFilterRequest filter)

Response 响应

ApiResponse

无论是异步方法还是同步方法，请确保在Controller层下对外公开接口方法统一使用ApiResponse作为返回的响应类。 该响应类包含以下基本字段。

public record ApiResponse  
{  
    /// <summary>  
    /// 响应码  
    /// </summary>  
    public int Code { get; set; }  

    /// <summary>  
    /// 消息类型  
    /// </summary>  
    public MessageType MessageType { get; set; }  

    /// <summary>  
    /// 响应消息  
    /// </summary>  
    public string Message { get; set; }  

    /// <summary>
    /// 结果
    /// </summary>
    public T Result { get; set; }

}

响应码

Code可以传入任意数字，但以下数字已被框架枚举占用。

消息类型

MessageType目前只支持以下四种消息类型

响应方法

在返回结果时，ApiControllerBase类为当前控制器提供了一系列的简单响应方法。

[HttpPost("GetUsers")]  
public async Task<ApiResponse> GetUsers(GetUsersRequest request)  
{  
    var users = _userService.GetUsers();  

    return SuccessResult(users);  
}