版本：Next

编码指南

本指南整体介绍了当前 Apache SeaTunnel 的模块和提交一个高质量 pull request 的最佳实践。

模块概述

模块名	介绍
seatunnel-api	SeaTunnel connector V2 API 模块
seatunnel-common	SeaTunnel 通用模块
seatunnel-connectors-v2	SeaTunnel connector V2 模块, connector V2 处于社区重点开发中
seatunnel-core/seatunnel-spark-starter	SeaTunnel connector V2 的 Spark 引擎核心启动模块
seatunnel-core/seatunnel-flink-starter	SeaTunnel connector V2 的 Flink 引擎核心启动模块
seatunnel-core/seatunnel-starter	SeaTunnel connector V2 的 SeaTunnel 引擎核心启动模块
seatunnel-e2e	SeaTunnel 端到端测试模块
seatunnel-examples	SeaTunnel 本地案例模块，开发者可以用来单元测试和集成测试
seatunnel-engine	SeaTunnel 引擎模块, seatunnel-engine 是 SeaTunnel 社区新开发的计算引擎，用来实现数据同步
seatunnel-formats	SeaTunnel 格式化模块，用来提供格式化数据的能力
seatunnel-plugin-discovery	SeaTunnel 插件发现模块，用来加载类路径中的SPI插件
seatunnel-transforms-v2	SeaTunnel transform V2 模块, transform V2 处于社区重点开发中
seatunnel-translation	SeaTunnel translation 模块, 用来适配Connector V2 和其他计算引擎，例如Spark、Flink等

如何提交一个高质量的Pull Request

创建实体类的时候使用 lombok 插件的注解(@Data @Getter @Setter @NonNull 等)来减少代码量。在编码过程中优先使用 lombok 插件是一个很好的习惯。
如果你需要在类中使用 log4j 打印日志，优先使用 lombok 中的 @Slf4j 注解。
SeaTunnel 使用 Github issue 来跟踪代码问题，包括 bugs 和改进，并且使用 Github pull request 来管理代码的审查和合并。所以创建一个清晰的 issue 或者 pull request 能让社区更好的理解开发者的意图，最佳实践如下：
[目的][模块名称] [子模块名称] 描述
1. Pull request 目的包含: Hotfix, Feature, Improve, Docs, WIP。请注意如果选择 WIP, 你需要使用 github 的 draft pull request。
2. Issue 目的包含: Feature, Bug, Docs, Discuss。
3. 模块名称: 当前 pull request 或 issue 所涉及的模块名称, 例如: Core, Connector-V2, Connector-V1等。
4. 子模块名称: 当前 pull request 或 issue 所涉及的子模块名称, 例如:File Redis Hbase等。
5. 描述: 高度概括下当前 pull request 和 issue 要做的事情，尽量见名知意。
提示:更多内容, 可以参考 Issue Guide 和 Pull Request Guide
代码片段不要重复。如果一段代码被使用多次，定义多次不是好的选择，最佳实践是把它公共独立出来让其他模块使用。
当抛出一个异常时，需要一起带上提示信息并且使异常的范围尽可能地小。抛出过于广泛的异常会让错误处理变得复杂并且容易包含安全问题。例如，如果你的 connector 在读数据的时候遇到 IOException，合理的做法如下：
```
try {
    // read logic
} catch (IOException e) {
    throw SeaTunnelORCFormatException("This orc file is corrupted, please check it", e);
}
```

Apache 项目的 license 要求很严格，每个 Apache 项目文件都应该包含一个 license 声明。在提交 pull request 之前请检查每个新文件都包含 Apache License Header。

/*
 * 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.
 */

Apache SeaTunnel 使用 Spotless 管理代码风格和格式检查。你可以使用下面的命令来自动修复代码风格问题和格式。
```
./mvnw spotless:apply
```
提交 pull request 之前，确保修改后项目编译正常，使用下面命令打包整个项目：
```
# 多线程编译
./mvnw -T 1C clean package
```
```
# 单线程编译
./mvnw clean package
```
提交 pull request 之前，在本地用完整的单元测试和集成测试来检查你的功能性是否正确，最佳实践是用 seatunnel-examples 模块的例子去检查多引擎是否正确运行并且结果正确。
如果提交的 pull request 是一个新的特性，请记得更新文档。
提交 connector 相关的 pull request, 可以通过写 e2e 测试保证鲁棒性，e2e 测试需要包含所有的数据类型，并且初始化尽可能小的 docker 镜像，sink 和 source 的测试用例可以写在一起减少资源的损耗。可以参考这个不错的例子： MongodbIT.java
类中默认的权限需要使用 private，不可修改的需要设置 final，特殊场景除外。
类中的属性和方法参数倾向于使用基本数据类型(int boolean double float...)，而不是包装类型(Integer Boolean Double Float...)，特殊情况除外。
开发一个 sink connector 的时候你需要知道 sink 需要被序列化，如果有不能被序列化的属性，需要包装到一个类中，并且使用单例模式。
如果代码中有多个 if 流程判断，尽量简化为多个 if 而不是 if-else-if。
Pull request 具有单一职责的特点，不允许在 pull request 包含与该功能无关的代码，如果有这种情况，需要在提交 pull request 之前单独处理好，否则 Apache SeaTunnel 社区会主动关闭 pull request。
贡献者需要对自己的 pull request 负责。如果 pull request 包含新的特性，或者修改了老的特性，增加测试用例或者 e2e 用例来证明合理性和保护完整性是一个很好的做法。
如果你认为社区当前某部分代码不合理（尤其是核心的 core 和 api 模块），有函数需要更新修改，优先使用 discuss issue 和 email 与社区讨论是否有必要修改，社区同意后再提交 pull request, 请不要不经讨论直接提交 pull request, 社区会认为无效并且关闭。

编码指南

模块概述​

如何提交一个高质量的Pull Request​

模块概述

如何提交一个高质量的Pull Request