fix(PostgreSQL): 使用 jsonb 可索引操作符查询键

[zhou-hao]

目的

• 将 PostgreSQL JSONB key exists 查询从 jsonb_exists* 函数改为 ? / ?| / ?& 操作符。
• 避免 jsonb_exists_any 等函数形式无法命中 jsonb_ops GIN 索引的问题。
• 保持 SQL builder 输出 PostgreSQL 原生操作符，JDBC 执行链路单独处理 ? 操作符与预编译占位符冲突。

核心变动

• PostgresqlJsonbExistTermFragmentBuilder
  • exist：生成 column ? ?。
  • all：生成 column ?& array[...]。
  • any / keys / 通用 in、overlap：生成 column ?| array[...]。
• JdbcSqlExecutor / PostgresqlDriverUtils
  • 在 JDBC prepareStatement 前判断连接是否为 PostgreSQL。
  • 仅 PostgreSQL JDBC 执行链路将 JSONB ? / ?| / ?& 操作符转义为 JDBC 可识别的 ?? / ??| / ??&。
  • 日志和 SqlRequest 保持原生 PostgreSQL SQL 形态，不污染 R2DBC。
• SqlUtils
  • 保留 R2DBC / native SQL 参数替换时跳过 PostgreSQL 原生 JSONB 操作符的能力。
  • 新增 JDBC 专用 PostgreSQL ? 操作符转义方法，处理字符串、双引号标识符、行注释和块注释。
• 测试
  • 更新 JSONB exists builder 断言为原生 ? / ?| / ?&。
  • 增加 JDBC 专用转义方法的单元测试。
  • 复用现有 PostgreSQL JDBC/R2DBC 集成测试验证真实 SQL 可执行。

设计与测试目标

• 设计稿：不适用，本次为已合并 JSONB 查询能力的索引命中修复。
• 用户确认：用户要求确认 R2DBC 能否直接使用 ?|，并倾向 JDBC 单独处理而不是让 R2DBC 兼容 ??。
• 测试目标：覆盖 JSONB ?、?|、?& 操作符生成、JDBC 执行前转义、R2DBC $n 占位符替换和 native SQL 日志还原。
• 数据库兼容与性能：仅 PostgreSQL JSONB 方言；操作符形式可被 PostgreSQL jsonb_ops GIN 索引用于 key exists 查询。未做压力测试，本 PR 以 SQL 形态和真实 PostgreSQL 集成执行作为替代验证。
• 注释 / 公共契约：不新增公共 SPI。
• 链路追踪：不涉及业务链路。
• MBean 运维可观测性：不涉及常驻任务、缓存、队列或后台执行器。

测试结果

• 命令：mvn -pl hsweb-easy-orm-rdb -Dtest=PostgresqlJsonbExistBuilderCoverageTest,SqlUtilsCoverageTest,SqlUtilsTest,SqlUtilsBranchTest test
  • 结果：74 passed, 0 failed, 0 skipped。
• 命令：mvn -pl hsweb-easy-orm-rdb -Dtest=PostgresqlBasicTest#testJsonbExistTerm test
  • 结果：1 passed, 0 failed, 0 skipped。
  • Testcontainers：postgres:11-alpine。
  • JDBC 日志 SQL 保持原生 data ? ?、data ?| array[ ?,? ]、data ?& array[ ?,? ]；执行前由 JDBC 链路转义。
• 命令：mvn -pl hsweb-easy-orm-rdb -Dtest=PostgresqlReactiveTests#testJsonbExistTerm test
  • 结果：1 passed, 0 failed, 0 skipped。
  • Testcontainers：postgres:11-alpine。
  • R2DBC SQL 直接使用 data ? $1、data ?| array[ $1,$2 ]、data ?& array[ $1,$2 ]。
• 临时真实库 smoke 验证：
  • JDBC PreparedStatement 直接 data ?| array[?,?] 会报“未设定参数值 3”，确认 JDBC 需要转义。
  • R2DBC 直接 data ?| array[$1,$2] 和 data ? $1 通过，确认不需要 ??。
• 格式检查：git diff --check 通过。

文档同步情况

• 未同步长期文档：本次为 PostgreSQL JSONB 查询 SQL 形态和执行链路修复，测试证据放在 PR 描述，不新增任务流水文档。

风险与说明

• 影响范围：PostgreSQL JSONB exists 查询、JDBC prepareStatement 前 SQL 转义、SqlUtils 参数替换逻辑。
• 方言限制：? / ?| / ?& 为 PostgreSQL JSONB 操作符，不影响其他数据库方言的 JSON 实现。
• JDBC 说明：仅 PostgreSQL 连接执行前转义 JSONB ? 操作符，避免 PostgreSQL JDBC 将其误判为预编译占位符。
• R2DBC 说明：R2DBC 直接使用 PostgreSQL 原生 ? / ?| / ?& 操作符，不再依赖 ?? 兼容路径。

[codecov-commenter]

⚠️ Please install the to ensure uploads and comments are reliably processed by Codecov.

Codecov Report

❌ Patch coverage is 68.67470% with 26 lines in your changes missing coverage. Please review.
✅ Project coverage is 79.14%. Comparing base (68b2764) to head (381739c).
⚠️ Report is 47 commits behind head on 4.2.

Files with missing lines	Patch %	Lines
...a/org/hswebframework/ezorm/rdb/utils/SqlUtils.java	67.69%	13 Missing and 8 partials ⚠️
...m/rdb/supports/postgres/PostgresqlDriverUtils.java	44.44%	2 Missing and 3 partials ⚠️

Additional details and impacted files

@@              Coverage Diff              @@
##                4.2     #114       +/-   ##
=============================================
+ Coverage     64.92%   79.14%   +14.21%     
- Complexity     2341     3391     +1050     
=============================================
  Files           343      374       +31     
  Lines          9375    10905     +1530     
  Branches        940     1309      +369     
=============================================
+ Hits           6087     8631     +2544     
+ Misses         2810     1637     -1173     
- Partials        478      637      +159     

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.