Apache Zeppelin 源码贡献指南:从开发环境搭建、源码构建到 Pull Request 提交流程

原创2026-10-08 23:35:272,643 阅读
文章标签:后端前端大数据数据分析

Apache Zeppelin 源码贡献指南:从开发环境搭建、源码构建到 Pull Request 提交流程

Apache Zeppelin 是一个基于 Web 的笔记本(Notebook)项目,支持以 SQL、Scala 等语言驱动的交互式数据分析和协作文档。本文以仓库中的官方贡献文档 how_to_contribute_code.md 为主体,完整讲解代码贡献者的全流程:开发环境搭建、获取源码、Maven 构建、三种开发模式运行 Zeppelin 服务端、Thrift 代码再生成、Selenium 集成测试,以及提交 Pull Request 前的注意事项。读完本文,你将掌握一套可复现的 Zeppelin 源码开发与测试实操方案,并了解其背后的构建结构与源码实现。

版权与贡献协议:Apache 2.0 License

Apache Zeppelin 是 Apache 2.0 License 软件。任何对 Zeppelin 的贡献——包括源码、文档、图片、网站内容——都意味着你同意以 Apache 2.0 许可证授权你的全部贡献。仓库根目录的 LICENSE 与 NOTICE 文件是理解这一协议的基础。

这一约束对贡献者意味着两件事:

  • 你在提交前应确认自己对所贡献代码拥有合法授权;
  • 项目中自动生成的代码(如 Thrift 生成的 Java 文件)会统一附带 Apache License 头,这也是后文"生成 Thrift 代码"环节会看到许可证头被自动拼接的原因。

开发环境准备

SCM:Git

Zeppelin 使用 Git 作为版本控制(SCM)系统,因此开发机上需要安装可用的 git 客户端。后续的源码获取、分支管理和 Pull Request 提交流程都依赖它。

IDE

Zeppelin 对 IDE 没有强制要求,你可以自由选择任意 IDE 或命令行编辑器。源码主要以 Java(服务端与解释器)和 JavaScript/AngularJS(前端 zeppelin-web)编写,此外还有少量 Scala 代码。

构建工具

构建代码前需要安装:

  • Oracle Java 7(JDK 1.7)
  • Apache Maven(3.1.x 或更高版本)

参考同仓库的 how_to_build.md 文档,各依赖要求如下:

名称 要求
Git 任意版本
Maven 3.1.x 或更高
JDK 1.7

若在 Ubuntu 等环境从零安装,可参照 how_to_build.md 中的示例命令(sudo apt-get install git openjdk-7-jdk ...)。Maven 构建 Zeppelin 这类大型多模块项目通常需要更多内存,文档建议配置:

export MAVEN_OPTS="-Xmx2g -XX:MaxPermSize=1024m"

并用 mvn -version、node --version 验证 Maven 与 Node 环境是否就绪(前端构建依赖 Node/npm)。

获取源码

首先需要获取 Zeppelin 源码。官方源码位置是 Apache 的 Git 仓库;在本镜像环境中,可以直接克隆当前仓库:

git clone https://gitcode.com/gh_mirrors/zeppelin2/zeppelin.git zeppelin

如果你希望基于特定分支开发,例如 branch-0.5.6:

git clone -b branch-0.5.6 git://git.apache.org/zeppelin.git zeppelin

说明:以当前仓库为例,其版本为 0.8.2-SNAPSHOT(参见 zeppelin-integration/pom.xml 中的 <version> 与父 pom 声明),分支示例仅用于演示按分支克隆的语法。

Apache Zeppelin 遵循 Fork & Pull 的源码控制工作流:如果你不仅要构建 Zeppelin,还希望修改代码并回馈上游,需要 fork 一份自己的仓库副本,在副本上修改后向主仓库发起 Pull Request。发起 PR 之前,请先查阅项目贡献指南(Contributing Guidelines),确保提交符合社区规范。

构建源码

在仓库根目录执行 Maven 构建:

mvn install

跳过测试以加速构建:

mvn install -DskipTests

指定 Spark / Hadoop 版本构建:

mvn install -Dspark.version=x.x.x -Dhadoop.version=x.x.x

更丰富的构建选项

