RBatis-Plus
An opt-in ORM L2 (result) cache product layered on top of RBatis, with a thin upstream hook surface and feature-rich Plus-side backends.
Status: DESIGN / PLANNING ONLY. Nothing in this repository is implemented yet. All crate names, module paths, type names, feature flags, dependencies, Mermaid diagrams, and code snippets in this README and in docs/ are proposed designs. No Rust workspace exists in this folder today.
- Date: 2026-07-24
- Upstream evidence baseline: RBatis
master@4050edd3dad03a113b8bb4f5818a006f11f2da78 - Latest surveyed commit title:
Limit decode fallback to single-column values - CodeGraph current stats (baseline): 178 files, 1,740 nodes, 17,805 edges, 192 classes, 715 functions, 655 tests; edge breakdown includes 9,366
CALLSand 5,524TESTED_BY; 88 flows, 14 communities.
Why
RBatis does not ship an ORM-level L2 cache. The "cache" you can find today is the prepared-statement cache inside rbdc-* drivers, plus historical SQL/parse caches — none of which is a cross-connection, cross-session query result cache. RBatis-Plus fills that gap by:
- Asking upstream RBatis for a small, generic execution-context and transaction-lifecycle surface (so cache, tracing, metrics, tenant, audit plugins can share it).
- Building the cache product —
CacheStoreSPI,CacheIntercept, policy model, key builder, in-process backend, Redis backend, macro annotations, admin helpers — entirely in RBatis-Plus.
The boundary is captured in docs/DECISIONS.md (ADR-001): "Upstream stays thin, RBatis-Plus carries the cache product."
Planned Crate Names
The following crate names are the planned names for the multi-crate workspace. None of them exist in this folder yet.
| Crate | Role |
|---|---|
rbatis-plus |
Meta-crate; facade and re-exports |
rbatis-plus-core |
Policy, SPI, CacheIntercept, key builder, error types |
rbatis-plus-mem |
In-process backend (planned: Moka-based) |
rbatis-plus-redis |
Distributed backend (planned: Redis async client) |
rbatis-plus-macros |
Declarative attribute annotations (planned, Phase 5) |
rbatis-plus-test |
Test-support helpers and fixtures (planned, no runtime role) |
The default cache is off. Users opt in by installing CacheIntercept after their SQL-rewriting interceptors.
Architecture (Planned)
The diagram below shows the planned layering from the user surface through RBatis-Plus and into upstream RBatis and rbdc. Boxes and edges are planned, not implemented.
flowchart TB
subgraph USER["User Code"]
CRUD["CRUD<br/>rbatis-plus wrapper or raw"]
WRAP["Wrapper / Query DSL"]
MAPPER["Mapper trait<br/>async fn"]
SVC["Service layer"]
end
subgraph PLUS["RBatis-Plus (planned)"]
MACROS["rbatis-plus-macros<br/>attribute metadata"]
CORE["rbatis-plus-core<br/>CacheIntercept / Policy / Key / Metrics"]
MEM["rbatis-plus-mem<br/>MemoryCacheStore (Moka)"]
REDIS["rbatis-plus-redis<br/>RedisCacheStore"]
TEST["rbatis-plus-test<br/>fixtures only"]
end
subgraph RBATIS["RBatis (upstream, evidence @ 4050edd3)"]
MACRO_DRV["Macro driver<br/>py_sql / html_sql / crud!"]
CODEGEN["Codegen"]
EXEC["Executor<br/>RBatis / RBatisConnExecutor / RBatisTxExecutor / Guard"]
INTERCEPT["Intercept chain<br/>Page / Log / + CacheIntercept"]
end
subgraph RBDC["rbdc / rbdc-* drivers"]
POOL["Pool"]
CONN["Connection"]
DRV["MySQL / Postgres / SQLite / MSSQL"]
end
subgraph TXLIFE["Transaction lifecycle hook boundary (planned)"]
HOOK["Begin / Commit / Rollback events<br/>TransactionListener"]
end
SVC --> MAPPER
MAPPER --> WRAP
WRAP --> CRUD
CRUD --> MACRO_DRV
CRUD --> EXEC
MACROS -.emits metadata.-> CORE
EXEC --> INTERCEPT
INTERCEPT --> CORE
CORE --> MEM
CORE --> REDIS
CORE --> TEST
EXEC --> POOL
POOL --> CONN
CONN --> DRV
DRV --> ROW["DB Row"]
ROW --> RBS["rbs::Value"]
RBS --> DECODE["decode<T>"]
DECODE --> CRUD
EXEC -.begin/commit/rollback.-> HOOK
HOOK -.fires.-> CORE
Plain-text flow (planned)
User service
-> Mapper trait method
-> Wrapper / Query DSL
-> CRUD or raw query
-> Executor::query / exec
-> Intercept chain (Page -> ... -> CacheIntercept -> Log)
-> CacheIntercept: build key, hit/miss, singleflight
-> on hit: return cached rbs::Value
-> on miss: fall through
-> Pool -> Connection -> rbdc driver
-> DB Row -> rbs::Value
-> decode<T> -> back to user
-> CacheIntercept.after: store rbs::Value
<- Executor returns rbs::Value
<- Wrapper returns T
<- Mapper returns T
<- Service consumes T
Transaction lifecycle boundary (planned):
Executor::begin / commit / rollback
-> TransactionListener events
-> CacheIntercept records pending invalidations by tx_id
-> on commit: flush pending tags
-> on rollback: discard pending tags
Evidence Summary (Latest Survey)
The RBatis workspace baseline used for the latest findings is master@4050edd3dad03a113b8bb4f5818a006f11f2da78. The full evidence and reasoning live in docs/RBatis 支持二级缓存调研报告.md. The current CodeGraph snapshot produced:
- 178 files, 1,740 nodes, 17,805 edges
- 192 classes, 715 functions, 655 tests
- 9,366
CALLS, 5,524TESTED_BY - 88 flows, 14 communities
- Latest commit title:
Limit decode fallback to single-column values
What that tells us:
- The RBatis workspace layers cleanly into
runtime / macro-driver / codegen / rbdc; caches that touchExecutortherefore cover py_sql, html_sql, raw queries, and CRUD without per-macro patches. Executoris the unified query/exec path acrossRBatis,RBatisConnExecutor,RBatisTxExecutor, andRBatisTxExecutorGuard.- CRUD is built on top of
py_sql; SQL flows through one pipeline. html_sqlcarries the highest CodeGraph criticality among the macro entry points — changes here must be conservative.- The macro driver returns a return-token string that contains the
ExecResultpayload; the executor recognises which path to take by the type token string. Cache keys therefore must be built from the final rewritten SQL, not the raw template. PageInterceptshares state maps keyed by executor id; cache ordering (rewriters before observers) is not optional.RBatisConnExecutor::beginconsumes the connection. Cloning the executor and callingbeginon a stale clone can fail because the innerMutex<Box<dyn Connection>>has already been moved. This shapes how the planned transaction-lifecycle hooks must be wired.- Transaction commit and rollback do not currently flow through any SQL
execinterceptor; theInterceptAPI cannot observe them. A transaction lifecycle hook boundary has to be added in upstream for production-grade cache consistency.
These findings reinforce the boundary principle: enhance Executor + Intercept + rbs::Value + py_sql rather than rebuild the ORM.
Repository Status
This folder currently contains only documentation. There is no Cargo workspace, no Rust source code, and no test infrastructure yet. Everything described above is a proposed design. Treat every Rust snippet in this README and in docs/ as a draft, not as evidence of behavior.
Documentation Index
The full documentation set lives under docs/. The nine detailed documents are kept in sync via this index.
| # | Document | Role |
|---|---|---|
| 1 | docs/RBatis 支持二级缓存调研报告.md |
Research report on RBatis L2 cache evidence (upstream baseline) |
| 2 | docs/ARCHITECTURE.md |
Planned RBatis-Plus architecture and layering |
| 3 | docs/IMPLEMENTATION_PLAN.md |
Phased plan, PR series, test matrix, acceptance gates |
| 4 | docs/CACHE_SPECIFICATION.md |
Wire protocol: keys, envelopes, codecs, tags, singleflight |
| 5 | docs/TRANSACTION_CONSISTENCY.md |
Transaction semantics, native vs conservative mode |
| 6 | docs/DECISIONS.md |
Architecture decision records (ADRs) |
| 7 | docs/INTEGRATION_GUIDE.md |
Integration gate template and future workspace setup |
| 8 | docs/OBSERVABILITY_SECURITY_OPERATIONS.md |
Observability, security, and operational posture |
| 9 | docs/TEST_AND_ACCEPTANCE_PLAN.md |
Test matrix and release gates |
Quick Links
- Research baseline:
docs/RBatis 支持二级缓存调研报告.md - Architecture:
docs/ARCHITECTURE.md - Implementation plan:
docs/IMPLEMENTATION_PLAN.md - Cache specification:
docs/CACHE_SPECIFICATION.md - Transactions:
docs/TRANSACTION_CONSISTENCY.md - Decisions:
docs/DECISIONS.md - Integration:
docs/INTEGRATION_GUIDE.md - Ops:
docs/OBSERVABILITY_SECURITY_OPERATIONS.md - Tests:
docs/TEST_AND_ACCEPTANCE_PLAN.md