Nacos Data Source Dialect 插件规范:多数据库方言与 Mapper 层架构实战解析
Nacos Data Source Dialect 插件规范:多数据库方言与 Mapper 层架构实战解析
Nacos 的持久化层通过 Data Source Dialect(数据源方言)插件把"一份逻辑 Schema + 一套 Repository 契约"翻译成不同数据库(Derby、MySQL、PostgreSQL、Oracle)特有的 SQL。本文以 datasource-dialect-plugin-spec.md 为骨架,结合 plugin/datasource 与 plugin-default-impl/nacos-default-datasource-plugin 的真实源码与 distribution/conf/application.properties 配置示例,系统讲解该插件的 SPI 契约、分页与自增主键机制、启动期互斥选择、数据源连接配置迁移,以及 LIKE 模糊查询转义等易踩坑细节,帮助你理解 Nacos 如何在不改逻辑模型的前提下自由切换数据库,并掌握自定义方言插件的落地方法。
一、为什么需要 Data Source Dialect 插件
Nacos 的持久化层希望在所有数据库上保持同一个逻辑数据模型:表名、列语义、事务预期、分页顺序、乐观更新行为完全一致。差异只发生在"数据库方言"这一层——分页写法(LIMIT ? 与 ROWNUM)、自增主键回填方式、SQL 函数命名、唯一键冲突的异常判定等。
方言插件正是为此而生的隔离层:它不是一个持久化域的属主(persistence domain owner),而是一个 SQL 翻译器。Repository 契约与持久化/转储边界由 Persistence And Dump Spec 定义;方言插件只负责把 Repository 调用翻译成具体数据库的 SQL,绝不决定资源标识、授权、兼容性策略或用户可见的领域行为。
从源码结构看,这种边界在模块划分上非常清晰:
plugin/datasource只定义契约(DatabaseDialect、Mapper、MapperManager、MapperContext、MapperResult)与常量;plugin-default-impl/nacos-default-datasource-plugin提供内置的 4 个数据库族实现(derby、mysql、postgresql、oracle);- 领域模块(如
config模块中的 Config Repository)仍持有具体持久化实现——因为它们承载了 Config 发布、历史、灰度、容量等领域语义,方言插件只向其提供 SQL 方言与 Mapper 层。
二、核心概念
| 概念 | 含义 |
|---|---|
| SQL platform | 部署时选定的数据库类型,如 derby、mysql、postgresql、oracle |
| Dialect | 数据库级别的 SQL 行为:分页、生成主键、函数映射等 |
| Mapper | 面向"一张逻辑表 + 一种数据库类型"的表级 SQL 提供者 |
| Logical schema | 所有数据库共享的 Nacos 表与列语义 |
有一个必须遵守的铁律:SQL platform 必须同时选定 DatabaseDialect 和同属一个数据库族的 Mapper 集合。用 A 数据库的方言搭配 B 数据库的 Mapper 是非法组合。
三、SPI 契约:DatabaseDialect
方言实现需要实现 com.alibaba.nacos.plugin.datasource.dialect.DatabaseDialect 接口(见 DatabaseDialect.java),该接口继承自 PluginConfigSpec(统一插件配置契约)。核心方法如下:
| 方法 | 要求 |
|---|---|
getType() |
返回稳定的数据库类型名,如 derby、mysql、postgresql、oracle |
getLimitTopSqlWithMark(sql) |
追加基于占位符的 top 限制 SQL(如 LIMIT ?) |
getLimitPageSqlWithMark(sql) |
追加基于占位符的分页 SQL(如 LIMIT ?,?) |
getLimitPageSql(sql, pageNo, pageSize) |
追加带数值的分页 SQL |
getLimitPageSqlWithOffset(sql, startOffset, pageSize) |
追加基于 offset 的分页 SQL |
getPagePrevNum(page, pageSize) |
返回分页第一个参数(如 offset) |
getPageLastNum(page, pageSize) |
返回分页第二个参数(如 pageSize) |
getReturnPrimaryKeys() |
返回生成主键的列名 |
getFunction(functionName) |
把逻辑函数名映射为方言 SQL 函数 |
isDuplicateKeyException(throwable) |
判定数据源异常是否为"唯一键冲突",默认识别 cause 链中的 Spring DuplicateKeyException |
3.1 分页默认实现
内置基础抽象类 AbstractDatabaseDialect(见 AbstractDatabaseDialect.java)为 MySQL/PostgreSQL 系的 LIMIT 语法提供了默认分页实现:
@Override
public int getPagePrevNum(int page, int pageSize) {
return (page - 1) * pageSize; // offset = (page-1) * pageSize
}
@Override
public String getLimitPageSqlWithMark(String sql) {
return sql + " LIMIT ?,? "; // 占位符分页
}
@Override
public String getLimitPageSql(String sql, int pageNo, int pageSize) {
return sql + " LIMIT " + getPagePrevNum(pageNo, pageSize) + " , " + pageSize;
}
@Override
public String[] getReturnPrimaryKeys() {
return PrimaryKeyConstant.LOWER_RETURN_PRIMARY_KEYS;
}
而 Oracle 方言的 OracleDatabaseDialect 则会把分页改写为 ROWNUM 形式,PostgreSQL 方言的 PostgresqlDatabaseDialect.java 也覆盖了 getLimitPageSqlWithMark 等分页方法——这正是"同一套 Repository 契约、不同 SQL 输出"的直观体现。基础测试 AbstractDatabaseDialectTest.java 中也有 assertEquals("SELECT LIMIT ?,? ", dialect.getLimitPageSqlWithMark("SELECT")) 这类断言可验证行为。
3.2 isDuplicateKeyException:唯一键冲突判定的唯一入口
isDuplicateKeyException(throwable) 是 Config Repository 判断"某次插入失败是否为唯一键冲突"的唯一入口。接口默认实现(见 DatabaseDialect.java)遍历 throwable 的 cause 链,按类名匹配 Spring 的 DuplicateKeyException:
String SPRING_DUPLICATE_KEY_EXCEPTION = "org.springframework.dao.DuplicateKeyException";
default boolean isDuplicateKeyException(Throwable throwable) {
Throwable cause = throwable;
while (cause != null) {
Class<?> type = cause.getClass();
while (type != null) {
if (SPRING_DUPLICATE_KEY_EXCEPTION.equals(type.getName())) {
return true;
}
type = type.getSuperclass();
}
cause = cause.getCause();
}
return false;
}
这里有两个设计要点:
- 按类名而非按类型匹配,目的是让 datasource 插件模块保持"零 Spring 依赖"的依赖足迹;
- 故意不把裸的厂商 SQLState(如 PostgreSQL 的
23505)直接当作重复键——这是对过去"数据库无关分类逻辑"的安全基线复刻,避免把非重复的完整性错误误判为重复。
PostgreSQL、MySQL、Derby、Oracle 等方言在标准 Spring 异常翻译不够精确时,可以覆写此方法,额外检查原始驱动异常(SQLState 或厂商错误码),典型写法是结合 DatabaseDialect.super.isDuplicateKeyException(throwable) 调用默认实现。但分类必须保持保守:非重复键的完整性失败绝不能上报为重复键。
四、SPI 契约:Mapper 层
表级 Mapper 插件实现 com.alibaba.nacos.plugin.datasource.mapper.Mapper 接口(见 Mapper.java),为 Repository 操作提供基础 CRUD SQL 与表级专用 SQL。当前内置 Mapper 族覆盖:
- 当前配置数据:
config_info、config_info_gray、config_tags_relation、his_config_info; - 命名空间与容量记录:
tenant_info、tenant_capacity、group_capacity; - AI 注册表记录:AI 资源元数据(
AiResourceMapper)与 AI 资源版本(AiResourceVersionMapper)。
AbstractMapper(见 AbstractMapper.java)提供了模板化的 select / insert / update / delete / count 实现,列名与占位符通过 @ 分隔约定组合;getPrimaryKeyGeneratedKeys() 的默认值是 new String[] {"id"}(取代了旧的 Statement.RETURN_GENERATED_KEYS)。
4.1 Mapper 默认方法:MySQL 兼容语法与覆盖义务
Mapper 接口允许为某个操作提供 default SQL,但这些默认 SQL 按 MySQL 兼容语法书写(包括 LIMIT 这类行限制子句)。如果一个数据库方言不接受该语法,就必须覆写每一个受影响的操作——注意:继承默认写法产生的不是启动失败,而是查询期的 SQL 语法错误。同时,Mapper 默认方法必须从 Repository 写入的同一个 MapperContext 中读取可选过滤值,确保可选谓词与绑定参数总是成对出现。
MapperContext(见 MapperContext.java)正是 Repository 与 Mapper 之间的统一参数通道:它持有 whereParamMap、updateParamMap、contextParamMap 三张 Map,外加 startRow 与 pageSize 分页字段。
4.2 LIKE 模糊查询的转义陷阱
模糊搜索参数在绑定前会用反斜杠转义 _ 通配符,这使得 LIKE 谓词也成了方言敏感点:
- MySQL 与 PostgreSQL:反斜杠是默认的
LIKE转义字符,开箱即用; - Derby 与 Oracle:没有默认转义字符,反斜杠会被字面匹配,继承的默认谓词会静默返回空行而不是报错。
因此,没有默认转义字符的方言必须通过 Mapper#getLikeEscapeClause() 上报其转义子句(Mapper 接口中默认返回空串,常量 LIKE_ESCAPE_CLAUSE = "ESCAPE '\\' "),并且每一个绑定此类参数的 LIKE ?(无论是 Mapper 默认方法还是方言覆写)都必须追加该子句。该子句不能硬编码进共享默认方法,因为不同数据库接受的转义字符字面量不同。
声明转义子句同时约束了调用方:一旦 LIKE 谓词声明了转义字符,绑定参数必须先转义转义字符本身、再转义 _,否则搜索值中若含字面反斜杠会构成非法转义序列,导致数据库拒绝整个查询(Oracle ORA-01424、Derby SQLSTATE 22025)。每个模糊搜索参数的产出方都必须遵循同一转义顺序:
先转义
\→ 再转义_→ 最后把 Nacos 通配符*替换为%。
4.3 MapperManager 的加载与索引
MapperManager(见 MapperManager.java)通过 Nacos SPI 加载全部 Mapper 实现,并按 dataSource + tableName 建立二级索引(MAPPER_SPI_MAP)。findMapper(dataSource, tableName) 在 datasource 或 table 缺失时抛出 NacosRuntimeException(FIND_DATASOURCE_ERROR_CODE / FIND_TABLE_ERROR_CODE)——缺失数据源或表 Mapper 是启动或运行期错误,而不是返回空结果。当 nacos.plugin.datasource.log.enabled=true 时,findMapper 会通过 MapperProxy.createSingleProxy(mapper) 返回代理以记录 SQL 日志(见 MapperProxy.java 与对应测试 MapperManagerTest.java)。
五、选择与状态:互斥型(EXCLUSIVE)插件
datasource-dialect 是**互斥选择(EXCLUSIVE)**插件类型,同一时刻只启用一个配置的方言。其核心插件类型为 critical,加载期间必须保持一个已选实现。
- 方言选择器在启动引导期完成选择,变更必须重启;
- 针对该互斥类型,持久化的状态条目不能替代静态选择,运行期状态 API 必须拒绝选择变更;
- 当标准选择键与历史别名都未配置时,选择跟随服务器存储默认值:单机模式与
-DembeddedStorage=true的集群模式选择derby;普通集群模式选择mysql。这个隐式选择也会在启动时被快照记录。
在运行期,DatabaseDialectManager#getDialect(databaseType)(见 DatabaseDialectManager.java)在返回方言前会先通过 PluginStateCheckerHolder.isPluginEnabled(PluginType.DATASOURCE_DIALECT.getType(), databaseType) 检查统一插件状态:
if (!PluginStateCheckerHolder.isPluginEnabled(...)) {
throw new IllegalStateException("DatabaseDialect plugin is disabled: " + databaseType
+ ". Please enable it via plugin management API.");
}
DatabaseDialect databaseDialect = SUPPORT_DIALECT_MAP.get(databaseType);
if (databaseDialect == null) {
throw new IllegalStateException("No DatabaseDialect implementation found for selected type: "
+ databaseType + "...");
}
被禁用的方言不得参与持久化操作。持久化子系统始终使该 critical 类型处于激活状态;如果请求的方言被禁用或缺失,启动必须显式失败并明确指出所选的方言与选择属性,服务器绝不能回退到另一个被发现但未配置的方言。
六、配置指南
6.1 SQL 平台选择
数据库类型通过如下标准键选择:
nacos.plugin.datasource-dialect.type=${databaseType}
spring.sql.init.platform仍是历史别名,两者同时配置时标准键优先;- 已被移除的
spring.datasource.platform不再被读取。
distribution/conf/application.properties 中的实际注释示例:
### The database dialect selected at startup. Legacy spring.sql.init.platform remains supported.
#nacos.plugin.datasource-dialect.type=mysql
#spring.sql.init.platform=mysql
从 plugin-spec.md 的互斥类型选择表可知,datasource-dialect 的默认值是 derby,标准键为 nacos.plugin.datasource-dialect.type,历史别名 spring.sql.init.platform 计划在 Nacos 4.0.0 移除。
6.2 数据源模块配置(Datasource Module Configuration)
连接属性由 Nacos 持久化模块与数据库驱动所有,统一收敛到以下模块前缀:
nacos.plugin.datasource.db.{item}
注意:这个命名空间并不使数据库方言可配置。DatabaseDialect 虽继承统一配置契约,但内置的 datasource-dialect:{databaseType} 实例不声明任何配置定义,对外暴露 configurable=false——因为连接凭据与连接池设置属于"单个服务器数据源",而不是属于每个已加载的方言。这些设置是静态的、重启生效,且不被插件 detail/PUT 配置 API 接受。
完整稳定的数据源模块配置项如下:
| 标准键或模式 | 历史别名 | 含义 |
|---|---|---|
nacos.plugin.datasource.db.num |
db.num |
外部数据源端点数量。外部存储场景下必填且必须为正数 |
nacos.plugin.datasource.db.url.{index} |
db.url.{index} |
每个 index(0 到 num - 1)的 JDBC URL |
nacos.plugin.datasource.db.user[.{index}] |
db.user[.{index}] |
共享或按 index 的用户名;缺失的 index 回退到共享值或 index 0 |
nacos.plugin.datasource.db.password[.{index}] |
db.password[.{index}] |
共享或按 index 的密码,回退规则同 user,敏感值 |
nacos.plugin.datasource.db.pool.config.connection-timeout |
db.pool.config.connectionTimeout 或 kebab-case 等价写法 |
Hikari 连接超时(毫秒),默认 3000 |
nacos.plugin.datasource.db.pool.config.validation-timeout |
db.pool.config.validationTimeout 或 kebab-case 等价写法 |
Hikari 校验超时(毫秒),默认 10000 |
nacos.plugin.datasource.db.pool.config.idle-timeout |
db.pool.config.idleTimeout 或 kebab-case 等价写法 |
Hikari 空闲超时(毫秒),默认 600000 |
nacos.plugin.datasource.db.pool.config.maximum-pool-size |
db.pool.config.maximumPoolSize 或 kebab-case 等价写法 |
Hikari 最大连接池大小,默认 20 |
nacos.plugin.datasource.db.pool.config.minimum-idle |
db.pool.config.minimumIdle 或 kebab-case 等价写法 |
Hikari 最小空闲连接数,默认 2 |
nacos.plugin.datasource.db.pool.config.driver-class-name |
db.pool.config.driverClassName 或 kebab-case 等价写法 |
JDBC 驱动类;留空使用 MySQL 驱动兼容默认值 |
nacos.plugin.datasource.db.pool.config.connection-test-query |
db.pool.config.connectionTestQuery 或 kebab-case 等价写法 |
连接测试查询;留空使用 SELECT 1 |
nacos.plugin.datasource.db.query-timeout |
JVM 属性 QUERYTIMEOUT |
JDBC 查询超时(秒),默认 3 |
优先级与迁移规则:
- 对每个逻辑配置项,即使标准键与历史别名来自不同的 Spring 属性源,标准键也优先;
- 带 index 的配置项独立解析,迁移期允许规范
url.0与历史url.1共存; - 使用历史别名会输出迁移警告,但不会记录配置值;
- 点号与方括号两种索引写法均被接受,单个不带索引的
url兼容 index0; nacos.plugin.datasource.db.pool.config.{hikari-property}前缀会继续绑定到 Hikari 数据源(在历史 pool 前缀绑定之后),以保留现有 Hikari 透传属性,同时允许规范值覆盖同名的历史值。长期 Nacos 配置契约只有上表列出的稳定子集。
distribution/conf/application.properties 中的实际示例(含历史别名说明):
# nacos.plugin.datasource.db.num=1
# nacos.plugin.datasource.db.url.0=jdbc:mysql://127.0.0.1:3306/nacos?characterEncoding=utf8&connectTimeout=1000&socketTimeout=3000&autoReconnect=true&useUnicode=true&useSSL=false&serverTimezone=UTC
# nacos.plugin.datasource.db.user=nacos
# nacos.plugin.datasource.db.password=nacos
# nacos.plugin.datasource.db.query-timeout=3
### Legacy db.* properties and the QUERYTIMEOUT JVM property remain supported as aliases.
### When both forms are configured, nacos.plugin.datasource.db.* takes precedence.
补充要点:
nacos.plugin.datasource.log.enabled仍是独立的数据源日志开关(非插件实现状态,见 plugin-spec.md 内置开关分类表);- 内嵌/外部持久化模式不属于方言私有配置;
- 自定义的、负责转换加密数据源凭据的 environment 插件,必须在自己的
propertyKey()集合中声明规范的密码键;仅声明db.password.*的旧实现只会处理历史输入。
七、内置数据库族实现
内置实现位于 plugin-default-impl/nacos-default-datasource-plugin,是随 Nacos 服务端发行版捆绑的持久化兼容层,不得引入数据库特有的资源语义(详见 default-datasource-dialect-plugin-spec.md)。
| 数据库类型 | 方言提供者 | Mapper 包 |
|---|---|---|
derby |
DerbyDatabaseDialect |
impl.derby |
mysql |
MysqlDatabaseDialect 与 DefaultDatabaseDialect |
impl.mysql |
postgresql |
PostgresqlDatabaseDialect |
impl.postgresql |
oracle |
OracleDatabaseDialect |
impl.oracle |
每个数据库包都必须同时注册 com.alibaba.nacos.plugin.datasource.dialect.DatabaseDialect 与 com.alibaba.nacos.plugin.datasource.mapper.Mapper 两类 SPI 文件,并按上表覆盖全部 9 张表的 Mapper(当前配置、灰度、标签、历史、命名空间、容量、AI 资源元数据与版本)。
从源码目录可以看到每族实现都是一一对应的:例如 Derby 族的 ConfigInfoMapperByDerby.java、MySQL 族的 ConfigInfoMapperByMySql.java、PostgreSQL 族的 ConfigInfoMapperByPostgresql.java、Oracle 族的 ConfigInfoMapperByOracle.java。每族还配套了专门的覆盖测试(如 MySqlMapperCoverageTest、OracleMapperCoverageTest、DerbyMapperCoverageTest、PostgresqlMapperCoverageTest),用于校验 Mapper 集合的完整性。
Nacos 3.3 起的变更:内置数据库族不再要求为"默认命名空间存储重复"或历史 beta/tag 灰度表提供运行期 Config 迁移查询。携带 3.0 之前 config_info_beta 或 config_info_tag 数据的部署,必须在升级到依赖当前 Mapper 集合的 3.3 服务器之前完成数据迁移——迁移是升级前置条件,而不是服务器运行期 Mapper 的职责。同样,若未来 Nacos 新增持久化表,内置族必须先补充对应 Mapper,然后该表才能成为文档化的服务器特性。
八、兼容性规则
数据库插件必须保持 Nacos 表语义、事务预期、分页顺序与乐观更新行为,不得改变逻辑 Schema 或资源模型(资源模型见 resource-model-spec.md)。实现方必须:
- 保持逻辑表名与列语义稳定;
- 对运行期值一律使用占位符 SQL;
- 对相同查询顺序保持分页确定性;
- 保持 Repository 预期的生成主键行为;
- 把 SQL 函数名保持在
getFunction(functionName)之后; - 文档化数据库版本要求与迁移要求。
具体到实现层面(见 default-datasource-dialect-plugin-spec.md 的兼容性小节):
- 保持各数据库族间 Nacos 逻辑 Schema 一致、SQL 占位符与参数顺序兼容 Repository 代码、insert 预期的主键列一致;
- AI 资源 Mapper 行为必须与资源模型对齐;
- 某数据库族需要 Schema 变更时必须附加迁移说明。
关于 critical 语义还有一个容易混淆的点:datasource-dialect 类型在加载期间是 critical 的,被选中的内置方言不能通过运行期插件状态禁用;但另一个只是"存在"的内置方言并不会仅仅因为被捆绑就单独成为 critical。
九、小结
Data Source Dialect 插件是 Nacos "一份逻辑模型,多库运行"的关键抽象:DatabaseDialect 负责数据库级方言行为(分页、生成主键、函数映射、重复键判定),Mapper 负责表级 SQL,MapperManager 与 DatabaseDialectManager 分别完成加载索引与运行期使能检查,而互斥选择与 critical 校验保证了"启动即选型、缺则必失败"的确定性。若要接入新的数据库族,核心工作就是:实现 DatabaseDialect(含 getLikeEscapeClause 等方言细节)、为全部逻辑表实现 Mapper、同时注册两类 SPI,并遵循占位符、转义顺序与兼容性规则。
十、延伸阅读
- Nacos Plugin Spec:所有插件类型的公共运行时契约(身份、执行模式、状态与配置来源优先级、管理 API)
- Default Data Source Dialect Implementation Spec:内置 4 个数据库族实现的细节与兼容性要求
- Persistence And Dump Spec:持久化与转储边界
- Resource Model Spec:Nacos 资源模型
- Resource Model 设计文档:中文版资源模型说明
- application.properties:方言选择与数据源模块配置的权威示例
- DatabaseDialect.java 与 Mapper.java:SPI 契约源码
- DatabaseDialectManager.java 与 MapperManager.java:运行时管理与使能检查