Apache Paimon 源码学习

作者 X老师（DaemonforY），Paimon 2.0 / master 源码，按 CC BY-NC-SA 4.0 发布。配套实验和代码在 GitHub。

Yui和Kai搭建Paimon源码实验室AI 生成配图

学习目标

• 在本机编译通过 Paimon 全部模块（含 Spark 3 / Flink 1.x）。
• 在 IDEA 中正确导入，能直接运行和调试单元测试。
• 知道编译过程中的几个坑及其原因。

1. 环境

项	版本	说明
源码	Apache Paimon master，2.2-SNAPSHOT，commit d15d250cf	本教程的源码行号都基于这个提交
JDK	17（作者使用 Temurin 17.0.19）	官方 README 要求 JDK 8/11，实测 JDK 17 可编译
Maven	≥ 3.6.3（作者使用 3.9.9）
镜像（可选）	本仓库 labs/maven-settings-aliyun.xml	国内直连 Maven Central 可能很慢

推荐的目录布局（源码与本教程仓库放在同一个父目录下）：

workspace/
├── paimon/            ← git clone https://github.com/apache/paimon.git
└── paimon-learning/   ← 本仓库

切到与教程一致的提交：

cd paimon && git checkout d15d250cf

2. 编译命令

编译命令像流水线装配各模块AI 生成配图

cd paimon && mvn -Pspark3,flink1 install -DskipTests -Dmaven.javadoc.skip=true -Dcheckstyle.skip -Dspotless.check.skip=true -Drat.skip=true -Denforcer.skip=true

• 国内网络可加 -s ../paimon-learning/labs/maven-settings-aliyun.xml 使用阿里云镜像。
• 需要的话先指定 JDK：export JAVA_HOME=$(/usr/libexec/java_home -v 17)（macOS），其它系统设置为你的 JDK 17 安装路径。
• 耗时约 10 分钟（依赖已缓存时），共 75 个模块。
• 只改了某个模块时，用 -pl paimon-core -am 只编译该模块及其依赖，速度快很多。
• 跑单个测试：

  cd paimon && mvn -pl paimon-core test -Dtest=UniversalCompactionTest

3. 踩过的坑（重要）

Profile失效像默认轨道被岔路切走AI 生成配图

坑 1：必须显式加 -Pspark3,flink1

根 pom.xml 里 spark3、flink1 两个 profile 是 activeByDefault。但 Maven 的规则是：同一个 pom 里只要有任何其它 profile 被激活，activeByDefault 的 profile 就全部失效。JDK ≥ 9 时 javadoc-jdk9+ profile 会自动激活，于是 spark3/flink1 被关掉：

• paimon-spark3-common、Flink 1.16~1.20 模块不在 reactor 中，reactor 只有 65 个模块；
• 依赖它们的模块会去 apache.snapshots 远程仓库拉当天 nightly SNAPSHOT jar，与本地最新源码不一致，报 object PaimonMetricsSource is not a member of package ... 之类的编译错误。

验证方法：

cd paimon && mvn -N help:active-profiles

坑 2：不要并发跑多个 Maven 构建

-T 1C 并行 + 残留的构建进程会争抢本地仓库锁，报 Could not acquire lock(s)。遇到时先 pgrep -fl plexus-classworlds 检查并清掉残留进程。

坑 3：用 -rf 续跑要小心

-rf :module 会跳过排在它前面的模块。如果前面某个模块其实没有 install 到本地仓库，就会从远程拉旧 jar。拿不准时去掉 -rf 全量跑（不加 clean 时已编译模块是增量的，并不慢）。

4. IDEA 导入

1. File → Open 选择 paimon/pom.xml，以 Maven 项目打开。
2. Maven 面板 → Profiles 勾选 spark3、flink1（原因同坑 1，否则 Spark/Flink 代码大片报红）。
3. Settings → Build Tools → Maven → User settings file 可选：指向本仓库的 labs/maven-settings-aliyun.xml（国内网络）。
4. Project SDK 选 JDK 17；语言级别保持 8（项目要求不能使用 JDK 8 以上语法）。
5. 把 paimon-common/target/generated-sources/antlr4 标记为 Sources Root（官方 README 要求）。
6. 安装 Scala 插件（paimon-spark 大量 Scala 代码）。

5. 源码目录速览

模块	内容
paimon-api	对外 API：Snapshot、CoreOptions、REST API、类型系统
paimon-common	通用工具：数据结构（BinaryRow）、FileIO、谓词、文件索引
paimon-core	核心引擎：LSM、合并、提交、扫描、读写、Catalog
paimon-format	Parquet / ORC / Avro 等格式读写
paimon-flink	Flink 连接器（Source/Sink/Action/CDC）
paimon-spark	Spark 连接器（多版本适配、DML 命令、存储过程）
paimon-hive	Hive Catalog 与 Hive 连接器
paimon-filesystems	OSS/S3/GCS/Azure 等文件系统实现
paimon-python	pypaimon：Python 读写与 REST 客户端
docs	官方文档源码、REST OpenAPI 规范

动手实验

• [ ] 跑 help:active-profiles，确认不加 -P 时只有 javadoc-jdk9+ 被激活。
• [ ] 在 IDEA 里直接运行 paimon-core 下的 UniversalCompactionTest，确认能跑通。
• [ ] 用 -pl paimon-core -am 编译一次，体会增量编译速度。

自测题

1. 为什么在 JDK 17 下不加 -Pspark3,flink1 会编译失败？
2. Could not acquire lock(s) 通常是什么原因？
3. -rf 续跑可能导致什么隐患？