Flink Modules 把自定义函数“伪装成内置函数”，以及 Core/Hive/自定义模块的加载与解析顺序

1. Modules 能解决什么问题

你会遇到这些需求时，Module 非常合适

• 你希望用户在 SQL 里直接用geo_distance(...)、ip_to_region(...)这种函数，像用 Flink 内置函数一样
• 你希望把 Hive 自带的一堆 UDF/UDTF 当成 Flink 内置函数用（HiveModule）
• 你想做“统一函数能力包”：比如公司内部的一套数据治理函数、脱敏函数、维表补全函数等，一次性加载即可用
• 你甚至希望影响临时表 connector 的创建（Module 也可以提供 source/sink factory，会影响默认 SPI 发现）

2. Module 的核心特性

2.1 没有 namespace

Module 提供的对象被视为Flink 的系统（built-in）对象，因此没有 catalog/database 的 namespace。
也就是说，它们更像core里的SUBSTRING、CAST一类“全局可见”的东西。

2.2 生命周期：load / use(enable) / disable / unload

• LOAD：把模块加载到 TableEnvironment（加载后默认启用）
• USE MODULES：决定哪些模块启用，并且决定解析顺序
• disable：不在USE MODULES ...里出现的已加载模块会被置为未启用（但仍然“加载着”）
• UNLOAD：从 TableEnvironment 中移除（卸载后就不能再 use 了，除非重新 load）

2.3 解析顺序（Resolution Order）决定“同名函数用哪个”

当多个启用模块里出现同名函数时，Flink 按模块顺序解析：

• 两个模块都启用：按USE MODULES的顺序，谁在前用谁
• 只启用一个：只会解析到启用的那个
• 两个都禁用：函数无法解析

这对“覆盖/替换”内置或第三方函数非常关键（比如你想让 hive 的某个函数优先于 core 或你自定义模块的实现）。

3. Module 类型：Core / Hive / 自定义

3.1 CoreModule

• Flink 的系统内置函数都在core
• 默认加载并启用
• 强烈不建议禁用 core（除非你真的知道自己在做什么）

3.2 HiveModule

• 把 Hive 内置函数提供给 Flink SQL / Table API 使用
• 需要按 Flink Hive 文档完成依赖与版本配置
• 很常见的用法：让 Flink SQL 更接近 Hive SQL 生态

3.3 自定义 Module

• 你可以实现Module接口来自定义模块

• 如果你希望在 SQL CLI 用LOAD MODULE xxx WITH (...)这种方式发现并加载，还需要实现ModuleFactory

  • ModuleFactory负责声明配置项，并根据 properties 实例化 module
  • 本质是：用 properties 让 discovery service 找到匹配的 factory，再创建 module

4. 用 SQL 管理 Modules：SHOW / LOAD / USE / UNLOAD

下面这套操作是理解模块最直接的方式（同时适用于 Table API 的executeSql以及 SQL Client）。

4.1 初始状态：只有 core

SHOWMODULES;SHOWFULLMODULES;

• SHOW MODULES：只展示“启用中的模块”
• SHOW FULL MODULES：展示“所有已加载模块 + 是否 used（启用）”

4.2 加载 hive 模块

LOADMODULE hiveWITH('hive-version'='...');

加载后默认启用，因此你会在SHOW MODULES里同时看到core和hive。

4.3 改变解析优先级（非常关键）

USEMODULES hive,core;

这意味着：如果hive和core都提供了同名函数，优先使用 hive 的版本。

4.4 禁用 core（演示用，不建议）

USEMODULES hive;

此时：

• SHOW MODULES只会显示启用的hive
• SHOW FULL MODULES会显示core used=false（core 还在，只是禁用了）

4.5 卸载 hive

UNLOAD MODULE hive;

卸载后 hive 不再可用，且不能再USE MODULES hive（除非重新LOAD）。

补充：SQL 中 module 名是 discovery 用的简单标识符，大小写敏感。

5. 用 Java API 管理 Modules（更适合平台/应用内嵌）

同样的生命周期在 Java 里对应：

• listModules()：启用的模块
• listFullModules()：已加载模块 + used
• loadModule(name, moduleInstance)
• useModules("hive", "core")
• unloadModule("hive")

典型流程：

tableEnv.listModules();tableEnv.listFullModules();tableEnv.loadModule("hive",newHiveModule());tableEnv.useModules("hive","core");tableEnv.useModules("hive");// 禁用 core（演示，不建议）tableEnv.unloadModule("hive");

6. 什么时候该用 Module，什么时候不该用

适合用 Module 的场景

• 你要做“公司级函数包”，让所有 SQL 作业像用内置函数一样调用
• 你需要和 Hive 生态函数对齐
• 你想用模块顺序解决“同名函数冲突”，并可控地覆盖默认实现

不太适合的场景

• 只给某一个作业加一两个函数：直接注册临时函数/系统函数更轻量
• 你希望函数有 namespace（按库隔离）：那更像 Catalog 的职责，而不是 Module

如果你准备把这块写成 CSDN 博客，我可以继续帮你把这一节扩成更“落地”的结构：

• “Module vs Catalog Function vs Temporary Function” 三者边界与选型
• “自定义 Module + ModuleFactory” 的最小可运行骨架（包含 properties 配置项）
• “函数同名冲突” 的真实案例（比如 hive 与 core 某些函数差异）以及排查思路