PostgreSQL JSONB字段在C#中需用Npgsql.Json.NET或Npgsql.SourceGenerators处理，不可直接用string读写；须配置类型处理器，避免参数类型错误；查询推荐jsonb_path_query下推执行，更新用jsonb_set，性能优化依赖GIN索引与合理建索引策略。
PostgreSQL JSONB字段在C#中必须用Npgsql.Json.NET或Npgsql.SourceGenerators
直接用 string 读写 jsonb 字段会丢失类型信息，且无法做路径查询；Npgsql 默认不自动序列化/反序列化 JSONB，必须显式配置。推荐用 Npgsql.Json.NET（兼容 Newtonsoft.Json）或 Npgsql.SourceGenerators（.NET 6+ + System.Text.Json），前者生态成熟，后者性能更好但需注意源生成器版本匹配。
常见错误现象：Npgsql.PostgresException: 42704: could not determine data type of parameter $1——这是把 JObject 或 JsonElement 直接当参数传给 DbParameter 导致的，Npgsql 不识别这些类型，必须注册转换器或使用专用扩展方法。
- 若用 Newtonsoft.Json：安装
Npgsql.Json.NET包，调用JsonConvert.SerializeObject()后再传入string是错的——应注册JsonNetTypeHandler，让 Npgsql 自动处理 - 若用 System.Text.Json：确保 Npgsql ≥ 7.0，并启用
UseSystemTextJson()（在NpgsqlDataSourceBuilder中设置） - 实体类中对应字段必须声明为
JObject、JArray、JsonDocument或自定义 POCO（需有无参构造函数+可写属性）
用 jsonb_path_query 在 C# 中查嵌套数组里的对象
想从 jsonb 字段里提取满足条件的子对象（比如“所有 status 为 active 的 items”），不能靠 C# 端过滤——数据量大时效率极低，应下推到数据库执行。PostgreSQL 提供 jsonb_path_query 函数，配合 Npgsql 的参数化查询即可安全使用。
示例场景：表 orders 有 data jsonb 字段，结构如 {"items": [{"id": 1, "status": "active"}, {"id": 2, "status": "draft"}]}，要查出所有 active item：
SELECT jsonb_path_query(data, '$.items[*] ? (@.status == "active")') AS item FROM orders;
在 C# 中写法：
using var cmd = conn.CreateCommand();
cmd.CommandText = @"SELECT jsonb_path_query(data, $1) FROM orders WHERE id = $2";
cmd.Parameters.AddWithValue("$1", "$.items[*] ? (@.status == \"active\")");
cmd.Parameters.AddWithValue("$2", orderId);
-
jsonb_path_query返回JsonDocument（启用 System.Text.Json 后）或JToken（Newtonsoft），不是 string，别用GetString()强转 - 路径表达式中的双引号必须转义，或改用 @-string：
@$"$.items[*] ? (@.status == ""active"")" - 避免拼接用户输入进路径表达式，否则有注入风险；所有动态值应走参数占位符（如用
jsonb_path_query(data, '$.items[*] ? (@.status == $var)', jsonb_build_object('var', @status))）
更新 jsonb 字段的局部值要用 jsonb_set，别用字符串拼接
想只改 JSONB 里的某个字段（例如把 user.settings.theme 从 "light" 改成 "dark"），直接 UPDATE ... SET data = '...' 拼接 JSON 字符串是危险的：易出格式错误、丢字段、SQL 注入、不支持 null 值语义。
正确做法是用 PostgreSQL 内置函数 jsonb_set：
UPDATE users SET settings = jsonb_set(settings, '{theme}', '"dark"', true) WHERE id = 123;
其中第四个参数 true 表示“路径不存在则创建”，false 则静默失败。
- C# 中调用时，路径用
string[]表示（如new[] { "theme" }），值用JsonDocument或JToken，不要转成 string - 如果要删键，用
jsonb_set(settings, '{theme}', 'null'::jsonb)，注意'null'::jsonb是 JSONB 类型的 null，不是 SQL NULL - 多层嵌套路径（如
{user, preferences, language}）必须确保父路径存在，否则jsonb_set不会自动创建中间对象，需链式调用或用COALESCE配合默认空对象
JSONB 查询性能差？加 GIN 索引但别乱建
没索引时 jsonb @> '{"status":"active"}' 是全表扫描，10 万行可能要秒级；加 GIN 索引后可降到毫秒级。但 GIN 索引不是万能的——它只加速存在性查询（@>、?、?|、?&），对 jsonb_path_query 或 ->> 提取后过滤无效。
建索引的关键点：
- 最常用的是
jsonb_path_ops：体积小、速度快，但只支持@>和?，适合“包含某结构”的场景 - 若要用
->>提取字段后做等值或范围查询，得建表达式索引，如CREATE INDEX idx_orders_status ON orders ((data->>'status')); - 别给整个
jsonb字段建默认 GIN（jsonb_ops），它会索引所有键和值，索引体积爆炸，写入变慢 - 复合索引慎用：GIN 不支持多列混合索引（比如
(status, data)），只能选一个 jsonb 字段做 GIN，其他条件靠顺序扫描补
真正难的不是怎么写代码，而是判断哪条路径值得索引、要不要冗余存一个扁平字段、以及什么时候该把 JSONB 拆回关系表——这些没法靠工具自动决定。
