分层架构中API模型位置与应用层处理器返回类型选型咨询

一、API输入/输出模型的放置位置 #

1. API输入模型（如示例中的GetModel） #

• 放置在API层。输入模型是API对外暴露的契约一部分，和HTTP请求参数、验证规则强绑定，属于API层的职责范围。放在API层可以避免业务层（应用/领域）被API的特定格式污染，同时符合分层依赖规则（API层依赖应用层，而非反向）。

2. API输出模型（如示例中的CustomApiResponse） #

• 放置在API层。输出模型是对外响应的格式定义，包含API特有的结构（比如状态码、自定义消息、分页包装等），属于API层的对外契约。如果需要通用的数据传输对象（DTO）用于业务层内部传递，可以在应用层定义业务视角的DTO（如CarSummaryDto），但API的最终输出模型必须由API层自行定义，避免应用层与API契约耦合。

二、应用层处理器的返回类型选型 #

推荐采用方案二的思路（返回领域对象），或进一步优化为返回应用层业务DTO，具体分析如下：

方案一（返回应用层CarDto）的问题 #

• 耦合API契约：应用层的CarDto如果直接作为API响应，会让应用层与API的输出格式强绑定。当API需要调整响应字段（比如新增/删除字段）时，必须修改应用层的CarDto，违反了分层隔离的原则——应用层应专注于业务用例逻辑，而非对外的API格式。
• 限制灵活性：不同API可能需要不同的输出格式，应用层统一返回的CarDto无法满足多API场景的差异化需求。

方案二（返回领域对象Car）的优势 #

• 职责清晰：应用层专注于业务逻辑执行，返回核心领域对象，保证领域层的纯净性；API层负责将领域对象转换为对外的响应模型，符合“关注点分离”原则。
• 低耦合：API的响应格式变化不会影响应用层和领域层，只需在API层调整映射规则即可。
• 避免数据泄漏：领域对象可能包含敏感业务数据或内部行为，API层可以在映射时过滤敏感字段，保证对外数据的安全性。

优化建议 #

如果担心领域对象的内部细节暴露给API层，或需要在应用层统一处理数据转换，可以在应用层定义业务视角的DTO（如CarBusinessDto），处理器返回该DTO，再由API层映射为CustomApiResponse。这种方式既隔离了领域对象，又避免了应用层与API契约的耦合：

// 应用层定义业务DTO
public class CarBusinessDto
{
    public string Id { get; set; }
    public string Brand { get; set; }
    public int Year { get; set; }
    // 仅包含业务用例所需的字段
}

// 应用层处理器返回业务DTO
public class GetCarsQueryHandler : IRequestHandler<GetCarsQuery, CarBusinessDto>
{
    private readonly ICarRepository _carRepository;
    private readonly IMapper _mapper;

    public GetCarsQueryHandler(ICarRepository carRepository, IMapper mapper)
    {
        _carRepository = carRepository;
        _mapper = mapper;
    }

    public async Task<CarBusinessDto> Handle(GetCarsQuery request, CancellationToken cancellationToken)
    {
        var car = await _carRepository.GetByIdAsync(request.Id);
        return _mapper.Map<CarBusinessDto>(car);
    }
}

// API层映射为对外响应
[HttpGet]
public async Task<IActionResult> Get(GetModel model)
{
    var queryModel = _mapper.Map<GetCarsQuery>(model);
    var carBusinessDto = await _mediator.Send(queryModel);
    var response = _mapper.Map<CustomApiResponse>(carBusinessDto);
    return Ok(response);
}

总结 #

• API输入/输出模型均放在API层，保证业务层与API契约解耦；
• 应用层处理器优先返回领域对象或应用层业务DTO，避免直接返回API特定的响应模型，维护分层架构的清晰性与灵活性。

内容的提问来源于stack exchange，提问作者user1765862