ASP.NET Core 8 Web API中PostgreSQL JSONB字段映射与存储问题

一、依赖包准备 #

确保项目中安装以下NuGet包：

• Npgsql（PostgreSQL的.NET官方驱动）
• Dapper（轻量ORM工具）
• 若偏好Newtonsoft.Json而非默认的System.Text.Json，额外安装Npgsql.Json.NET

二、实体类类型定义 #

针对两个JSONB字段，根据场景选择对应类型：

1. 固定结构的adress_data字段 #

直接使用你已定义的Adress_Data类，Npgsql会自动完成JSONB与实体类的序列化/反序列化。

2. 动态结构的frontends_field字段 #

推荐三种常用类型：

• JsonDocument：强类型、可安全遍历/访问JSON节点，适合需要读取字段内容的场景
• dynamic：最灵活，适合仅存储/转发JSON内容、无需解析的场景
• Dictionary<string, object>：键值对形式，适合需要遍历键值的场景

修改后的实体类代码：

public class User
{
    [Required]
    public long? User_Id { get; set; }
    
    [Required]
    [MaxLength(50)]
    public string UserName { get; set; } = string.Empty;
    
    [Required]
    [MaxLength(200)]
    public string FullName { get; set; } = string.Empty;

    [Required]
    [MaxLength(300)]
    public string Password { get; set; } = string.Empty;

    [MaxLength(300)]
    public string Salt { get; set; } = string.Empty;

    // 动态前端配置字段，以JsonDocument为例
    public JsonDocument? frontends_field { get; set; }
    // 固定结构的地址字段
    public Adress_Data? adress_data { get; set; }
}

public class Adress_Data 
{
    public string? adress_name { get; set; }
    public string? streetinfo { get; set; }
    public string? buildinginfo { get; set; }
    public string? city { get; set; }
}

三、JSON序列化配置（可选） #

若使用System.Text.Json（默认） #

无需额外配置，Npgsql从v6版本开始默认使用System.Text.Json处理JSON类型。

若使用Newtonsoft.Json #

安装Npgsql.Json.NET包后，在项目启动代码（如Program.cs）中添加全局配置：

NpgsqlConnection.GlobalTypeMapper.UseJsonNet();

四、插入逻辑验证 #

你的现有接口代码无需大幅修改，Dapper会自动将实体类属性映射为SQL参数，Npgsql负责将.NET类型序列化为JSONB：

[HttpPost]
public async Task<ActionResult<User>> PostUser([FromBody] User req)
{
    try
    {
        using var MyCnt = _db.GetConnection();
        var MySql = """
            INSERT INTO public.users (username, fullname, password, salt, frontends_field, adress_data)
            VALUES (@username, @fullname, @password, @salt, @frontends_field, @adress_data)
            returning *;
            """;
        var result = await MyCnt.QueryFirstOrDefaultAsync<User>(MySql, req);

        return Ok(result);
    }
    catch (Exception ex)
    {
        return BadRequest(ex.Message);
    }
}

五、关键注意事项 #

• 属性名匹配：确保实体类属性名与SQL参数名一致（PostgreSQL对大小写不敏感，但保持一致可避免歧义）
• 空值处理：为JSON字段添加?标记设为可空，避免空值序列化报错
• 版本兼容性：使用Npgsql 8.x系列版本，与.NET Core 8.0完全兼容

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