Apache Zeppelin 源码贡献指南:从开发环境搭建、源码构建到 Pull Request 提交流程
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)
- 将 conf/zeppelin-site.xml.template 复制为
zeppelin-server/src/main/resources/zeppelin-site.xml,按需修改其中的配置项; - 在
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
- 同样先把 conf/zeppelin-site.xml.template 复制为
zeppelin-server/src/main/resources/zeppelin-site.xml并配置; - 在 IDE 中将
ZeppelinServer.java设为主类直接运行/调试。
IDE 方式最适合断点调试服务端逻辑,例如在 InterpreterSettingManager、NotebookRestApi 等类中打断点跟踪请求处理链路。
生成 Thrift 代码
Zeppelin 的部分代码由 Apache Thrift 生成。对大多数改动而言,你无需关心这部分;但如果你修改了任何 Thrift IDL 文件(例如 zeppelin-interpreter/src/main/thrift/RemoteInterpreterService.thrift),就需要重新生成代码,并把更新后的生成文件一并提交进 patch。
重新生成的步骤为:
- 安装 thrift-0.9.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
延伸阅读
- how_to_build.md:更完整的构建要求、profile 清单、代理配置与发行包制作;
- useful_developer_tools.md:子模块选择性构建、单个测试运行、Selenium 测试运行等开发工具技巧;
- how_to_contribute_website.md:面向网站内容贡献者的指南;
- writing_zeppelin_interpreter.md:如果你计划贡献一个新的解释器,这篇文档会很有帮助。