# Ineed-Core 当前实现状态

## 文档定位

本文档用于把 `ineed-core` 当前代码、聚合 `pom.xml`、测试入口和已知缺口放在同一处说明。

它回答的是“现在仓库里实际有什么、推荐怎么用、哪些能力还不能按稳定主路径理解”。如果要看完整模块声明，读 [module-inventory.md](module-inventory.md)；如果要看能力分层，读 [module-capability-map.md](module-capability-map.md)。

## 当前使用口径

四条关系型业务路径为 WebMVC + JPA/JDBC/MyBatis-Flex，以及 WebFlux + R2DBC，均有源码与框架测试入口。详细的源码状态、本轮执行证据和未验证范围统一维护在[运行时矩阵](../concepts/runtime-matrix.md)。

开发人员可先沿[首个模块教程](../getting-started/first-module.md)学习 JDBC 路径，再对照其他实现；教学顺序不决定正式业务交付范围。公共能力、新模块和未限定单栈的任务，仍按[业务骨架](../project-development/business-module-layout-guide.md)评估并对齐目标栈。

服务缓存按阻塞/响应式运行时分别使用，不能混装。MongoDB 已进入聚合但不在本轮业务验证范围；Elasticsearch 聚合声明仍为注释；动态数据源 lookup key 仍返回 null；Druid starter 是依赖聚合。

## 代码结构速览

各模块的角色说明详见 [module-inventory.md](module-inventory.md)。

## 测试现状

当前 `ineed-core` 下存在较多可执行测试，覆盖基础契约、数据能力、WebMvc/WebFlux support、JPA/JDBC/MyBatis-Flex/R2DBC adapter 默认行为和聚合链路。

常用验证入口：

```bash
cd java/ineed-core
mvn test

cd java/ineed-core
mvn -pl ineed-core-base test

cd java/ineed-core
mvn -pl ineed-core-tests/ineed-core-test-webmvc test

cd java/ineed-core
mvn -pl ineed-core-tests/ineed-core-test-webflux test
```

当前仓库没有 Maven wrapper。本轮 effective POM 的编译 release 为 17，定向测试使用 JDK 25、Maven 3.9.15；这不等于已经完成 JDK 17 运行兼容性验证。准备步骤见[工具链说明](../getting-started/prerequisites.md)。

## 已知缺口

### 动态数据源

`ineed-core-modules/ineed-core-datasource/src/main/java/com/ineed/core/datasource/DynamicDataSource.java` 当前没有从上下文读取真实 lookup key。后续如果要支持租户级或运行时选择数据源，应先补齐：

- lookup key 来源与生命周期
- `DynamicDataSourceContextHolder` 的设置、清理和嵌套调用规则
- 对应单元测试和至少一个启动模块验证

### 数据库元数据

`ineed-rdb-metadata` 提供连接、表、列等元数据读取。当前 `RdbMetadataUtil` 已通过 `RdbMetadataException.readFailed` 转换 SQLException；调用方应区分读取失败和真实空结果。目标数据库厂商的支持范围仍需对应验证，见[接入指南](../guides/clients-and-metadata.md)。

### 响应式链路

`WebFlux + R2DBC` 已有模块和测试入口，本轮已执行相关框架链路测试，实际覆盖与环境边界见[验证记录](../maintenance/verification-2026-09-19.md)。响应式实现中要避免装配期求值，例如不要用 `Mono.just(getEntityClass())` 提前触发“不支持该操作”的同步异常。

### Starter 体系

`ineed-starter-druid` 当前没有源码级自动配置类，也没有 `spring.factories` 或 `AutoConfiguration.imports`。它只负责依赖聚合。后续如果要演进为真正 starter，应补齐：

- `@AutoConfiguration` 入口
- 条件装配规则
- 默认配置与用户覆盖策略
- starter 专用测试

### 服务缓存运行时边界

服务缓存已从 engine 中拆分为两套独立运行时：

- `ineed-core-service-cache` 由 `ineed-core-engine` 直接依赖，使用 Spring Cache、阻塞式 Redis/Redisson 依赖与阻塞式事务同步机制。
- `ineed-core-service-cache-reactive` 由 `ineed-core-engine-reactive` 直接依赖，使用 Reactive Redis 与响应式事务同步机制。
- 两套模块都通过 `AutoConfiguration.imports` 注册各自配置，但响应式 engine 不依赖阻塞式 engine，响应式缓存也不依赖阻塞式缓存。

新增缓存能力时，应分别验证阻塞式和响应式实现，不要通过引入另一套运行时来复用实现。

## 文档维护要求

当代码结构变化时，按下面顺序更新文档：

1. 先更新 [module-inventory.md](module-inventory.md)，确保模块声明与聚合 `pom.xml` 一致。
2. 再更新本文档，说明能力状态、推荐口径和已知缺口是否变化。
3. 如果影响业务开发主路径，再更新 [module-capability-map.md](module-capability-map.md)、[crud-query-guide.md](../project-development/crud-query-guide.md)、[r2dbc-code-guide.md](../project-development/r2dbc-code-guide.md) 和 [business-module-layout-guide.md](../project-development/business-module-layout-guide.md)。
4. 如果影响项目开发规则，再更新 [development-contract.md](../project-development/development-contract.md) 和 [code-style-guide.md](../project-development/code-style-guide.md)。

> 最后核验：2026-09-19