Apache SeaTunnel 开发规范与 AI Agent 工程实践指南从构建验证到提交协作的完整约定【免费下载链接】seatunnelSeaTunnel is a multimodal, high-performance, distributed, massive data integration tool.项目地址: https://gitcode.com/GitHub_Trending/se/seatunnelApache SeaTunnel 在仓库根目录维护了一份面向 LLM / AI Agent 的上下文指南CLAUDE.md与AGENTS.md内容一致它把成熟 Apache 项目的工程纪律沉淀为可执行的硬性约定提变更前必须本地验证、提交信息必须遵循[Type][Module]格式、配置项必须用Option定义、不兼容变更必须登记备案。本文以此文档为骨架结合仓库源码seatunnel-api、seatunnel-engine、seatunnel-e2e、bin/install-plugin.sh等逐条展开解读帮助你无论是人还是 Agent在 SeaTunnel 代码库上写出安全、一致、可验证的代码与提交。这份文档是什么为 LLM/Agent 准备的代码库上下文指南CLAUDE.md的定位非常明确帮助 AI 助手LLM / Agent对 Apache SeaTunnel 代码库做出安全safe、一致consistent、可验证verifiable的修改。它并不是泛泛的贡献指南而是镜像了成熟 Apache 项目的工程实践并逐一适配到 SeaTunnel 特有的构建、测试、架构和文档约定上——例如 Zeta 引擎的三层角色、Option配置体系、seatunnel-e2e的 Testcontainers 测试范式等。因此理解这份文档的正确方式是把它当作进入 SeaTunnel 代码库的协作契约文档中的每一条规则几乎都能在仓库中找到对应的实现或配套脚本作为证据。铁律一提变更前必须本地验证文档开篇即以 CRITICAL: Validate Before Proposing Changes 强调Agent 必须在本地运行验证命令之后再建议或提交变更否则 PR 大概率会被拒绝。# 格式化代码强制 ./mvnw spotless:apply # 快速验证强制 ./mvnw -q -DskipTests verify # 单元测试强烈建议 ./mvnw test三条命令分工明确spotless:apply是 SeaTunnel 的代码格式化入口统一使用Google Java FormatAOSP 风格。仓库中tools/spotless_check/pre-commit.sh的存在进一步印证格式检查被前置到提交阶段避免不合规代码流入主干。-q -DskipTests verify用于快速验证编译与打包链路是否畅通跳过测试以节省时间是改完先保证能编译的底线检查。mvnw test运行单元测试验证行为正确性属于强烈推荐项。Git 提交信息约定SeaTunnel 采用严格的提交信息格式来维持干净、可检索的历史记录[Type][Module] DescriptionType类型Type含义Feature新功能FixBug 修复Improve对现有行为的改进Docs仅文档变更Test测试用例或测试框架变更Chore构建、依赖或维护类任务Module模块模块名与仓库顶层目录一一对应例如Module对应模块Connector-V2seatunnel-connectors-v2Zetaseatunnel-engineZeta 引擎Coreseatunnel-coreAPIseatunnel-apiTransform-V2seatunnel-transforms-v2Formatseatunnel-formatsTranslationseatunnel-translationE2Eseatunnel-e2e示例[Fix][Connector-V2] Fix MySQL source split enumeration bug [Fix][Zeta] Fix checkpoint timeout under heavy backpressure [Feature][Transform-V2] Add LLM transform plugin [Improve][Core] Optimize jar package loading speed [Docs] Update quick start guide这种格式让git log --grep可以快速按模块或类型过滤历史例如查找所有 Zeta 引擎的修复只需要检索\[Fix\]\[Zeta\]。仓库结构速览文档给出了模块级的目录导航与实际仓库布局一一对应seatunnel/ ├── seatunnel-api/ # 核心 API 定义 ├── seatunnel-connectors-v2/ # Source Sink 连接器主要贡献区域 ├── seatunnel-transforms-v2/ # Transform 插件包括 LLM ├── seatunnel-engine/ # Zeta 引擎 Web UI ├── seatunnel-core/ # 作业提交与 CLI 入口 ├── seatunnel-translation/ # Flink Spark 适配层 ├── seatunnel-formats/ # 数据格式JSON、Avro 等 ├── seatunnel-e2e/ # 端到端集成测试 ├── docs/ # 文档en zh └── config/ # 默认配置对照真实仓库可以看到seatunnel-connectors-v2/下按连接器拆分出 90 个独立模块connector-jdbc、connector-kafka、connector-cdc-* 等这正是文档所说连接器是主要贡献区域的原因seatunnel-engine/下则是 Zeta 引擎的 client/common/core/server/storage 等子模块。提交信息中的 Module 名与这套目录体系严格对应。Java 代码规范SeaTunnel 后端遵循 Google Java FormatAOSP 风格由 Spotless 强制实施此外还有几条硬性约定导入禁止通配符导入import xxx.*优先使用 shade 后的依赖包名为org.apache.seatunnel.shade.*。这一点在 Option.java 中即可看到实例它导入的是org.apache.seatunnel.shade.com.fasterxml.jackson.core.type.TypeReference而非直接依赖 Jackson 原始坐标——这正是 shade 依赖隔离策略的落地。空值语义避免隐式的 null 假设null 处理必须显式。可见性API 保持最小化能包内私有package-private就优先不向外部暴露不必要的接口。注释重要方法必须写注释包括 public API、生命周期钩子初始化、start/stop、checkpoint以及复杂或性能敏感的逻辑。文档给出了标准示例/** * Enumerates source splits for parallel reading. * Called once during job initialization. * * param context Split enumeration context * return Collection of discovered splits */ Override public ListSourceSplit enumerateSplits(SplitEnumerationContext context) { // Implementation }enumerateSplits正是SeaTunnelSource接口中支撑并行读取的核心方法见 SeaTunnelSource.java一次调用返回全部分片再由引擎分发给多个并行任务。ASF License 头强制所有新建文件必须携带 ASF 许可证头这是 Apache 项目的合规红线/* * 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. */仓库中几乎每个源码文件与脚本包括bin/install-plugin.sh、config/v2.batch.config.template等都以该头开场新建文件照此复制即可。向后兼容是硬约束文档用 VERY IMPORTANT 强调向后兼容是硬约束hard constraintAgent 必须将其作为不可逾越的红线。禁止事项不得移除或重命名现有配置项config option不得随意修改默认值不得破坏 public API 或 SPI 契约任何不兼容变更必须同时满足显式写入文档登记到docs/en/introduction/concepts/incompatible-changes.md提供迁移指引在 PR 描述中清晰说明这份登记文件在仓库中真实存在且持续维护incompatible-changes.md 记录了逐版本的破坏性变更例如JDBC 连接器时区感知时间戳列MySQLTIMESTAMP、PostgreSQLtimestamptz等由统一映射为TIMESTAMP改为显式映射为TIMESTAMP_TZ直接影响 Iceberg 等下游的建表语义引擎 REST 指标表级指标 key 从{tableName}变为{VertexIdentifier}.{tableName}如Sink[0].fake.user_table要求 Grafana/Prometheus 监控规则同步更新Condition.of(option, null)不再被允许seatunnel-api的Condition构造器现在会在构造期对空期望值抛IllegalArgumentException官方建议用Conditions.notBlank(option)替代。这些真实条目告诉我们兼容性管理不是口号而是有制度化登记、有迁移方案、有影响评估的完整流程。升级前查阅该文件是 SeaTunnel 社区的既定动作。依赖规则依赖引入是 Agent 最容易顺手触发的改动文档对此明确设限除非绝对必要不得引入新依赖优先复用org.apache.seatunnel.shade.*下已有的 shade 依赖任何新依赖必须在 PR 描述中说明理由并评估 shading、体积与冲突风险其背后逻辑是SeaTunnel 通过 shade 把常用三方库如 Jackson统一隔离到内部命名空间避免连接器各自拉版本造成类冲突。读者在阅读连接器代码时如果看到org.apache.seatunnel.shade.*的 import应理解为这是刻意的隔离设计而不是包名写错了。架构指南ConnectorV2新连接器的开发必须遵循以下骨架实现SeaTunnelSource或SeaTunnelSink接口定义见 SeaTunnelSource.java配置项使用Option定义见下文配置规则通过SourceSplitEnumerator支持并行先枚举分片再由多个并行 reader 消费禁止把连接器特有的逻辑泄漏到引擎或 core 模块中这是插件化的核心约束连接器与引擎之间只通过 API 契约通信引擎不感知任何具体连接器的实现细节从而保证新增一个连接器无需改动引擎代码。Zeta 引擎Zeta 是 SeaTunnel 自研的分布式引擎seatunnel-engine/文档明确了三层角色划分Client提交作业配置Master调度与协调Worker执行任务Source → Transform → Sink这三层在seatunnel-engine/下对应 seatunnel-engine-client、seatunnel-engine-server含 master/worker 实现等模块。开发时必须尊重任务边界与生命周期语义——例如 checkpoint 的协调由引擎负责连接器只负责在prepareCommit/commit等生命周期钩子中完成自身职责。配置Option规则SeaTunnel 的全部用户可见配置必须通过Option机制定义这是配置体系的基石。每个 Option 必须包含name键名type类型default value默认值如适用clear description清晰描述查看 Option.java 的源码即可印证其设计OptionT封装了key配置键、typeReference类型引用、defaultValue默认值、description描述以及fallbackKeys回退键列表五个核心字段。fallbackKeys的存在说明 SeaTunnel 支持配置键的兼容回退——老键名可以平滑映射到新键名这正是Option 名称是稳定契约这一规则的技术支撑。配套的OptionRule见 OptionRule.java负责组装与校验配置项连接器通过它声明必填项、可选项及条件约束。实际配置模板如 v2.batch.config.template中的env/source/sink三段结构最终都会解析并绑定到各插件声明的 Option 上。错误处理与日志异常必须携带足够的上下文信息涉及的表、任务、配置键方便定位问题禁止吞掉异常swallow异常要么向上传播要么显式处理日志级别使用规范INFO—— 生命周期事件WARN—— 可恢复问题ERROR—— 导致任务失败的错误绝不记录敏感信息密码、token、凭据这条规则直接关系到可观测性与安全性CDC 作业中若异常只报操作失败而不带表名和任务 ID排障成本会成倍上升而日志中混入数据库密码则可能造成生产事故。在实现连接器时异常消息建议形如Failed to write to table {table} in task {task}, config key: {key}。文档规则文档被视为功能的一部分而不是事后的补充Documentation is part of the feature, not an afterthought任何用户可见的变更都必须同步更新docs/en与docs/zh仓库中这两套文档目录结构一一对应正是为了支持双语同步配置名、默认值、示例必须与代码严格一致禁止文档与实现脱节这意味着 Agent 改配置项时必须同步检查 docs/en 与 docs/zh 下对应连接器文档中的参数表测试指南单元测试位于各模块的src/test/java下例如 seatunnel-api 的测试验证行为而非实现细节优先编写确定性、最小化的测试./mvnw testE2E 测试位于seatunnel-e2e目录基于Testcontainers拉起真实中间件测试类需继承TestSuiteBase基类实现在 TestSuiteBase.java./mvnw -DskipUT -DskipITfalse verify注意-DskipUT跳过单元测试、-DskipITfalse开启集成测试与单测命令形成互补。seatunnel-e2e/seatunnel-connector-v2-e2e/下每个连接器都有对应的connector-xxx-e2e模块例如 connector-jdbc-e2e、connector-cdc-mysql-e2e 等它们是连接器改动合入前的最后一道防线。性能意识Agent 编写代码时必须评估性能影响热路径每条数据都会经过的路径避免不必要的对象创建——例如在 source/sink 的逐行处理逻辑中重复 new 对象会显著拉高 GC 压力谨慎使用大内存缓冲区警惕 OOM 与背压问题时刻考虑并行度与资源使用parallelism的取值、分片粒度的设计都会直接影响集群吞吐PR 范围规则变更保持最小化与聚焦避免夹带无关重构或纯格式修改一个 PR 只解决一个问题这条规则与向后兼容硬约束配合使用范围越小review 越容易回归风险越低也越容易被 maintainer 接受。运行与调试实战从源码构建./mvnw clean install -DskipTests -Dskip.spotlesstrue跳过测试与格式检查以加速本地开发迭代正式提 PR 前仍需补跑前文的验证三连。安装连接器插件sh bin/install-plugin.sh $current_version该脚本在仓库 bin/install-plugin.sh 中真实存在其工作机制值得深入理解读取清单脚本读取 config/plugin_config 中--connectors-v2--标记下的连接器 artifactId 列表逐一下载文件头部注释说明了该清单用于把用户配置中的插件名映射到对应 JAR 包名。版本与下载方式连接器默认版本为3.0.0见 install-plugin.sh可通过第一个参数覆盖下载方式由环境变量SEATUNNEL_PLUGIN_DOWNLOAD_METHOD控制https或maven当版本为快照/动态版本如*-SNAPSHOT、LATEST时自动切换到 Maven 方式以解析唯一快照Maven 仓库地址可用SEATUNNEL_MAVEN_REPOSITORY覆盖。安全校验HTTPS 方式下会下载.sha512/.sha1校验文件并逐字节比对还会校验下载文件是否为合法 JAR检查 ZIP 魔数504b防止下载到损坏或伪造的文件。运行作业Zetash bin/seatunnel.sh --config config/v2.batch.config.template -e local说明当前源码仓库的bin/目录直接保留的是插件安装脚本install-plugin.sh及其 Windows 版install-plugin.cmdseatunnel.sh等启动脚本随发行装配产出此处沿用CLAUDE.md中面向发行版的标准用法。-e local表示以本地模式运行作业配置取自仓库中的 v2.batch.config.template该模板展示了最小可用配置的三段式结构env { parallelism 2 job.mode BATCH checkpoint.interval 10000 } source { FakeSource { parallelism 2 plugin_output fake row.num 16 schema { fields { name string age int } } } } sink { Console { } }env作业级配置parallelism控制并行度job.mode区分 BATCH/STREAMINGcheckpoint.interval设置检查点间隔source数据源FakeSource是内置测试源row.num控制生成行数schema声明字段类型sink数据目的地Console把结果打印到控制台便于快速验证管道连通性。替换 source/sink 为真实连接器如 Kafka、JDBC、MySQL CDC即可过渡到生产场景。总结Agent 协作的黄金流程把整份指南压缩成一份可执行的行动清单无论对人还是对 Agent 都适用动手前阅读CLAUDE.md/AGENTS.md对照仓库结构确认改动落在哪个模块写代码时遵守 Java 规范Spotless 格式、无通配符 import、shade 依赖、携带 ASF License 头、用Option定义配置、按 INFO/WARN/ERROR 分级打日志且不记录敏感信息、保持向后兼容改动后依次执行./mvnw spotless:apply→./mvnw -q -DskipTests verify→./mvnw test连接器改动补 E2E 测试继承TestSuiteBase提交时使用[Type][Module] Description格式保持一个 PR 解决一个问题若涉及破坏性变更同步更新docs/en与docs/zh登记到 incompatible-changes.md 并提供迁移指引。这套约定之所以被反复强调是因为它直接决定了 SeaTunnel 这样一个多模块、多连接器、多引擎适配的大型数据集成项目能否长期保持可维护性。理解并遵守它是成为合格 SeaTunnel 贡献者的第一步。【免费下载链接】seatunnelSeaTunnel is a multimodal, high-performance, distributed, massive data integration tool.项目地址: https://gitcode.com/GitHub_Trending/se/seatunnel创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 Apache SeaTunnel 开发规范与 AI Agent 工程实践指南：从构建验证到提交协作的完整约定
Apache SeaTunnel 开发规范与 AI Agent 工程实践指南从构建验证到提交协作的完整约定【免费下载链接】seatunnelSeaTunnel is a multimodal, high-performance, distributed, massive data integration tool.项目地址: https://gitcode.com/GitHub_Trending/se/seatunnelApache SeaTunnel 在仓库根目录维护了一份面向 LLM / AI Agent 的上下文指南CLAUDE.md与AGENTS.md内容一致它把成熟 Apache 项目的工程纪律沉淀为可执行的硬性约定提变更前必须本地验证、提交信息必须遵循[Type][Module]格式、配置项必须用Option定义、不兼容变更必须登记备案。本文以此文档为骨架结合仓库源码seatunnel-api、seatunnel-engine、seatunnel-e2e、bin/install-plugin.sh等逐条展开解读帮助你无论是人还是 Agent在 SeaTunnel 代码库上写出安全、一致、可验证的代码与提交。这份文档是什么为 LLM/Agent 准备的代码库上下文指南CLAUDE.md的定位非常明确帮助 AI 助手LLM / Agent对 Apache SeaTunnel 代码库做出安全safe、一致consistent、可验证verifiable的修改。它并不是泛泛的贡献指南而是镜像了成熟 Apache 项目的工程实践并逐一适配到 SeaTunnel 特有的构建、测试、架构和文档约定上——例如 Zeta 引擎的三层角色、Option配置体系、seatunnel-e2e的 Testcontainers 测试范式等。因此理解这份文档的正确方式是把它当作进入 SeaTunnel 代码库的协作契约文档中的每一条规则几乎都能在仓库中找到对应的实现或配套脚本作为证据。铁律一提变更前必须本地验证文档开篇即以 CRITICAL: Validate Before Proposing Changes 强调Agent 必须在本地运行验证命令之后再建议或提交变更否则 PR 大概率会被拒绝。# 格式化代码强制 ./mvnw spotless:apply # 快速验证强制 ./mvnw -q -DskipTests verify # 单元测试强烈建议 ./mvnw test三条命令分工明确spotless:apply是 SeaTunnel 的代码格式化入口统一使用Google Java FormatAOSP 风格。仓库中tools/spotless_check/pre-commit.sh的存在进一步印证格式检查被前置到提交阶段避免不合规代码流入主干。-q -DskipTests verify用于快速验证编译与打包链路是否畅通跳过测试以节省时间是改完先保证能编译的底线检查。mvnw test运行单元测试验证行为正确性属于强烈推荐项。Git 提交信息约定SeaTunnel 采用严格的提交信息格式来维持干净、可检索的历史记录[Type][Module] DescriptionType类型Type含义Feature新功能FixBug 修复Improve对现有行为的改进Docs仅文档变更Test测试用例或测试框架变更Chore构建、依赖或维护类任务Module模块模块名与仓库顶层目录一一对应例如Module对应模块Connector-V2seatunnel-connectors-v2Zetaseatunnel-engineZeta 引擎Coreseatunnel-coreAPIseatunnel-apiTransform-V2seatunnel-transforms-v2Formatseatunnel-formatsTranslationseatunnel-translationE2Eseatunnel-e2e示例[Fix][Connector-V2] Fix MySQL source split enumeration bug [Fix][Zeta] Fix checkpoint timeout under heavy backpressure [Feature][Transform-V2] Add LLM transform plugin [Improve][Core] Optimize jar package loading speed [Docs] Update quick start guide这种格式让git log --grep可以快速按模块或类型过滤历史例如查找所有 Zeta 引擎的修复只需要检索\[Fix\]\[Zeta\]。仓库结构速览文档给出了模块级的目录导航与实际仓库布局一一对应seatunnel/ ├── seatunnel-api/ # 核心 API 定义 ├── seatunnel-connectors-v2/ # Source Sink 连接器主要贡献区域 ├── seatunnel-transforms-v2/ # Transform 插件包括 LLM ├── seatunnel-engine/ # Zeta 引擎 Web UI ├── seatunnel-core/ # 作业提交与 CLI 入口 ├── seatunnel-translation/ # Flink Spark 适配层 ├── seatunnel-formats/ # 数据格式JSON、Avro 等 ├── seatunnel-e2e/ # 端到端集成测试 ├── docs/ # 文档en zh └── config/ # 默认配置对照真实仓库可以看到seatunnel-connectors-v2/下按连接器拆分出 90 个独立模块connector-jdbc、connector-kafka、connector-cdc-* 等这正是文档所说连接器是主要贡献区域的原因seatunnel-engine/下则是 Zeta 引擎的 client/common/core/server/storage 等子模块。提交信息中的 Module 名与这套目录体系严格对应。Java 代码规范SeaTunnel 后端遵循 Google Java FormatAOSP 风格由 Spotless 强制实施此外还有几条硬性约定导入禁止通配符导入import xxx.*优先使用 shade 后的依赖包名为org.apache.seatunnel.shade.*。这一点在 Option.java 中即可看到实例它导入的是org.apache.seatunnel.shade.com.fasterxml.jackson.core.type.TypeReference而非直接依赖 Jackson 原始坐标——这正是 shade 依赖隔离策略的落地。空值语义避免隐式的 null 假设null 处理必须显式。可见性API 保持最小化能包内私有package-private就优先不向外部暴露不必要的接口。注释重要方法必须写注释包括 public API、生命周期钩子初始化、start/stop、checkpoint以及复杂或性能敏感的逻辑。文档给出了标准示例/** * Enumerates source splits for parallel reading. * Called once during job initialization. * * param context Split enumeration context * return Collection of discovered splits */ Override public ListSourceSplit enumerateSplits(SplitEnumerationContext context) { // Implementation }enumerateSplits正是SeaTunnelSource接口中支撑并行读取的核心方法见 SeaTunnelSource.java一次调用返回全部分片再由引擎分发给多个并行任务。ASF License 头强制所有新建文件必须携带 ASF 许可证头这是 Apache 项目的合规红线/* * 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. */仓库中几乎每个源码文件与脚本包括bin/install-plugin.sh、config/v2.batch.config.template等都以该头开场新建文件照此复制即可。向后兼容是硬约束文档用 VERY IMPORTANT 强调向后兼容是硬约束hard constraintAgent 必须将其作为不可逾越的红线。禁止事项不得移除或重命名现有配置项config option不得随意修改默认值不得破坏 public API 或 SPI 契约任何不兼容变更必须同时满足显式写入文档登记到docs/en/introduction/concepts/incompatible-changes.md提供迁移指引在 PR 描述中清晰说明这份登记文件在仓库中真实存在且持续维护incompatible-changes.md 记录了逐版本的破坏性变更例如JDBC 连接器时区感知时间戳列MySQLTIMESTAMP、PostgreSQLtimestamptz等由统一映射为TIMESTAMP改为显式映射为TIMESTAMP_TZ直接影响 Iceberg 等下游的建表语义引擎 REST 指标表级指标 key 从{tableName}变为{VertexIdentifier}.{tableName}如Sink[0].fake.user_table要求 Grafana/Prometheus 监控规则同步更新Condition.of(option, null)不再被允许seatunnel-api的Condition构造器现在会在构造期对空期望值抛IllegalArgumentException官方建议用Conditions.notBlank(option)替代。这些真实条目告诉我们兼容性管理不是口号而是有制度化登记、有迁移方案、有影响评估的完整流程。升级前查阅该文件是 SeaTunnel 社区的既定动作。依赖规则依赖引入是 Agent 最容易顺手触发的改动文档对此明确设限除非绝对必要不得引入新依赖优先复用org.apache.seatunnel.shade.*下已有的 shade 依赖任何新依赖必须在 PR 描述中说明理由并评估 shading、体积与冲突风险其背后逻辑是SeaTunnel 通过 shade 把常用三方库如 Jackson统一隔离到内部命名空间避免连接器各自拉版本造成类冲突。读者在阅读连接器代码时如果看到org.apache.seatunnel.shade.*的 import应理解为这是刻意的隔离设计而不是包名写错了。架构指南ConnectorV2新连接器的开发必须遵循以下骨架实现SeaTunnelSource或SeaTunnelSink接口定义见 SeaTunnelSource.java配置项使用Option定义见下文配置规则通过SourceSplitEnumerator支持并行先枚举分片再由多个并行 reader 消费禁止把连接器特有的逻辑泄漏到引擎或 core 模块中这是插件化的核心约束连接器与引擎之间只通过 API 契约通信引擎不感知任何具体连接器的实现细节从而保证新增一个连接器无需改动引擎代码。Zeta 引擎Zeta 是 SeaTunnel 自研的分布式引擎seatunnel-engine/文档明确了三层角色划分Client提交作业配置Master调度与协调Worker执行任务Source → Transform → Sink这三层在seatunnel-engine/下对应 seatunnel-engine-client、seatunnel-engine-server含 master/worker 实现等模块。开发时必须尊重任务边界与生命周期语义——例如 checkpoint 的协调由引擎负责连接器只负责在prepareCommit/commit等生命周期钩子中完成自身职责。配置Option规则SeaTunnel 的全部用户可见配置必须通过Option机制定义这是配置体系的基石。每个 Option 必须包含name键名type类型default value默认值如适用clear description清晰描述查看 Option.java 的源码即可印证其设计OptionT封装了key配置键、typeReference类型引用、defaultValue默认值、description描述以及fallbackKeys回退键列表五个核心字段。fallbackKeys的存在说明 SeaTunnel 支持配置键的兼容回退——老键名可以平滑映射到新键名这正是Option 名称是稳定契约这一规则的技术支撑。配套的OptionRule见 OptionRule.java负责组装与校验配置项连接器通过它声明必填项、可选项及条件约束。实际配置模板如 v2.batch.config.template中的env/source/sink三段结构最终都会解析并绑定到各插件声明的 Option 上。错误处理与日志异常必须携带足够的上下文信息涉及的表、任务、配置键方便定位问题禁止吞掉异常swallow异常要么向上传播要么显式处理日志级别使用规范INFO—— 生命周期事件WARN—— 可恢复问题ERROR—— 导致任务失败的错误绝不记录敏感信息密码、token、凭据这条规则直接关系到可观测性与安全性CDC 作业中若异常只报操作失败而不带表名和任务 ID排障成本会成倍上升而日志中混入数据库密码则可能造成生产事故。在实现连接器时异常消息建议形如Failed to write to table {table} in task {task}, config key: {key}。文档规则文档被视为功能的一部分而不是事后的补充Documentation is part of the feature, not an afterthought任何用户可见的变更都必须同步更新docs/en与docs/zh仓库中这两套文档目录结构一一对应正是为了支持双语同步配置名、默认值、示例必须与代码严格一致禁止文档与实现脱节这意味着 Agent 改配置项时必须同步检查 docs/en 与 docs/zh 下对应连接器文档中的参数表测试指南单元测试位于各模块的src/test/java下例如 seatunnel-api 的测试验证行为而非实现细节优先编写确定性、最小化的测试./mvnw testE2E 测试位于seatunnel-e2e目录基于Testcontainers拉起真实中间件测试类需继承TestSuiteBase基类实现在 TestSuiteBase.java./mvnw -DskipUT -DskipITfalse verify注意-DskipUT跳过单元测试、-DskipITfalse开启集成测试与单测命令形成互补。seatunnel-e2e/seatunnel-connector-v2-e2e/下每个连接器都有对应的connector-xxx-e2e模块例如 connector-jdbc-e2e、connector-cdc-mysql-e2e 等它们是连接器改动合入前的最后一道防线。性能意识Agent 编写代码时必须评估性能影响热路径每条数据都会经过的路径避免不必要的对象创建——例如在 source/sink 的逐行处理逻辑中重复 new 对象会显著拉高 GC 压力谨慎使用大内存缓冲区警惕 OOM 与背压问题时刻考虑并行度与资源使用parallelism的取值、分片粒度的设计都会直接影响集群吞吐PR 范围规则变更保持最小化与聚焦避免夹带无关重构或纯格式修改一个 PR 只解决一个问题这条规则与向后兼容硬约束配合使用范围越小review 越容易回归风险越低也越容易被 maintainer 接受。运行与调试实战从源码构建./mvnw clean install -DskipTests -Dskip.spotlesstrue跳过测试与格式检查以加速本地开发迭代正式提 PR 前仍需补跑前文的验证三连。安装连接器插件sh bin/install-plugin.sh $current_version该脚本在仓库 bin/install-plugin.sh 中真实存在其工作机制值得深入理解读取清单脚本读取 config/plugin_config 中--connectors-v2--标记下的连接器 artifactId 列表逐一下载文件头部注释说明了该清单用于把用户配置中的插件名映射到对应 JAR 包名。版本与下载方式连接器默认版本为3.0.0见 install-plugin.sh可通过第一个参数覆盖下载方式由环境变量SEATUNNEL_PLUGIN_DOWNLOAD_METHOD控制https或maven当版本为快照/动态版本如*-SNAPSHOT、LATEST时自动切换到 Maven 方式以解析唯一快照Maven 仓库地址可用SEATUNNEL_MAVEN_REPOSITORY覆盖。安全校验HTTPS 方式下会下载.sha512/.sha1校验文件并逐字节比对还会校验下载文件是否为合法 JAR检查 ZIP 魔数504b防止下载到损坏或伪造的文件。运行作业Zetash bin/seatunnel.sh --config config/v2.batch.config.template -e local说明当前源码仓库的bin/目录直接保留的是插件安装脚本install-plugin.sh及其 Windows 版install-plugin.cmdseatunnel.sh等启动脚本随发行装配产出此处沿用CLAUDE.md中面向发行版的标准用法。-e local表示以本地模式运行作业配置取自仓库中的 v2.batch.config.template该模板展示了最小可用配置的三段式结构env { parallelism 2 job.mode BATCH checkpoint.interval 10000 } source { FakeSource { parallelism 2 plugin_output fake row.num 16 schema { fields { name string age int } } } } sink { Console { } }env作业级配置parallelism控制并行度job.mode区分 BATCH/STREAMINGcheckpoint.interval设置检查点间隔source数据源FakeSource是内置测试源row.num控制生成行数schema声明字段类型sink数据目的地Console把结果打印到控制台便于快速验证管道连通性。替换 source/sink 为真实连接器如 Kafka、JDBC、MySQL CDC即可过渡到生产场景。总结Agent 协作的黄金流程把整份指南压缩成一份可执行的行动清单无论对人还是对 Agent 都适用动手前阅读CLAUDE.md/AGENTS.md对照仓库结构确认改动落在哪个模块写代码时遵守 Java 规范Spotless 格式、无通配符 import、shade 依赖、携带 ASF License 头、用Option定义配置、按 INFO/WARN/ERROR 分级打日志且不记录敏感信息、保持向后兼容改动后依次执行./mvnw spotless:apply→./mvnw -q -DskipTests verify→./mvnw test连接器改动补 E2E 测试继承TestSuiteBase提交时使用[Type][Module] Description格式保持一个 PR 解决一个问题若涉及破坏性变更同步更新docs/en与docs/zh登记到 incompatible-changes.md 并提供迁移指引。这套约定之所以被反复强调是因为它直接决定了 SeaTunnel 这样一个多模块、多连接器、多引擎适配的大型数据集成项目能否长期保持可维护性。理解并遵守它是成为合格 SeaTunnel 贡献者的第一步。【免费下载链接】seatunnelSeaTunnel is a multimodal, high-performance, distributed, massive data integration tool.项目地址: https://gitcode.com/GitHub_Trending/se/seatunnel创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考