# 同功能多实现对齐记录：2026-09-23

适用 `3.0.0-SNAPSHOT`。本轮围绕同一输入、持久化结果和调用方可见响应进行修复，并执行完整 Core reactor 回归。它不是所有数据库、网络环境和业务应用的生产验收。

## 本轮修复

| 范围 | 原差异 | 现在的共同结果 |
| --- | --- | --- |
| 逻辑删除/恢复 | Flex 未限制原删除状态，重复删除重写审计 | 四栈只执行有效状态转换；重复删除保留首次审计，恢复清空删除主体和时间 |
| Flex 事务 | 帐号、状态、删除、审计通过实体类获取全局 Mapper | 使用当前 Mapper 实例，跟随当前 SqlSession 提交或回滚 |
| 空批次 | 同步 ORM 对 null/空集合各自处理，R2DBC 已有空结果约定 | Core 批量创建、按 ID 物理删除、逻辑删除/恢复、状态和审计直接结束，不向持久化层委派 |
| R2DBC ID 可见性 | TENANT_ONLY 可能读出非法全局行；TENANT_SELF 仅排除 NULL | SQL 租户条件之后再拒绝空白键及不允许的全局行；单条、批量、Publisher 和 exists 使用一致结果 |
| Web 框架异常 | WebFlux 丢失框架异常携带的响应头 | 保留 405 Allow、415 支持媒体类型等协议头 |
| Web 数据库异常 | 数据库动作包装异常一律按完整性约束；WebFlux 未识别嵌套 SQLException | 两栈检查真实原因；约束失败 422，其他 SQL 错误 500 且隐藏 SQL 细节 |
| HTTP 请求 | OkHttp 隐式 JSON、WebClient 隐式文本类型，压缩协商与编码处理不同 | UTF-8 正文、显式 Content-Type、缺省 Accept-Encoding identity，保留最终 URI 编码 |
| HTTP 超时 | 异常类型不同；OkHttp 正亚毫秒值变成 0（无限） | 完整响应期限统一为 HttpTimeoutException；OkHttp 正亚毫秒期限至少 1 ms |

R2DBC 的 `existsById` 现在通过可见实体读取后判断是否存在，以便复用实体级存量数据过滤；会比原来的纯 EXISTS 查询多读取实体字段。数据量较大或实体含大字段时应关注这一成本。

## 验证证据

工具链：JDK 25，Maven 3.9.15，编译目标 Java 17。在 Core 仓库根目录执行：

```bash
mvn test
python3 scripts/check-docs.py --workspace
```

完整 reactor：39 个 Maven 项目，29 个测试模块，274 份本次生成的 Surefire XML，**1,475 项测试，失败 0、错误 0、跳过 0**。相较本轮起始状态新增 57 项测试。统计只包含本次命令启动后生成的报告，未累加旧 target 报告。

| 新增/扩展测试 | 数量 | 实际验证方式 |
| --- | --- | --- |
| 三 HTTP 执行器共同场景 | 27 | 回环 HTTP Server：UTF-8、显式/缺省头、编码 URI、重复响应头、重定向、409、204、GET/DELETE/HEAD、字节上限、慢速完整正文超时、亚毫秒期限、失败后复用 |
| WebClient 订阅和取消 | 1 | Mock ExchangeFunction，验证创建 Publisher 无交换、订阅启动、取消传播；不冒充真实网络断开测试 |
| 四数据栈删除生命周期 | 4 | 实际 H2 SQL、Spring Data JPA 代理、MyBatis-Flex SqlSession、R2DBC TransactionalOperator；审计幂等、空批次、恢复和回滚 |
| Flex 帐号/状态/审计事务 | 1 | 实际 H2，提交及回滚，验证原会话写入和其他行不受影响 |
| 四数据栈空批次边界 | 4 | Mockito 调用记录，确认创建和按 ID 删除不委派 ORM；不冒充数据库写入验证 |
| R2DBC 异常租户行读取 | 2 | 实际 H2 与 Spring 仓储代理：NULL、空串、空格、Tab、非法全局行及合法租户主体 |
| 双 Web 请求分派 | 18 | MockMvc / WebTestClient 真实框架分派器：400、403、405、415、422、500、嵌套数据库动作原因、响应头及错误体；不是启动整个应用的网络 E2E |

HTTP 修复前先执行同一组契约测试，复现默认头、超时类型和无限等待差异；修复后共同场景通过。HTTP 公共测试以 test-jar 供三个适配器继承，避免各自维护不同断言。测试产物绑定在 test-compile，使 reactor 的 `mvn test` 可以直接复用。

