Apache SeaTunnel 编码指南模块地图、18 条高质量 Pull Request 规范与工具化强制机制【免费下载链接】seatunnelSeaTunnel is a multimodal, high-performance, distributed, massive data integration tool.项目地址: https://gitcode.com/GitHub_Trending/se/seatunnelApache SeaTunnel 的 编码指南 是社区维护代码库一致性的核心文档它既给出了各 Maven 模块的职责划分也以 18 条最佳实践规定了从命名、日志、异常处理、License 头到本地构建验证的完整提交流程。读完本文你将掌握 SeaTunnel 的模块结构地图能按照社区规范编写符合 Spotless 风格检查的代码并学会用./mvnw命令链、预提交钩子和 e2e 测试框架完成提交前全链路自检。SeaTunnel 的模块结构地图指南首先通过一张模块表帮助开发者定位代码位置这也是理解后续按模块组织 Issue/PR的前提模块职责seatunnel-apiSeaTunnel Connector V2 API 模块seatunnel-commonSeaTunnel 公共模块seatunnel-connectors-v2SeaTunnel Connector V2 模块当前社区重点投入的方向seatunnel-core/seatunnel-spark-starter基于 Spark 引擎的 Connector V2 核心启动器seatunnel-core/seatunnel-flink-starter基于 Flink 引擎的 Connector V2 核心启动器seatunnel-core/seatunnel-starter基于 SeaTunnel 引擎的 Connector V2 核心启动器seatunnel-e2e端到端测试模块seatunnel-examples本地示例模块可用于单元测试和集成测试seatunnel-engineSeaTunnel 社区自研的计算引擎专注于数据同步场景seatunnel-formats数据格式模块提供数据序列化/反序列化能力seatunnel-plugin-discovery插件发现模块负责从 classpath 加载 SPI 插件seatunnel-transforms-v2Transform V2 模块社区重点投入的方向seatunnel-translation翻译适配模块用于适配 Connector V2 与 Spark、Flink 等计算引擎从源码结构看根 pom.xml 的modules声明与上表一一对应并包含文档未逐一展开的补充模块seatunnel-config配置解析含 shade 与 SQL 子模块、seatunnel-trace链路追踪、seatunnel-edge-agent边缘代理、seatunnel-ci-toolsCI 工具等此外seatunnel-dist发行包组装与seatunnel-benchmarks性能基准分别挂在release和benchmarkprofile 下按需激活。开发前确认改动落在正确模块是后续 Issue/PR 命名规范第 3 条的基础。Issue 与 Pull Request 的命名规范SeaTunnel 使用 issue 跟踪缺陷与改进使用 GitHub Pull Request 管理代码评审与合并因此清晰的标题能显著降低沟通成本。社区推荐的标题格式为[purpose] [module name] [sub-module name] Description各字段的取值约定如下PR purpose包括Hotfix、Feature、Improve、Docs、WIP。注意若 purpose 为WIP必须使用 GitHub 的 draft pull requestIssue purpose包括Feature、Bug、Docs、DiscussModule namePR 或 issue 涉及的模块名例如Core、Connector-V2、Connector-V1等Sub-module name涉及的子模块名例如File、Redis、Hbase等Description简洁清晰地概括目标让人一眼看懂 PR 的核心意图。例如一个修改 MongoDB 连接器写入缓冲逻辑的 PR标题可以写作[Improve] [Connector-V2] [Mongodb] Reduce buffer flush memory usage。Java 代码风格规范Lombok、封装与基本类型指南对日常编码风格给出三条硬性约定1. 优先使用 Lombok 注解减少样板代码。使用Data、Getter、Setter、NonNull等注解创建实体类。这一约定在构建层面有明确支撑根 pom.xml 统一管理lombok依赖版本1.18.36scope 为provided并在 maven-compiler-plugin 的annotationProcessorPaths中注册 Lombok 注解处理器任何子模块无需自行声明版本。2. 日志统一使用Slf4j。需要输出日志的类不要手写Logger字段优先使用 Lombok 的Slf4j注解。这在 e2e 测试代码中是标准写法例如 MongodbIT.java 的类声明就标注了Slf4j。3. 字段权限与可变性、参数类型优先基本类型。类属性默认private可变性设为final特殊场景才允许放宽属性与方法参数优先使用基本类型int、boolean、double、float等不推荐包装类型Integer、Boolean、Double等特殊情况可合理变更。4. 简化控制流。代码中存在多个if判断时尝试把 if-else-if 链拆分为多个独立的if简化流程、降低嵌套深度。5. Sink 连接器的序列化约束。开发 Sink 连接器时要注意 Sink 会被序列化若某些属性不可序列化应将其封装进类并使用单例模式。这条约束源于 SeaTunnel 引擎与 Spark/Flink 翻译层需要在进程间传递 Sink 实例不可序列化字段会直接导致任务提交失败。6. 消除重复代码。同一段代码若被多次使用不应复制多份而应提炼为公共代码段供其他模块复用——这与seatunnel-common、connector-common这类公共模块的存在目的一致。异常处理与 License 头异常要带提示语且范围要小。抛出异常时附带 hint message避免过宽的异常范围——过宽的异常会催生更复杂、更易藏安全漏洞的错误处理代码。指南给出的示例连接器读取数据遇到IOException时应收敛为具体的业务异常try { // read logic } catch (IOException e) { throw SeaTunnelORCFormatException(This orc file is corrupted, please check it, e); }每个新增文件必须包含 Apache License 头。Apache 项目有严格的许可证要求提交 PR 前需检查每个新文件都带有如下头注释以 Java 文件为例/* * Licensed to the Apache Software Foundation (ASF) under one or more * contributor license agreements. See the NOTICE file distributed with * this work for additional information regarding copyright ownership. * The ASF licenses this file to You under the Apache License, Version 2.0 * (the License); you may not use this file except in compliance with * the License. You may obtain a copy of the License at * * http://www.apache.org/licenses/LICENSE-2.0 * * Unless required by applicable law or agreed to in writing, software * distributed under the License is distributed on an AS IS BASIS, * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. * See the License for the specific language governing permissions and * limitations under the License. */仓库中任何新文件都可以照此对照例如 MongodbIT.java 开头的头注释即为标准样式。另外 seatunnel-ci-tools 模块专门承载 CI 侧的检查逻辑可进一步查看其在持续集成中如何校验文件合规性。Spotless代码风格与格式的强制机制指南第 7 条指出 SeaTunnel 使用Spotless做代码风格与格式检查可用一条命令自动修复./mvnw spotless:apply这条命令背后有完整的构建配置支撑。根 pom.xml 中声明了spotless-maven-plugin版本 2.29.0关键配置包括Java 格式采用googleJavaFormat1.7 的AOSP风格并执行removeUnusedImports移除无用 import与formatAnnotations格式化注解import 排序固定顺序为org.apache.seatunnel.shade, org.apache.seatunnel, org.apache, org, javax, java, 静态导入正则规则replaceRegex禁止通配符导入import xxx.*、禁止 PowerMock、禁止 JUnit 4 导入只允许 JUnit Jupiter、并将 Guava / Jetty / Hikari / Janino / Commons Lang3 的导入自动改写为org.apache.seatunnel.shade下的 shade 包路径——这正是 SeaTunnel 依赖隔离策略在源码层面的体现业务代码不得直接引用原始三方包必须使用 shade 后的包名POM 排序sortPom统一pom.xml的缩进4 空格与排序规则执行绑定spotless-checkgoal 绑定在validate阶段意味着每次构建都会先跑风格检查可通过-Dskip.spotlesstrue跳过属性默认值为false。此外仓库提供了预提交钩子脚本 pre-commit.sh先执行./mvnw spotless:check检查通过则放行失败则自动执行./mvnw spotless:apply修复后以非零码退出提醒开发者提交被修复的文件。将其安装为 git 的 pre-commit hook 后格式问题就能在本地提交前被拦截而不是留到 CI。本地构建验证编译与打包指南第 8 条要求提交 PR 前必须确认加入你的代码后项目能正常编译官方给出的命令为# 多线程编译 ./mvnw -T 1C clean package# 单线程编译 ./mvnw clean package注意事项仓库自带 Maven Wrappermvnw无需本地预装 Maven版本与 CI 保持一致-T 1C表示每个 CPU 核心一个编译线程适合多核机器加速全量构建该命令会触发validate阶段的 Spotless check因此**能编译通过本身就隐含了格式检查通过**seatunnel-dist只会在 release 相关 profile 下参与构建日常开发无需关心发行包组装。本地自测利用 seatunnel-examples 与 e2e 测试指南第 9 条建议在提交前在本地完成完整的单元与集成测试最佳实践是利用seatunnel-examples模块的自测能力验证多引擎运行正确且结果无误。当前仓库中 seatunnel-examples 包含seatunnel-engine-examplesSeaTunnel 引擎示例seatunnel-flink-examplesFlink 引擎示例seatunnel-spark-connector-v2-exampleSpark 引擎示例seatunnel-edge-agent-examples边缘代理示例。这些示例与 e2e 模块共享作业配置文件 容器化执行的验证思路连接器开发完成后用示例/示例配置在对应引擎上跑一遍确认多引擎翻译层seatunnel-translation没有行为差异。连接器类型 PR 必须补充 e2e 测试。指南第 11 条对 e2e 测试提出三点要求并以 MongoDB 连接器为例e2e 测试应覆盖全量数据类型尽量少初始化 Docker 镜像把 source 与 sink 的测试用例写在同一个测试类中减少资源浪费利用异步能力保证测试稳定性。指南推荐的范例是 MongoDB 的 e2e 测试在当前仓库中对应 MongodbIT.java可以从源码结构看到上述要求的具体落地测试类继承AbstractMongodbITsource 与 sink 用例集中在同一类中共用一个 MongoDB 容器使用TestTemplateTestContainer参数化执行同一份用例可在不同引擎容器中运行用DisabledOnContainer(type {EngineType.FLINK, EngineType.SPARK}, ...)精确标注引擎差异如MongodbIT.java第 85-88 行禁用 FLINK/SPARK 的 null 值写测试而非笼统跳过覆盖全数据类型写入int/long/string 组合的SeaTunnelRow、多表写入、SaveModeDROP/APPEND/ERROR、事务与 upsert 等完整场景。编写新的连接器 e2e 测试时可以直接参考同目录下其他-e2e子模块如 JDBC、Kafka的目录组织方式src/test/java下放 IT 类src/test/resources下放.conf作业配置由container.executeJob(/xxx.conf)驱动执行并断言退出码。单一职责、文档同步与核心模块改动流程指南最后几条是流程性约束违反任何一条都可能导致 PR 被直接关闭单一职责第 16 条。PR 不允许夹带与功能无关的代码。若改动涉及多个主题先在各自的分支上分别处理再分别提交 PR否则社区会主动关闭该 PR。为自己的 PR 负责第 17 条。若 PR 包含新功能或修改了旧功能必须补充测试用例或 e2e 测试证明 PR 的合理性与功能完整性。文档同步第 10 条。功能需要更新文档时务必同时更新文档。SeaTunnel 的文档集中在docs/目录英文docs/en、中文docs/zh连接器文档按connectors/source与connectors/sink分目录组织改连接器时对应更新docs/zh/connectors/...或docs/en/connectors/...下的说明。核心模块改动必须先讨论第 18 条。若你认为社区现有代码尤其是core与api模块不合理、需要更新或修改第一动作是发起discuss issue或邮件与社区讨论待社区同意后再提交 PR未经讨论直接提交针对核心模块的 PR 会被视为无效工作并被关闭。提交前检查清单综合上述规范提交一个高质量 PR 前可按以下清单逐项确认标题符合[purpose] [module] [sub-module] Description格式WIP 状态已置为 draft PR新文件均带 Apache License 头实体类使用 Lombok 注解日志使用Slf4j字段private final参数优先基本类型异常带提示语、范围收敛重复代码已抽为公共模块Sink 中不可序列化属性已封装为单例./mvnw spotless:apply已执行且./mvnw spotless:check通过建议安装 pre-commit.sh 钩子./mvnw -T 1C clean package全量编译通过功能已用seatunnel-examples在目标引擎上自测连接器 PR 已补充覆盖全数据类型的 e2e 测试source/sink 同写一类、控制 Docker 镜像数量相关文档已同步更新核心模块改动已有社区讨论结论。以上所有约束均可在当前仓库中直接核验模块边界看 根 pom.xml风格规则看 Spotless 插件配置测试范式看 seatunnel-e2e 下各连接器的 IT 类。将这套规范 工具强制的机制内化后提交的 PR 在 CI 与人工评审中的通过率会显著提高。【免费下载链接】seatunnelSeaTunnel is a multimodal, high-performance, distributed, massive data integration tool.项目地址: https://gitcode.com/GitHub_Trending/se/seatunnel创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考