同仓库的 how_to_build.md 提供了更完整的构建参考,可作为本文的延伸:

  • Spark profile:-Pspark-2.1、-Pspark-2.0、-Pspark-1.6、-Pspark-1.5、-Pspark-1.4 等,主版本用 profile 指定,次版本用 -Dspark.version=x.x.x 微调;
  • Hadoop profile:-Phadoop-0.23、-Phadoop-1、-Phadoop-2.2、-Phadoop-2.3、-Phadoop-2.4、-Phadoop-2.6、-Phadoop-2.7,配合 -Dhadoop.version=x.x.x;
  • Scala 版本:默认 Scala 2.10,可用 -Pscala-2.10 / -Pscala-2.11 切换,切换前通常先运行仓库提供的脚本 dev/change_scala_version.sh:
    ./dev/change_scala_version.sh 2.11
    
  • R 支持:-Pr(集成 SparkR);
  • 第三方仓库:-Pvendor-repo(如 Cloudera);MapR 发行版可用 -Pmapr3、-Pmapr40、-Pmapr41、-Pmapr50、-Pmapr51;
  • 示例模块:-Pexamples 构建 zeppelin-examples 下的示例。

组合示例:

# 以 spark-2.0 / hadoop-2.4 / scala-2.11 构建全部解释器
./dev/change_scala_version.sh 2.11
mvn clean package -DskipTests -Pspark-2.0 -Phadoop-2.4 -Pr -Pscala-2.11

打包发布版

如需生成最终发行包(含压缩归档),运行:

mvn clean package -Pbuild-distr

归档文件生成在 zeppelin-distribution/target 目录下。若处于代理环境,请按 how_to_build.md 的 "Proxy setting" 一节同时配置 Maven(~/.m2/settings.xml)、npm 与 git。

按需构建子模块

大型改动往往只需构建部分模块。仓库文档 useful_developer_tools.md 给出了按模块构建的实用命令,例如:

# 只构建 zeppelin-web
mvn clean -pl 'zeppelin-web' package -DskipTests;

# 构建 zeppelin-server 及其依赖
mvn clean package -pl 'spark,spark-dependencies,python,markdown,zeppelin-server' --am -DskipTests

--am(also make)会连带构建依赖模块,适合在只改动了特定模块时快速验证。

开发模式运行 Zeppelin 服务端

贡献代码后需要本地运行验证,官方文档提供了三种方式。

方式一:命令行(mvn exec:java)

  1. 将 conf/zeppelin-site.xml.template 复制为 zeppelin-server/src/main/resources/zeppelin-site.xml,按需修改其中的配置项;
  2. 在 zeppelin-server 模块目录下执行:
cd zeppelin-server
HADOOP_HOME=YOUR_HADOOP_HOME JAVA_HOME=YOUR_JAVA_HOME \
mvn exec:java -Dexec.mainClass="org.apache.zeppelin.server.ZeppelinServer" -Dexec.args=""

这里指定的主类 org.apache.zeppelin.server.ZeppelinServer 正是服务端的入口类,源码位于 ZeppelinServer.java。从源码可以看到,它继承自 JAX-RS 的 Application,构造时通过 ZeppelinConfiguration.create() 加载配置,并依次组装解释器工厂(InterpreterFactory)、Notebook(Notebook)、搜索服务(LuceneSearch)、凭据管理(Credentials)等核心组件,最终把 Jetty Web 服务与 REST API、WebSocket(NotebookServer)绑定在一起。理解这一主类有助于你快速定位服务启动相关的改动点。

方式二:守护进程脚本(Daemon Script)

注意:请先在 Zeppelin 根目录执行一次

mvn clean install -DskipTests

否则服务端构建会因本地仓库缺少依赖而失败。

然后使用守护脚本启动(本仓库中的脚本文件名为 bin/zeppelin-daemon.sh):

bin/zeppelin-daemon.sh start

启动成功后访问 http://localhost:8080 即可看到 Zeppelin 界面。

方式三:IDE

  1. 同样先把 conf/zeppelin-site.xml.template 复制为 zeppelin-server/src/main/resources/zeppelin-site.xml 并配置;
  2. 在 IDE 中将 ZeppelinServer.java 设为主类直接运行/调试。

IDE 方式最适合断点调试服务端逻辑,例如在 InterpreterSettingManager、NotebookRestApi 等类中打断点跟踪请求处理链路。

生成 Thrift 代码

Zeppelin 的部分代码由 Apache Thrift 生成。对大多数改动而言,你无需关心这部分;但如果你修改了任何 Thrift IDL 文件(例如 zeppelin-interpreter/src/main/thrift/RemoteInterpreterService.thrift),就需要重新生成代码,并把更新后的生成文件一并提交进 patch。

重新生成的步骤为:

  1. 安装 thrift-0.9.2(版本需匹配项目约定);
  2. 进入 thrift 目录并执行生成脚本:
cd <zeppelin_home>/zeppelin-interpreter/src/main/thrift
./genthrift.sh