持久化保留前轮已加入的排序隔离、树路径替换、Flex 显式 null 更新和过期版本拒绝等测试，本轮完整回归再次执行。Web 另对照了 26 组包含 Mapping 声明的成对源码，未发现声明差异；既有路由、批量和搜索反射契约测试同时通过。源码声明相同不等于所有控制器均完成 E2E。

关键可执行入口：

- [公共 HTTP 网络契约](../../ineed-core-httpclient/src/test/java/com/ineed/core/httpclient/AbstractHttpExecutorContractTest.java)。
- [JDBC 生命周期](../../ineed-core-modules/ineed-core-data-jdbc/src/test/java/com/ineed/core/data/jdbc/repository/PersistenceLifecycleParityIntegrationTest.java)、[JPA 生命周期](../../ineed-core-modules/ineed-core-data-jpa/src/test/java/com/ineed/core/data/jpa/repository/PersistenceLifecycleParityIntegrationTest.java)、[Flex 生命周期及当前会话](../../ineed-core-modules/ineed-core-data-mybatis-flex/src/test/java/com/ineed/core/data/mybatisflex/mapper/PersistenceLifecycleParityIntegrationTest.java)、[R2DBC 生命周期](../../ineed-core-reactive-modules/ineed-core-data-r2dbc/src/test/java/com/ineed/core/data/r2dbc/repository/PersistenceLifecycleParityIntegrationTest.java)。
- [R2DBC 实际仓储租户读取](../../ineed-core-reactive-modules/ineed-core-data-r2dbc/src/test/java/com/ineed/core/data/r2dbc/repository/FindByIdRepositoryTenantScopeTest.java)。
- [MVC 分派](../../ineed-core-modules/ineed-core-webmvc/src/test/java/com/ineed/core/webmvc/configuration/WebDispatchParityTest.java)、[WebFlux 分派](../../ineed-core-reactive-modules/ineed-core-webflux/src/test/java/com/ineed/core/webflux/configuration/WebDispatchParityTest.java)。

## 提交快照复核

提交前从 Git 暂存树导出到空目录重新构建，39 个 Maven 项目通过，274 份报告、**1,474 项测试，失败/错误/跳过均为 0**。与上述工作区结果相差的一项是此前另有修改的 `QueryParametersTest.withoutPagingPreservesScopeAndDoesNotChangeCaller`，本次提交未包含该文件。这样可以独立验证本次提交，而不依赖其他在途修改。该验证后仅补充本段记录。

## 兼容变化与保留边界

- HTTP 调用方若依赖默认 JSON/text 类型或自动 gzip，需改为显式请求头；最终 URL 应由调用方正确编码。详细合同见[客户端指南](../guides/clients-and-metadata.md)。
- 不把阻塞方法与 Publisher 的执行时机强行做成一样；业务层不能在响应式链中 block/subscribe。测试桥接里的 block 仅用于收集结果。
- 不能把原生 ORM save、低层 updateEntity 和标准 Manager 更新流程混为一谈：JPA/JDBC/R2DBC 新实体判定与 Flex 显式 UPDATE 仍有差异。全新实体直接传入 updateEntity 的拒绝/插入行为未纳入统一保证；业务更新应经过现有实体读取与权限检查。
- 租户读写权限、查询默认值、分页、状态能力、缓存和事件执行既有测试；这次没有新建所有能力与所有数据库的笛卡尔积矩阵。帐号/状态的位运算 SQL 涉及方言，不能由本轮 H2 生命周期测试推导 MySQL/PostgreSQL 全方言通过，也未新增复合位掩码支持。
- 尚未执行生产 MySQL/PostgreSQL 等数据库、真实 TLS/代理/压缩、长时间并发压力及应用完整 HTTP E2E。MongoDB、Elasticsearch 和不同 Socket 协议不自动取得关系型四栈同等能力认证。
- 构建仍可出现 JDK 25 下 Lombok/Netty/Mockito 的运行时兼容提示、MapStruct 注解处理提示，以及 macOS Netty DNS 原生库回退日志；本记录只声明测试通过，不声明依赖层零警告。

今后新增适配器，应先复用共同场景，再补该技术栈的事务、资源取消和方言测试；新增公共行为同步更新[运行时矩阵](../concepts/runtime-matrix.md)和对应权威指南。
