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");