NiFi自定义Controller Service报API与实现捆绑异常排查

异常触发根因 #

核心报错来自NiFi NAR类加载机制的强制约束：控制器服务的API接口与实现必须分离在独立NAR包中，实现类NAR严禁将依赖的服务API类打包进自身包内，违反该规则时NiFi会直接拒绝加载实现类，生成不可用的Ghost组件，后续UI抛出的"不是合法组件类型"错误都是组件被Ghost化后的连带表现。
对照现有配置，有3个配置错误直接触发异常：

• 错误引入nifi-dbcp-service-nar为implementation范围：该依赖会传递引入DBCPService接口类、原生DBCPConnectionPool实现类，全部打进自定义服务NAR包，直接触发"API与实现共同打包"的校验错误
• NiFi依赖版本混乱：同时引入1.12.0版本的nifi-nar-bundles pom和1.16.1版本的其他NiFi组件，会导致类加载时出现重复类、类版本不匹配问题
• 依赖范围错误：NiFi运行环境本身已经提供所有原生控制器服务、核心API类，这类组件不需要打包进自定义NAR，仅需编译时声明依赖即可。

可行修复步骤 #

1. 调整nifi-controllers模块的build.gradle依赖
   删除错误依赖，统一NiFi版本，将所有NiFi原生组件的依赖范围调整为compileOnly，修正后配置如下：

ext {
    nifiVersion = '1.16.1'
}
dependencies {
    // 业务自定义依赖，随组件打包
    implementation group: 'com.oracle.ojdbc', name: 'ojdbc8', version: '19.3.0.0'
    implementation group: 'com.fasterxml', name: 'aalto-xml', version: '1.3.2'

    // NiFi原生依赖，仅编译时使用，不打入最终NAR
    compileOnly group: 'org.apache.nifi', name: 'nifi-api', version: nifiVersion
    compileOnly group: 'org.apache.nifi', name: 'nifi-utils', version: nifiVersion
    compileOnly group: 'org.apache.nifi', name: 'nifi-dbcp-service-api', version: nifiVersion
    compileOnly group: 'org.apache.nifi', name: 'nifi-dbcp-service', version: nifiVersion

    // 测试依赖
    testImplementation group: 'org.apache.nifi', name: 'nifi-mock', version: nifiVersion
    testImplementation group: 'org.slf4j', name: 'slf4j-simple', version: '1.7.36'
    testImplementation group: 'junit', name: 'junit', version: '4.13.2'
}
tasks.named('test') {
    useJUnitPlatform()
}

必须完全移除org.apache.nifi:nifi-nar-bundles:1.12.0、org.apache.nifi:nifi-dbcp-service-nar:1.16.1两个implementation依赖，这是类被错误打包的核心原因。

2. 配置nifi-controllers-nar模块的NAR依赖
   NiFi通过NAR声明建立类加载关联，需要在nifi-controllers-nar模块的build.gradle中声明对原生DBCP服务NAR的依赖，保证运行时可以加载父类DBCPConnectionPool：

dependencies {
    nar project(':nifi-controllers')
    nar "org.apache.nifi:nifi-dbcp-service-nar:${nifiVersion}"
}

3. 打包校验
   构建完成后解压生成的nifi-controllers-nar包，检查META-INF/bundled-dependencies目录下是否存在nifi-dbcp-service-api、nifi-dbcp-service相关jar包，无相关jar包说明依赖配置正确。
4. 部署操作

• 清除NiFi根目录下work目录的旧组件缓存，避免Ghost组件残留影响加载
• 将构建生成的nifi-controllers-nar、nifi-controllers-api-nar放入NiFi的extensions目录
• 重启NiFi后重新创建自定义控制器服务即可正常使用。

内容的提问来源于stack exchange，提问作者maria_so