跳到主要内容
版本：3.0.0

ApiControllerBase

ApiControllerBase 是 Aegis Web API 的基础控制器。
可以把它理解成：帮你把 Controller 的返回格式统一起来。

它解决什么问题​

有了它之后，Controller 不用再自己拼响应对象。
平时最常用的也就是这几种情况：

  • 返回单对象
  • 返回列表
  • 返回分页列表
  • 返回失败消息
  • 把 ServiceResult<T> 直接转换成标准响应

响应类型怎么理解​

平时先记这三种就够：

  • ApiResponse
  • EntityResponse<T>
  • EntitiesResponse<T>

ApiResponse​

基础响应类型，仅包含公共字段：

  • Code
  • MessageType
  • Message

它本身不带 Result，只是公共父级类型。

EntityResponse<T>​

单对象返回时使用，数据路径是：

Result

EntitiesResponse<T>​

列表或分页列表返回时使用，数据路径是：

Result.List
Result.Total
Result.CurrentIndex

最常用的几个方法​

SuccessResult(entity)​

返回单对象。

[HttpGet("GetUser")]
public async Task<ApiResponse> GetUser(long id)
{
    var dto = await _userService.GetUserAsync(id);
    return SuccessResult(dto);
}

SuccessListResult(list)​

返回列表。

[HttpGet("GetList")]
public async Task<ApiResponse> GetList([FromQuery] PageListRequest request)
{
    var list = await _userService.GetUsersAsync(request);
    return SuccessListResult(list);
}

SuccessListResult(pagedResult)​

返回分页结果，会自动带上总数和页码。

FailedResult(message)​

返回失败结果。

if (dto == null)
{
    return FailedResult("未查询到相关数据");
}

CallResult(serviceResult)​

如果 Service 返回的是 ServiceResult<T>，可以直接交给它转换。

这里要特别记一下​

当前 Aegis 的基础响应类型是 ApiResponse / EntityResponse<T> / EntitiesResponse<T>。
如果你在其他规范材料里看到 ApiResult<T> 之类的写法，请先把它视为参考口径，不要直接覆盖当前代码事实。

实际项目里怎么用最省事​

在业务项目里，最省事的写法通常是：

  • Controller 统一返回 Task<ApiResponse>
  • 单对象使用 SuccessResult
  • 列表使用 SuccessListResult
  • 失败使用 FailedResult
  • 复杂 Service 分支可考虑 CallResult

这样前后端都比较好对齐，Swagger 里也更稳定。