genthrift.sh 的实际行为可以从脚本源码直接看到:

  • 删除旧的 gen-java 临时目录以及 ../java/org/apache/zeppelin/interpreter/thrift 下已生成的代码;
  • 执行 thrift --gen java RemoteInterpreterService.thrift 生成 Java 代码;
  • 遍历生成出的每个文件,把 java_license_header.txt 中的 Apache License 头拼接到文件头部——这正是前文"贡献即同意 Apache 2.0 授权"在工程上的具体落地;
  • 最后把生成结果移动到 zeppelin-interpreter/src/main/java/org/apache/zeppelin/interpreter/thrift 并清理临时目录。

RemoteInterpreterService 定义了解释器进程与服务端之间的远程调用协议,是理解 Zeppelin 解释器隔离机制的关键入口。

运行 Selenium 集成测试

Zeppelin 提供了一套基于 Selenium 的集成测试,用于在真实浏览器中验证 Notebook 前端交互。本仓库中这些测试位于 zeppelin-integration/src/test/java/org/apache/zeppelin/integration 目录。

运行前需先构建并启动 Zeppelin,确保服务运行在 8080 端口,然后执行:

TEST_SELENIUM=true mvn test -Dtest=[TEST_NAME] -DfailIfNoTests=false \
-pl 'zeppelin-interpreter,zeppelin-zengine,zeppelin-server'

例如运行段落操作集成测试 ParagraphActionsIT.java:

TEST_SELENIUM=true mvn test -Dtest=ParagraphActionsIT -DfailIfNoTests=false \
-pl 'zeppelin-interpreter,zeppelin-zengine,zeppelin-server'

以 ParagraphActionsIT.java 的 testCreateNewButton 为例,可以看到它通过 Selenium WebDriver 驱动浏览器:先 createNewNote() 新建笔记,再用 XPath 定位段落上的设置图标(icon-settings)并点击 "Insert New",随后校验段落数量是否从 1 变为 2,最后通过弹窗(modal)删除段落并断言结果——这套用例完整覆盖了段落创建、插入、删除的前端交互链路。

关于测试环境,你需要在开发机安装 Firefox 浏览器。CI 服务器使用 Firefox 31.0 运行 Selenium 测试,建议安装相同版本并禁用自动更新以保持一致。集成测试模块的依赖与生命周期可以在 zeppelin-integration/pom.xml 中确认:它引入 selenium-java(版本 3.8.1)、JUnit,并通过 maven-failsafe-plugin 绑定 integration-test/verify 阶段;同时用 maven-antrun-plugin 在 pre-integration-test 阶段自动执行 zeppelin-daemon.sh start、在 post-integration-test 阶段自动 stop,从而端到端管理测试用的 Zeppelin 进程。

如果希望让 Maven 自动完成"启动服务 → 跑测试 → 停止服务"的闭环,也可以直接使用 how_to_build.md 中记录的端到端验收命令:

# 假设 zeppelin-server 已运行在 localhost:8080(可用 -Durl=.. 覆盖)
mvn verify

# 或使用打包好的发行版,由 Maven 自行启停服务
mvn verify -P using-packaged-distr

从哪里开始

如果你是第一次参与 Zeppelin 开发,可以在 Apache JIRA 的 ZEPPELIN 项目中按 beginner / newbie 标签筛选入门级 issue,从中认领第一个任务。这类任务通常改动范围小、上下文清晰,适合熟悉构建与提交流程。

保持参与

贡献者应订阅 Zeppelin 邮件列表,以便跟进讨论:

  • dev@zeppelin.apache.org:面向希望为 Zeppelin 贡献代码的人。订阅邮件发送到 dev-subscribe@zeppelin.apache.org,退订发送到 dev-unsubscribe@zeppelin.apache.org,历史讨论可在邮件列表归档中检索。

遇到任何问题,请在 Apache JIRA 的 ZEPPELIN 项目中创建 ticket 跟踪。

提交前的工程化建议

  • 代码风格:仓库根目录提供了 checkstyle.xml 与 scalastyle.xml 风格配置,提交前请确保代码符合规范;
  • PR 辅助脚本:仓库 dev 目录提供了社区常用的开发辅助脚本,例如 test_zeppelin_pr.py(测试某个 PR 的代码)、merge_zeppelin_pr.py(合并 PR),可用于本地预检或了解社区的 PR 处理流程;
  • 单独运行某个测试类:配合 -pl 与 -Dtest 参数即可精确运行单个测试,例如:
    mvn test -pl 'zeppelin-server' --am -DfailIfNoTests=false -Dtest=HeliumBundleFactoryTest
    

延伸阅读

登录后查看全文
zeppelin