扩展机制
ApiGo 在三个层面提供扩展能力：数据源驱动（接入新的数据库/存储）、结果处理插件（加工返回数据）、运行配置钩子（不改代码调整行为）。本文从代码结构角度说明扩展点如 何加载、如何执行，使用说明见 数据插件 与 数据源管理。
数据源驱动 SPI
加载方式
数据源驱动基于 Java ServiceLoader 发现，无需修改核心代码：
新增驱动需要三步：
- 实现
DataSourceDriver接口（或继承DefaultDataSourceDriver）。 - 在模块的
META-INF/services/cn.apigo.core.spi.datasource.DataSourceDriver中写入实现类全名。 - 将模块加入
apigo-api与apigo-admin的依赖，使两端的ServiceLoader都能发现。
驱动名称必须唯一
DataSourceManager 初始化时按 getName() 注册；名称重复或为空会直接抛出 51003/51004 异常，阻止服务启动。类型匹配时统一转小写。
接口职责
| 方法 | 作用 |
|---|---|
getName() | 驱动类型标识，与数据源配置的 datasourceType 对应 |
isRelational() | 是否关系型；决定是否走事务与 JDBC 连接池 |
supportsTransaction() / supportsStatement() / supportsMetaData() | 能力声明，执行引擎据此选择执行路径 |
test() | 数据源连通性测试 |
init() / destroy() | 连接池或客户端生命周期 |
getMetaData() | 库表结构浏览（表、字段、索引） |
getStatement() | SQL/查询语句执行 |
两类驱动
- JDBC 驱动：
JdbcDataSourceDriver继承DefaultDataSourceDriver，统一处理连接池、事务、元数据与StatementMapper。MySQL、Oracle、PostgreSQL 等关系型数据库共用这一实现，差异由 JDBC URL 与驱动包决定。 - 原生驱动：MongoDB、Elasticsearch 直接实现
DataSourceDriver，声明isRelational=false，自行管理客户端与查询语句。这类数据源不参与 SQL 事务，元数据能力也按驱动实现。
连接池隔离
DataSourceManager 在进程内维护三类映射：
| 映射 | 内容 |
|---|---|
pluginType | 驱动类型 → 驱动实例 |
pluginDataSourcePool | 数据源 ID → 原生驱动实例 |
DATA_SOURCE_POOL_JDBC | 数据源 ID → JDBC DataSource |
同一数据源切换驱动类型时，会释放旧类型的资源，避免连接池泄漏。管理端多实例各自维护本地连接池，共享的只是 Redis 中的配置快照。
结果处理插件
执行链
插件在接口执行完成、响应写出之前运行，输入是结果数据，输出是加工后的数据。执行器 PluginExecutor 的工作方式：
- 解析接口上的
pluginConfigJSON。结构为{ "<pluginType>": { "enabled": true, ... } }。 - 按
getType()从 Spring 容器注册的PluginHandler中匹配处理器。 - 只保留
enabled=true的插件，按getOrder()升序执行。 - 每个处理器的输出作为下一个处理器的输入。
内置处理器
| 类型 | 顺序 | 职责 |
|---|---|---|
fieldMapping | 5 | 字段重命名 / 映射 |
dataProcess | 10 | 过滤、排序、脱敏、加密、计算 |
dictTransform | 11 | 字典值转文本 |
fieldFormat | 12 | 日期、金额、百分比、大小写、去空格 |
fieldReplace | 13 | 空值 / 正则匹配替换 |
dataMerge | 14 | 多字段合并为一个字段 |
dataAggregation | 15 | 分组聚合（求和、计数、平均、最大、最小） |
treeTransform | 30 | 列表转树 |
singleObject | 35 | 列表取单条 |
nestedStructure | 40 | 按路径构造多级嵌套 |
分组聚合在界面中未开放
dataAggregation 已实现并注册，但当前前端插件面板没有暴露入口。通过接口定义 JSON 配置后仍可生效；这属于后端已具备、界面暂未开放的能力。
容错语义
插件执行出现异常时，PluginExecutor 记录错误日志并返回原始数据，不会让接口调用失败。这一设计保证「加工逻辑出错」不会升级为「接口不可用」，但也意味着插件配置错误只能从日志发现，不会体现在响应码上。
新增处理器
- 实现
PluginHandler，返回唯一的getType()与合适的getOrder()。 isEnabled()默认读取配置中的enabled字段，通常无需重写。- 在
PluginConfiguration中注册为 Spring Bean，或在任意@Configuration中声明 Bean。 - 前端需要增加对应配置面板；否则只能通过接口定义的
pluginConfigJSON 使用。
处理器应保持幂等、无外部副作用，并假设输入可能是单对象或列表。
报告与数据加工边界
| 能力 | 扩展方式 | 是否需要改代码 |
|---|---|---|
| 接入新数据库 | 实现 DataSourceDriver + SPI 注册 | 是 |
| 修改返回字段结构 | 配置数据插件 | 否 |
| 调整 SQL 方言差异 | JDBC 驱动或自定义 StatementMapper | 视情况 |
| 新增 AI 工具 | McpAdminToolAdapter 中声明 @Tool 方法 | 是 |
| 调整限流/缓存/告警行为 | 管理界面配置 | 否 |
| 替换 License 签名算法 | 实现 SignatureAlgorithm | 是（厂商侧） |
与管理端的扩展边界
管理端执行服务共用同一套 apigo-core 与 apigo-plugin，因此：
- 数据源驱动必须在两端都可加载。只加入执行服务依赖时，管理端的连接测试与元数据浏览会失败。
- 结果插件只在执行链路生效，管理端预览接口时同样会执行插件，便于所见即所得。
- 修改插件执行顺序会影响所有已启用该插件的接口，属于全局行为变更，需要回归验证。