[English] [中文]
愿景 “One API Access Any DataBase”
一款数据库访问库，提供 Java 对多种不同类型数据库统一访问，它的目标是使用一套 API 访问所有数据库。
Website • Documentation • Blog
--- ## 📖 简介 | Introduction **dbVisitor** 是一款基于 JDBC 标准构建的**统一数据访问基座**，致力于实现 **“One API Access Any DataBase”** 的愿景。 借助独特的**双层适配器架构**，它成功打破了 RDBMS 与 NoSQL 之间的编程壁垒，让开发者能够使用**同一套标准 API** 无缝操作 MySQL、MongoDB、Elasticsearch 等各类数据库。 dbVisitor 不主张发明新语法去掩盖差异，而是通过**标准化**与**分层抽象**来科学地**管理差异**，为 Java 应用提供了一个既具备便捷性又保留 JDBC 灵活性的通用数据底座。
dbVisitor 提供了多层次的 API 抽象，允许在 **简单性** 与 **灵活性** 之间自由切换：
- 🛡 **LambdaTemplate**: 屏蔽差异
- 类型安全的 Lambda 查询构建器，支持链式调用。
- 单表 CRUD 方法，开箱即用，自动翻译为目标数据库的 SQL 或 DSL。
- 🧱 **Mapper/Interface**: 管理差异
- 声明式接口编程，支持 `@Query`/XML，将 SQL/DSL 逻辑与代码分离。
- 提供 BaseMapper 通用方法无需重复开发。
- 🔧 **JdbcTemplate**: 透传差异
- 标准 JDBC 模板方法，支持原生 SQL 和 Shell 脚本透传。
- 提供 ConnectionCallback，允许直接访问底层驱动 API。
## ✨ 核心特性 | Features
### ⚙️ 框架特点 (Framework Characteristics)
- **🛡️ 统一基座**: 一套 API 通杀 RDBMS (MySQL, PG...) 与 NoSQL (Mongo, ES...)。
- **🔌 广泛兼容**: 纯 Java (JDK8+)，零依赖，完美适配 Spring/Solon 等主流框架。
- **📦 轻量级**: 极简设计，核心仅依赖 `cobble` 工具包。
### 🔋 基础能力 (Capabilities)
- **API 分层抽象**：
- [编程式 API](https://www.dbvisitor.net/docs/guides/api/program_api)，通过编程方式实现对数据库的访问，最大特点是具有强大的灵活性。
- [声明式 API](https://www.dbvisitor.net/docs/guides/api/declarative_api)，通过接口可以对 SQL 的维护更加集中，使代码结构变得更加清晰。
- [通用 Mapper](https://www.dbvisitor.net/docs/guides/api/base_mapper)，通用 Mapper 可以让您的程序在数据访问层变得更加精炼。
- [构造器 API](https://www.dbvisitor.net/docs/guides/api/lambda_api)，通过链式调用的方式构造查询条件，避免了手写 SQL 的繁琐。
- [文件 Mapper](https://www.dbvisitor.net/docs/guides/api/file_mapper)，通过文件的方式编写 SQL 或 DSL，使得 SQL 逻辑与代码完全分离。
- [JDBC 适配器](https://www.dbvisitor.net/docs/guides/drivers/about)，提供对 JDBC 的标准封装，支持各类非关系型数据库的接入。
- **对象映射**：
- [一套 API](https://www.dbvisitor.net/docs/guides/core/mapping/about) 应对不同类型数据源，学习曲线平稳，无需掌握复杂的概念。
- 支持智能结果集映射，自动处理 [驼峰转换](https://www.dbvisitor.net/docs/guides/core/mapping/camel_case) 与属性填充。
- 内置 6 种 [主键生成器](https://www.dbvisitor.net/docs/guides/core/mapping/keytype)，不够还可以自定义
- Tips：不支持关系映射，如：一对一、一对多、多对一、多对多。
- **SQL Rules**：
- [动态 SQL 简化](https://www.dbvisitor.net/docs/guides/rules/about)，引入 `@{...}` 规则语法，大幅简化动态 SQL 拼接逻辑，告别繁琐的 XML 标签。
- [SQL 增强规则](https://www.dbvisitor.net/docs/guides/rules/dynamic_rule)，内置 `@{and}`, `@{or}`, `@{in}` 等规则，自动根据参数空值情况判定条件是否生效。
- [参数处理规则](https://www.dbvisitor.net/docs/guides/rules/args_rule)，支持 `@{md5}`, `@{uuid}` 等指令，在 SQL 执行前对参数进行预处理。
- **参数处理**：
- 支持 [位置参数](https://www.dbvisitor.net/docs/guides/args/position)，语句中使用 “?” 标记参数，可以将值绑定到相应索引（从 0 开始）的参数。
- 支持 [名称参数](https://www.dbvisitor.net/docs/guides/args/named)，语句中使用如 :name、&name 或 #{...} 写法，可以将 SQL 中的参数名称化。
- 支持 [SQL 注入](https://www.dbvisitor.net/docs/guides/args/inject)，语句中使用 ${...} 写法，可以对已名称化的参数进行取值，并将结果注入到 SQL 语句中。
- 支持 [规则传参](https://www.dbvisitor.net/docs/guides/args/rule)，语句中通过 @{...} 写法，可以借助 规则 机制，优雅的处理一些常见动态 SQL 场景。
- 支持 [接口方式](https://www.dbvisitor.net/docs/guides/args/interface)，通过接口实现方式让参数设置更加具有定制化，以满足一些特殊的场景。
- **TypeHandler**：
- 灵活的类型转换系统，自动处理复杂映射。
- 丰富的类型支持，涵盖 [基础类型](https://www.dbvisitor.net/docs/guides/types/handlers/about)、
[JSON](https://www.dbvisitor.net/docs/guides/types/json-serialization)、
[枚举](https://www.dbvisitor.net/docs/guides/types/enum-handler)、
[数组](https://www.dbvisitor.net/docs/guides/types/array-handler)、
[时间类型](https://www.dbvisitor.net/docs/guides/types/handlers/datetime-handler)、
[地理信息类型](https://www.dbvisitor.net/docs/guides/types/gis-handler)、
[流类型](https://www.dbvisitor.net/docs/guides/types/stream-handler)、
[字节类型](https://www.dbvisitor.net/docs/guides/types/handlers/bytes-handler) 等。
- **接收结果**：
- 在所有类型数据源上提供多种方式处理查询结果。
- 常见结果处理有 [Bean映射](https://www.dbvisitor.net/docs/guides/core/mapping/about)、
[RowMapper](https://www.dbvisitor.net/docs/guides/result/for_mapper)、
[RowCallbackHandler](https://www.dbvisitor.net/docs/guides/result/row_callback)、
[ResultSetExtractor](https://www.dbvisitor.net/docs/guides/result/for_extractor)
- **Session/Transaction**：
- 支持多数据源事物管理（非分布式事务）
- 支持和 Spring 一样的事务控制能力，包括 [7 种事物传播行为](https://www.dbvisitor.net/docs/guides/transaction/propagation)。
- 支持通过 [编程式](https://www.dbvisitor.net/docs/guides/transaction/manager/program)、
[注解式](https://www.dbvisitor.net/docs/guides/transaction/manager/annotation)、
[模版方法](https://www.dbvisitor.net/docs/guides/transaction/manager/template) 几种方式控制事务。
- Tips：尽管 dbVisitor 统一了事务等调用形式，但它不能改变底层数据库的物理特性。
- **高级特性**：
- Map 结构亲和力强，支持多种结果集格式：
- 单值/单列/单行/多行/分页 等多种结果集接收方式。
- 支持返回 List\