Apache SeaTunnel 项目编码规范与最佳实践指南

Apache SeaTunnel 项目编码规范与最佳实践指南

seatunnel SeaTunnel is a next-generation super high-performance, distributed, massive data integration tool. 项目地址: https://gitcode.com/gh_mirrors/sea/seatunnel

项目模块架构解析

Apache SeaTunnel 作为一个数据集成平台，其代码结构采用了模块化设计，各模块职责分明：

1. 核心基础模块

   • seatunnel-api: 提供连接器V2版本的统一接口定义
   • seatunnel-common: 包含项目通用工具类和基础组件
   • seatunnel-plugin-discovery: 实现SPI插件发现机制

2. 连接器相关模块

   • seatunnel-connectors-v2: 新一代连接器实现（当前重点开发方向）
   • seatunnel-formats: 数据格式化处理能力
   • seatunnel-transforms-v2: 数据转换功能模块

3. 引擎适配层

   • seatunnel-core下的各starter模块：
     • seatunnel-spark-starter: Spark引擎适配
     • seatunnel-flink-starter: Flink引擎适配
     • seatunnel-starter: SeaTunnel原生引擎适配
   • seatunnel-translation: 连接器与计算引擎间的适配层

4. 测试与示例

   • seatunnel-e2e: 端到端测试模块
   • seatunnel-examples: 本地开发测试示例

5. 核心引擎

   • seatunnel-engine: SeaTunnel自研的计算引擎，专注于数据同步场景

高质量代码提交规范

1. 代码风格与结构

• Lombok应用：推荐使用@Data、@Getter等注解简化POJO类定义，@Slf4j简化日志声明
• DRY原则：避免重复代码片段，提取公共组件
• 访问控制：类属性优先使用private final修饰
• 基础类型优先：方法参数和属性优先使用基本类型(int, boolean等)

2. 异常处理规范

• 精准捕获：避免捕获过于宽泛的异常类型
• 异常包装：捕获底层异常后应转换为项目自定义异常
• 信息完整：异常消息应包含足够上下文信息

示例：

try {
    // 数据读取逻辑
} catch (IOException e) {
    throw new SeaTunnelORCFormatException("ORC文件损坏，请检查文件完整性", e);
}

3. 分支逻辑优化

• 条件简化：使用多个独立if替代if-else-if链
• 提前返回：对于异常条件优先处理并提前返回

4. 序列化注意事项

开发Sink连接器时需特别注意：

• 确保所有属性可序列化
• 对不可序列化的属性使用单例模式封装
• 考虑分布式环境下的对象传输

开发流程最佳实践

1. 问题跟踪与提交

• 问题分类：明确标记为Feature/Bug/Docs/Discuss
• 模块标注：在标题中注明涉及的模块和子模块
• 描述清晰：简明扼要说明问题或改进点

2. 代码质量保障

• 许可证检查：确保每个文件包含Apache许可证声明
• 格式化工具：使用Spotless自动格式化代码

./mvnw spotless:apply

• 完整编译：提交前执行全项目编译

./mvnw -T 1C clean package

3. 测试要求

• 单元测试：为新增功能添加测试用例
• 集成测试：利用seatunnel-examples模块验证多引擎兼容性
• E2E测试：对于连接器开发需包含：
  • 完整数据类型覆盖
  • 源端和目的端联合测试
  • 异步测试保证稳定性

社区协作准则

1. 单一职责：每个PR只解决一个明确问题
2. 事前讨论：对核心模块的重大修改应先发起讨论
3. 文档同步：功能变更需同步更新相关文档
4. 测试负责制：贡献者需为PR提供相应测试证明

通过遵循这些规范，开发者可以确保代码质量符合Apache SeaTunnel项目要求，提高代码审查效率，促进项目健康发展。

seatunnel SeaTunnel is a next-generation super high-performance, distributed, massive data integration tool. 项目地址: https://gitcode.com/gh_mirrors/sea/seatunnel