使用Dapper查询带IEnumerable子对象的国家数据时遇splitOn参数异常

这个报错的核心原因很明确：Dapper的多映射API需要明确知道如何拆分结果集中的不同实体数据——默认它只会寻找名为Id的字段作为拆分点，但如果你的关联实体（比如这里的Province）的主键不是Id，就必须手动指定splitOn参数。

先复盘一下问题场景 #

假设你的实体类大概是这样的：

public class Country
{
    public int CountryId { get; set; }
    public string CountryName { get; set; }
    public List<Province> Provinces { get; set; }
}

public class Province
{
    public int ProvinceId { get; set; } // 这里主键不是默认的Id
    public string ProvinceName { get; set; }
    public int CountryId { get; set; }
}

你写的SQL左外连接逻辑没问题，但在调用Dapper的Query方法时，没有指定拆分字段，导致Dapper找不到从哪一行开始切换到Province实体的映射：

// 错误写法：缺少splitOn参数
var countries = connection.Query<Country, Province, Country>(
    @"SELECT c.CountryId, c.CountryName, p.ProvinceId, p.ProvinceName, p.CountryId
      FROM Countries c
      LEFT JOIN Provinces p ON c.CountryId = p.CountryId",
    (country, province) =>
    {
        if (province != null)
        {
            country.Provinces ??= new List<Province>();
            country.Provinces.Add(province);
        }
        return country;
    }
).Distinct().ToList();

正确的解决办法 #

只需要在Query方法中添加splitOn参数，指定第二个实体（Province）的主键字段名即可：

// 正确写法：显式指定splitOn为Province的主键字段
var countries = connection.Query<Country, Province, Country>(
    @"SELECT c.CountryId, c.CountryName, p.ProvinceId, p.ProvinceName, p.CountryId
      FROM Countries c
      LEFT JOIN Provinces p ON c.CountryId = p.CountryId",
    (country, province) =>
    {
        if (province != null)
        {
            country.Provinces ??= new List<Province>();
            country.Provinces.Add(province);
        }
        return country;
    },
    splitOn: "ProvinceId" // 关键：告诉Dapper从这个字段开始映射Province实体
).Distinct().ToList();

额外说明 #

1. 拆分规则：splitOn参数指定的是结果集中第二个实体的第一个主键列的名称，Dapper会自动从这个字段开始，把后续的列映射到第二个实体的属性上。
2. 多实体场景：如果需要映射更多层级的实体（比如Country→Province→City），可以用逗号分隔多个拆分字段，比如splitOn: "ProvinceId,CityId"。
3. 列顺序注意：SQL查询结果中，第一个实体的列必须放在最前面，第二个实体的列紧跟其后，不能打乱顺序，否则映射会出错。

你参考的示例之所以不需要指定splitOn，大概率是因为示例中的实体主键都是Id，正好匹配Dapper的默认规则，而你的实体用了自定义的主键名（比如CountryId、ProvinceId），所以必须显式配置。

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