Dapper一对多查询报错：splitOn列'PortalId'未找到

Multi-map error: splitOn column 'PortalId' was not found

我在应用中使用Dapper执行各类查询，处理一对多关联的两张表查询时遇到上述错误，以下是我的查询实现代码及响应类定义，原本认为配置正确但仍出现问题，寻求帮助。

查询代码 #

public async Task<Result<PortalResponse?, Error>> Handle(GetEmailAddressesQuery request, CancellationToken cancellationToken)
{
    var parameters = new DynamicParameters();
    parameters.Add("@p_tenantid", request.TenantId);

    const string sql = """
        SELECT em.PortalId, em.Email
        FROM dbo.Portal p 
        JOIN dbo.PortalEmailAddress em ON p.Id = em.PortalId
        WHERE p.TenantId = @p_tenantid
    """;

    using var connection = _dapperContext.CreateConnection();

    var response = await connection.QueryAsync<PortalResponse, EmailAddressResponse, PortalResponse>
        (new CommandDefinition(sql, parameters, cancellationToken: cancellationToken),
          (portal, emailAddress) =>
          {
              portal.EmailAddresses.Add(emailAddress);
              return portal;
          }, splitOn: "PortalId");

    if (response is null)
    {
        return PortalErrors.PortalNotFound(request.TenantId);
    }

    return response.FirstOrDefault();
}

响应类定义 #

public sealed class PortalResponse : IResponse
{
    public int Id { get; init; }
    public string Name { get; init; } = string.Empty;
    public List<EmailAddressResponse> EmailAddresses { get; set; } = [];
    public List<PhoneNumberResponse> PhoneNumbers { get; set; } = [];
    public AddressResponse? Address { get; set; }
    public string? WelcomeMessage { get; init; }
    public string? Logo { get; init; };
}

public sealed class EmailAddressResponse
{
    public int PortalId { get; init; }
    public string Email { get; init; } = string.Empty;
}

问题原因及解决方案 #

核心问题 #

1. SQL查询字段缺失：你的SQL只返回了em.PortalId和em.Email，但PortalResponse需要的Id、Name等字段完全没查询。Dapper多映射时需要先完整映射第一个实体（PortalResponse），再切换到第二个实体（EmailAddressResponse），缺失第一个实体的字段会导致映射逻辑混乱，进而触发splitOn字段找不到的错误。
2. splitOn逻辑误解：splitOn的作用是告诉Dapper「从哪个字段开始，切换到下一个实体的映射」。你把PortalId作为splitOn字段，但它是第二个实体的字段，且前面没有第一个实体的字段，Dapper无法识别切换点。

修复步骤 #

1. 修正SQL查询语句

必须先查询Portal表的字段（至少包含PortalResponse的Id，用于后续合并重复记录），再查询PortalEmailAddress的字段，保证字段顺序是「主实体字段在前，关联实体字段在后」。

修改后的SQL：

SELECT 
    p.Id, p.Name, -- 根据需求添加PortalResponse需要的其他字段（如WelcomeMessage、Logo等）
    em.PortalId, em.Email
FROM dbo.Portal p 
JOIN dbo.PortalEmailAddress em ON p.Id = em.PortalId
WHERE p.TenantId = @p_tenantid

2. 调整查询结果处理逻辑

Dapper多映射会为每个关联的Email返回一条Portal记录，需要手动合并相同Portal的Email列表：

var results = await connection.QueryAsync<PortalResponse, EmailAddressResponse, PortalResponse>
    (new CommandDefinition(sql, parameters, cancellationToken: cancellationToken),
      (portal, emailAddress) =>
      {
          portal.EmailAddresses.Add(emailAddress);
          return portal;
      }, splitOn: "PortalId");

// 合并同一Portal的EmailAddresses
var response = results.GroupBy(p => p.Id)
                      .Select(g => 
                      {
                          var mergedPortal = g.First();
                          mergedPortal.EmailAddresses = g.SelectMany(item => item.EmailAddresses).ToList();
                          return mergedPortal;
                      })
                      .FirstOrDefault();

if (response is null)
{
    return PortalErrors.PortalNotFound(request.TenantId);
}

return response;

3. 验证字段匹配

确保SQL返回的字段名和实体类属性名一致（如果不一致可以用SQL别名，比如p.Id AS PortalId，但这里PortalResponse的属性是Id，所以直接用p.Id即可）。

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