Flink CDC 贡献者开发指南基于 AGENTS.md 的构建、测试与协作规范深度解析【免费下载链接】flink-cdcFlink CDC is a streaming data integration tool项目地址: https://gitcode.com/GitHub_Trending/flin/flink-cdc本篇指南以仓库根目录的 AGENTS.md 为骨架系统梳理 Apache Flink CDC 面向 AI 编码代理与人类贡献者的协作规范包括构建命令、测试策略、模块结构与编码标准。读完本文你将掌握 Flink CDC 的快速编译方式、Flink 1.x/2.x 双版本兼容构建、JUnit 5 AssertJ 测试编写规范以及提交信息、Pull Request 与变更边界的完整约定可直接用于日常开发与提交审核。一、AGENTS.md 是什么一份写给 AI 编码代理的协作手册AGENTS.md 是 Flink CDC 仓库中专门面向 AI 编码代理AI coding agents的指导文件目标是在 AI 生成代码进入 Apache 开源项目流程时把人与仓库的隐性约定显式化用什么 JDK、怎么编译、怎么测试、代码怎么写、提交怎么提、什么能改什么不能改。它本质上是一份可执行的仓库贡献契约既约束 AI 代理也约束所有参与者确保代码风格、测试口径与流程规范的一致。本文所有命令均以仓库根目录当前仓库flink-cdc根目录为执行起点关键配置项均有仓库源码佐证。二、开发环境前置要求PrerequisitesAGENTS.md 明确列出的环境基线Java 11作为编译基线所有代码必须在 Java 11 上编译运行Java 17用于双版本验证与较新的 Flink 2.x 环境Maven 3.8.6 或更高版本GitUnix-like 环境Linux、macOS、WSLDocker运行集成测试ITCase与端到端测试e2e tests时必需。仓库根 pom.xml 中java.version11、source.java.version11、target.java.version11与上述基线一致同时 Maven Enforcer 插件在构建时强制校验requireMavenVersion [3.1.1,)与requireJavaVersion ${source.java.version}见 pom.xml。pom 中还提供了按 JDK 自动激活的java-11-targetJDK 11~17与java-17-targetJDK 17profile自动切换编译目标。三、构建命令速查BuildAGENTS.md 给出了四类典型构建命令均可直接复制使用# 1. 快速开发构建跳过测试与格式检查追求最快反馈 mvn clean install -DskipTests -Dspotless.check.skiptrue -Dcheckstyle.skiptrue # 2. 针对 Flink 1.x 的完整构建默认 profile mvn clean package -DskipTests # 3. 针对 Flink 2.x 的完整构建 mvn clean package -DskipTests -Pflink2 # 4. 只构建单个模块示例flink-cdc-common-am 表示同时构建其依赖模块 mvn clean package -DskipTests -pl flink-cdc-common -am几个值得注意的仓库级细节-Pflink2profile会切换一组依赖版本如 Kafka 连接器版本、Paimon/Iceberg 的 Flink 主版本见 pom.xml并在测试阶段额外复制 Flink 2.x 的 shaded-guava 到target/flink2-extra-libs加入测试 classpathSpotless 全限定名问题根 pom 中有一条注释明确指出由于 Flink 构建环境设置直接执行mvn spotless:apply/mvn spotless:check可能失效需使用全限定插件名mvn com.diffplug.spotless:spotless-maven-plugin:apply见 pom.xml。AGENTS.md 中mvn spotless:apply的写法在实际执行受阻时可切换为该全限定形式根 pom 通过flatten-maven-plugin与maven-shade-plugin为所有子模块生成固定的dependency-reduced-pom.xml确保${flink.version}在子模块中被解析为实际版本号pom.xml。四、测试命令与测试策略TestingAGENTS.md 提供的测试命令矩阵# 运行某个模块的全部测试 mvn verify -pl flink-cdc-common # 针对 Flink 2.x 运行模块全部测试 mvn verify -pl flink-cdc-common -Pflink2 # 运行单个测试类 mvn -pl flink-cdc-common -DtestMyTest test # 运行单个测试方法 mvn -pl flink-cdc-common -DtestMyTest#myMethod test从根 pom 的 surefire 配置可以印证其运行机制pom.xml默认test阶段只执行**/*Test.java与**/*Test.scala单元测试单独的integration-testsexecution 绑定在integration-test阶段只执行**/*ITCase.java与**/*ITCase.scala需要 Docker / 真实数据库的集成测试为控制 MiniCluster 资源默认forkCount1、reuseForkstrue测试 JVM 追加了大量--add-opens/--add-exports参数并针对 Oracle 时区问题设置了-Doracle.jdbc.timezoneAsRegionfalse。因此如果只想跑单测用mvn test或-Dtest...要跑 Docker 集成测试需要mvn verify或显式触发 integration-test 阶段且本机具备 Docker 环境。五、代码质量与格式化Code QualityAGENTS.md 规定提交前必须执行# 应用代码风格规则如失败改用全限定名见第三节 mvn spotless:apply mvn spotless:checkSpotless基于 Google Java FormatAOSP 风格版本 1.24.0格式化并配置了 import 顺序org.apache.flink, org.apache.flink.shaded, , javax, java, scala, #(静态导入)同时自动移除未使用的 importpom.xmlCheckstyle在validate阶段执行规则文件为 tools/maven/checkstyle.xml包含文件行数上限、禁止尾随空白、禁止Throwables.propagate(、禁止Boolean/Integer/Long.getXxx等规则并提供 tools/maven/suppressions.xml 作为豁免清单License 头所有新增文件必须包含 ASF Apache License 2.0 头根 pom 的 apache-rat-plugin 会在verify阶段强制检查pom.xml。六、仓库结构总览围绕 Pipeline 抽象的模块化设计AGENTS.md 指出Flink CDC 围绕Pipeline 抽象组织代码一条用户定义的管道从一个或多个 Source 读取数据可选地做 transform再写入一个或多个 Sink。核心模块实现这一抽象连接器模块提供具体的源端与目标端实现。核心模块Core Modules模块职责flink-cdc-common跨模块共享的 API 与数据模型CDC 事件类型DataChangeEvent、SchemaChangeEvent等、schema 模型、数据类型、source/sink 接口、FactorySPI、路由定义、UDF 接口与工具类。大多数新抽象从这里开始。flink-cdc-runtimePipeline 的运行时实现读取、路由、transform基于 Calcite Janino 的表达式求值、写出 CDC 事件所需的算子。flink-cdc-composer管道装配与部署层把PipelineDefinition翻译成可运行的 Flink 作业串联 sources/operators/sinks支持 Flink 原生、Kubernetes、YARN 部署。flink-cdc-cli命令行入口flink-cdc.sh解析 YAML 管道定义并委托给flink-cdc-composer。flink-cdc-dist发行打包产出flink-cdc-version-bin发布归档。以 CLI 模块为例源码可以印证这一职责描述CliFrontend.java 是入口类解析命令行参数、打印帮助、创建 executor 并执行CliFrontendOptions.java 定义了全部命令行选项--flink-home、-h/--help、--global-config、--jar、-t/--target支持local、remote、yarn-session、yarn-application、kubernetes-application、--use-mini-cluster、-s/--from-savepoint、-cm/--claim-mode、-n/--allow-nonRestored-state、-D动态覆盖 Flink 配置。管道级全局配置样例可在 flink-cdc.yaml 中找到其核心字段与常见取值如下# 管道并行度 parallelism: 4 # 处理源端 schema change 事件的行为 schema.change.behavior: EVOLVEFlink 版本兼容Flink Version CompatibilityAGENTS.md 强调 Flink CDC 同时支持两代 Flinkflink-cdc-flink1-compat—— Flink 1.x 兼容层当前为1.20.3默认 profileflink-cdc-flink2-compat—— Flink 2.x 兼容层当前为2.2.0通过-Pflink2激活。根 pom.xml 中flink.1.x.version1.20.3、flink.2.x.version2.2.0、flink.version${flink.1.x.version}与此一致。所有依赖 Flink API 的模块必须将 Flink 依赖声明为providedscope并引用${flink.version}占位符由激活的 profile 解析pom.xml。改动请在 Flink 1.20LTS与 Flink 2.x 上分别验证。连接器模块flink-cdc-connect/连接器分为两类Source Connectorsflink-cdc-connect/flink-cdc-source-connectors/面向 DataStream 与 Flink SQL 作业的 CDC 源例如flink-connector-mysql-cdc、flink-connector-oracle-cdc、flink-connector-mongodb-cdc等每个源还配套发布对应的flink-sql-connector-*-cdcshaded 产物Pipeline Connectorsflink-cdc-connect/flink-cdc-pipeline-connectors/面向 YAML API 的管道连接器例如flink-cdc-pipeline-connector-doris、flink-cdc-pipeline-connector-kafka、flink-cdc-pipeline-connector-paimon等。测试模块与文档flink-cdc-e2e-tests/端到端测试父模块包含共享测试工具flink-cdc-e2e-utils容器管理、断言、源端 E2E 测试flink-cdc-source-e2e-tests与管道 E2E 测试flink-cdc-pipeline-e2e-tests文档docs/为基于 Hugo 的文档站点docs/content/存放英文文档docs/content.zh/存放中文文档新增特性时两者都要同步更新。七、编码规范细节Coding StandardsAGENTS.md 对代码风格给出如下强制要求均可与仓库工具链对应提交前用 Spotless 格式化 Java 文件mvn spotless:apply失败时用全限定名见第三节Import 顺序Checkstyle 强制org.apache.flink.cdc→org.apache.flink→ 其他第三方 →javax→java静态导入放最后禁止星号导入禁止使用的 importCheckstyle 强制JUnit 4org.junit.*org.junit.jupiter.*除外——改用 JUnit 5 Jupiterorg.junit.jupiter.api.Assertions与org.hamcrest——改用 AssertJcom.google.common.*——改用flink-shaded-guavacom.google.common.base.Preconditions——改用 Flink CDC 自带的Preconditions见 flink-cdc-commoncom.google.common.annotations.VisibleForTesting——改用org.apache.flink.cdc.common.annotation下的VisibleForTestingAPI 稳定性注解面向用户的 API 类型应携带稳定性注解仅当方法/字段/构造器与所在类型不一致时才需显式标注Public跨大版本稳定PublicEvolving小版本内可能变化Experimental随时可能变化Internal无稳定性保证用户不应依赖。上述注解定义在 flink-cdc-common 的 annotation 包 下包含Public.java、PublicEvolving.java、Experimental.java、Internal.java、VisibleForTesting.java五个文件日志使用 SLF4J 带参数占位符的写法LOG.info(foo {}, bar)禁止字符串拼接大括号if/else/for/while/do一律使用大括号注释全部使用英文且保持简洁仅在必要时书写避免琐碎的param/returnJavadocLicense所有新文件必须带 Apache License 2.0 头。八、测试编写规范Testing StandardsAGENTS.md 对测试的约束非常具体新测试一律使用JUnit 5org.junit.jupiter与AssertJorg.assertj.core.api.Assertions禁止 JUnit 4 与 Hamcrest测试类为包私有类上不加public命名约定单元测试*Test.java例如SchemaUtilsTest集成测试需要 Docker / 真实数据库*ITCase.java例如MySqlSourceITCase新行为必须覆盖成功、失败与边界用例测试应自解释避免冗长注释Bug 修复先确认新测试在无修复时失败红再确认带修复后通过绿以证明测试的有效性。仓库中可观察到这一命名体系的实际落地flink-cdc-common测试目录下既有SelectorsTest.java、TableIdHashFunctionProviderTest.java这类单元测试也有JdbcTableDiscovererITCase.java这类需要真实环境的集成测试参见 flink-cdc-common/src/test。九、提交信息与 Pull Request 约定Commits and PRsCommit message 格式[FLINK-XXXX][component] DescriptionFLINK-XXXX为 JIRA issue 编号component为受影响区域例如connect/mysql、pipeline-connector/kafka、docs、runtime无需 JIRA 的小修复使用[hotfix][component] ...或[docs][component] ...纯 CI 改动使用[ci] Description。Pull Request 约定PR 标题格式与 commit message 保持一致[FLINK-XXXX][component] Title除琐碎改动外必须关联 JIRA issue完整填写 PR 模板目的、变更日志、测试方式、文档影响请求 review 前确保 CI 通过在 fork 上启用 GitHub Actions 再开 PR不得直接 push 上游使用 AI 工具时勾选 AI disclosure 复选框并在 PR 模板中取消注释Generated-by行遵循 ASF Generative Tooling Guidance。十、变更边界先询问与禁止事项BoundariesAGENTS.md 明确划分了动手前必须先确认与绝对禁止两类边界这对 AI 代理尤其关键。先询问Ask first的变更类型新增或修改Public/PublicEvolving注解即面向用户的 API 承诺新增依赖大型跨模块重构变更序列化格式或 checkpoint 行为变更热路径逐记录处理、状态访问从而影响性能。绝对禁止Never提交密钥、凭据或 token直接 push 到apache/flink-cdc必须始终从自己的 fork 工作在一个 PR 中混入无关改动在新测试代码中使用 JUnit 4 或 Hamcrest使用org.junit.jupiter.api.Assertions应改用 AssertJ在 commit message 中添加带 AI 代理的Co-Authored-By应改用Generated-by: Tool Name and Version。结语AGENTS.md 是 Flink CDC 仓库中一份信息密度极高的工程协作契约它同时回答了环境怎么搭、构建怎么跑、测试怎么分、代码怎么写、提交怎么提、边界在哪里六类问题并为 AI 编码代理划出了清晰的责任红线。对贡献者而言将本文梳理的构建命令含-Pflink2双版本策略、JUnit 5 AssertJ 测试规范、Checkstyle/Spotless 工具链与FLINK-XXXX提交格式固化为日常工作流即可与 Flink CDC 的既有工程文化无缝衔接。【免费下载链接】flink-cdcFlink CDC is a streaming data integration tool项目地址: https://gitcode.com/GitHub_Trending/flin/flink-cdc创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 Flink CDC 贡献者开发指南：基于 AGENTS.md 的构建、测试与协作规范深度解析
Flink CDC 贡献者开发指南基于 AGENTS.md 的构建、测试与协作规范深度解析【免费下载链接】flink-cdcFlink CDC is a streaming data integration tool项目地址: https://gitcode.com/GitHub_Trending/flin/flink-cdc本篇指南以仓库根目录的 AGENTS.md 为骨架系统梳理 Apache Flink CDC 面向 AI 编码代理与人类贡献者的协作规范包括构建命令、测试策略、模块结构与编码标准。读完本文你将掌握 Flink CDC 的快速编译方式、Flink 1.x/2.x 双版本兼容构建、JUnit 5 AssertJ 测试编写规范以及提交信息、Pull Request 与变更边界的完整约定可直接用于日常开发与提交审核。一、AGENTS.md 是什么一份写给 AI 编码代理的协作手册AGENTS.md 是 Flink CDC 仓库中专门面向 AI 编码代理AI coding agents的指导文件目标是在 AI 生成代码进入 Apache 开源项目流程时把人与仓库的隐性约定显式化用什么 JDK、怎么编译、怎么测试、代码怎么写、提交怎么提、什么能改什么不能改。它本质上是一份可执行的仓库贡献契约既约束 AI 代理也约束所有参与者确保代码风格、测试口径与流程规范的一致。本文所有命令均以仓库根目录当前仓库flink-cdc根目录为执行起点关键配置项均有仓库源码佐证。二、开发环境前置要求PrerequisitesAGENTS.md 明确列出的环境基线Java 11作为编译基线所有代码必须在 Java 11 上编译运行Java 17用于双版本验证与较新的 Flink 2.x 环境Maven 3.8.6 或更高版本GitUnix-like 环境Linux、macOS、WSLDocker运行集成测试ITCase与端到端测试e2e tests时必需。仓库根 pom.xml 中java.version11、source.java.version11、target.java.version11与上述基线一致同时 Maven Enforcer 插件在构建时强制校验requireMavenVersion [3.1.1,)与requireJavaVersion ${source.java.version}见 pom.xml。pom 中还提供了按 JDK 自动激活的java-11-targetJDK 11~17与java-17-targetJDK 17profile自动切换编译目标。三、构建命令速查BuildAGENTS.md 给出了四类典型构建命令均可直接复制使用# 1. 快速开发构建跳过测试与格式检查追求最快反馈 mvn clean install -DskipTests -Dspotless.check.skiptrue -Dcheckstyle.skiptrue # 2. 针对 Flink 1.x 的完整构建默认 profile mvn clean package -DskipTests # 3. 针对 Flink 2.x 的完整构建 mvn clean package -DskipTests -Pflink2 # 4. 只构建单个模块示例flink-cdc-common-am 表示同时构建其依赖模块 mvn clean package -DskipTests -pl flink-cdc-common -am几个值得注意的仓库级细节-Pflink2profile会切换一组依赖版本如 Kafka 连接器版本、Paimon/Iceberg 的 Flink 主版本见 pom.xml并在测试阶段额外复制 Flink 2.x 的 shaded-guava 到target/flink2-extra-libs加入测试 classpathSpotless 全限定名问题根 pom 中有一条注释明确指出由于 Flink 构建环境设置直接执行mvn spotless:apply/mvn spotless:check可能失效需使用全限定插件名mvn com.diffplug.spotless:spotless-maven-plugin:apply见 pom.xml。AGENTS.md 中mvn spotless:apply的写法在实际执行受阻时可切换为该全限定形式根 pom 通过flatten-maven-plugin与maven-shade-plugin为所有子模块生成固定的dependency-reduced-pom.xml确保${flink.version}在子模块中被解析为实际版本号pom.xml。四、测试命令与测试策略TestingAGENTS.md 提供的测试命令矩阵# 运行某个模块的全部测试 mvn verify -pl flink-cdc-common # 针对 Flink 2.x 运行模块全部测试 mvn verify -pl flink-cdc-common -Pflink2 # 运行单个测试类 mvn -pl flink-cdc-common -DtestMyTest test # 运行单个测试方法 mvn -pl flink-cdc-common -DtestMyTest#myMethod test从根 pom 的 surefire 配置可以印证其运行机制pom.xml默认test阶段只执行**/*Test.java与**/*Test.scala单元测试单独的integration-testsexecution 绑定在integration-test阶段只执行**/*ITCase.java与**/*ITCase.scala需要 Docker / 真实数据库的集成测试为控制 MiniCluster 资源默认forkCount1、reuseForkstrue测试 JVM 追加了大量--add-opens/--add-exports参数并针对 Oracle 时区问题设置了-Doracle.jdbc.timezoneAsRegionfalse。因此如果只想跑单测用mvn test或-Dtest...要跑 Docker 集成测试需要mvn verify或显式触发 integration-test 阶段且本机具备 Docker 环境。五、代码质量与格式化Code QualityAGENTS.md 规定提交前必须执行# 应用代码风格规则如失败改用全限定名见第三节 mvn spotless:apply mvn spotless:checkSpotless基于 Google Java FormatAOSP 风格版本 1.24.0格式化并配置了 import 顺序org.apache.flink, org.apache.flink.shaded, , javax, java, scala, #(静态导入)同时自动移除未使用的 importpom.xmlCheckstyle在validate阶段执行规则文件为 tools/maven/checkstyle.xml包含文件行数上限、禁止尾随空白、禁止Throwables.propagate(、禁止Boolean/Integer/Long.getXxx等规则并提供 tools/maven/suppressions.xml 作为豁免清单License 头所有新增文件必须包含 ASF Apache License 2.0 头根 pom 的 apache-rat-plugin 会在verify阶段强制检查pom.xml。六、仓库结构总览围绕 Pipeline 抽象的模块化设计AGENTS.md 指出Flink CDC 围绕Pipeline 抽象组织代码一条用户定义的管道从一个或多个 Source 读取数据可选地做 transform再写入一个或多个 Sink。核心模块实现这一抽象连接器模块提供具体的源端与目标端实现。核心模块Core Modules模块职责flink-cdc-common跨模块共享的 API 与数据模型CDC 事件类型DataChangeEvent、SchemaChangeEvent等、schema 模型、数据类型、source/sink 接口、FactorySPI、路由定义、UDF 接口与工具类。大多数新抽象从这里开始。flink-cdc-runtimePipeline 的运行时实现读取、路由、transform基于 Calcite Janino 的表达式求值、写出 CDC 事件所需的算子。flink-cdc-composer管道装配与部署层把PipelineDefinition翻译成可运行的 Flink 作业串联 sources/operators/sinks支持 Flink 原生、Kubernetes、YARN 部署。flink-cdc-cli命令行入口flink-cdc.sh解析 YAML 管道定义并委托给flink-cdc-composer。flink-cdc-dist发行打包产出flink-cdc-version-bin发布归档。以 CLI 模块为例源码可以印证这一职责描述CliFrontend.java 是入口类解析命令行参数、打印帮助、创建 executor 并执行CliFrontendOptions.java 定义了全部命令行选项--flink-home、-h/--help、--global-config、--jar、-t/--target支持local、remote、yarn-session、yarn-application、kubernetes-application、--use-mini-cluster、-s/--from-savepoint、-cm/--claim-mode、-n/--allow-nonRestored-state、-D动态覆盖 Flink 配置。管道级全局配置样例可在 flink-cdc.yaml 中找到其核心字段与常见取值如下# 管道并行度 parallelism: 4 # 处理源端 schema change 事件的行为 schema.change.behavior: EVOLVEFlink 版本兼容Flink Version CompatibilityAGENTS.md 强调 Flink CDC 同时支持两代 Flinkflink-cdc-flink1-compat—— Flink 1.x 兼容层当前为1.20.3默认 profileflink-cdc-flink2-compat—— Flink 2.x 兼容层当前为2.2.0通过-Pflink2激活。根 pom.xml 中flink.1.x.version1.20.3、flink.2.x.version2.2.0、flink.version${flink.1.x.version}与此一致。所有依赖 Flink API 的模块必须将 Flink 依赖声明为providedscope并引用${flink.version}占位符由激活的 profile 解析pom.xml。改动请在 Flink 1.20LTS与 Flink 2.x 上分别验证。连接器模块flink-cdc-connect/连接器分为两类Source Connectorsflink-cdc-connect/flink-cdc-source-connectors/面向 DataStream 与 Flink SQL 作业的 CDC 源例如flink-connector-mysql-cdc、flink-connector-oracle-cdc、flink-connector-mongodb-cdc等每个源还配套发布对应的flink-sql-connector-*-cdcshaded 产物Pipeline Connectorsflink-cdc-connect/flink-cdc-pipeline-connectors/面向 YAML API 的管道连接器例如flink-cdc-pipeline-connector-doris、flink-cdc-pipeline-connector-kafka、flink-cdc-pipeline-connector-paimon等。测试模块与文档flink-cdc-e2e-tests/端到端测试父模块包含共享测试工具flink-cdc-e2e-utils容器管理、断言、源端 E2E 测试flink-cdc-source-e2e-tests与管道 E2E 测试flink-cdc-pipeline-e2e-tests文档docs/为基于 Hugo 的文档站点docs/content/存放英文文档docs/content.zh/存放中文文档新增特性时两者都要同步更新。七、编码规范细节Coding StandardsAGENTS.md 对代码风格给出如下强制要求均可与仓库工具链对应提交前用 Spotless 格式化 Java 文件mvn spotless:apply失败时用全限定名见第三节Import 顺序Checkstyle 强制org.apache.flink.cdc→org.apache.flink→ 其他第三方 →javax→java静态导入放最后禁止星号导入禁止使用的 importCheckstyle 强制JUnit 4org.junit.*org.junit.jupiter.*除外——改用 JUnit 5 Jupiterorg.junit.jupiter.api.Assertions与org.hamcrest——改用 AssertJcom.google.common.*——改用flink-shaded-guavacom.google.common.base.Preconditions——改用 Flink CDC 自带的Preconditions见 flink-cdc-commoncom.google.common.annotations.VisibleForTesting——改用org.apache.flink.cdc.common.annotation下的VisibleForTestingAPI 稳定性注解面向用户的 API 类型应携带稳定性注解仅当方法/字段/构造器与所在类型不一致时才需显式标注Public跨大版本稳定PublicEvolving小版本内可能变化Experimental随时可能变化Internal无稳定性保证用户不应依赖。上述注解定义在 flink-cdc-common 的 annotation 包 下包含Public.java、PublicEvolving.java、Experimental.java、Internal.java、VisibleForTesting.java五个文件日志使用 SLF4J 带参数占位符的写法LOG.info(foo {}, bar)禁止字符串拼接大括号if/else/for/while/do一律使用大括号注释全部使用英文且保持简洁仅在必要时书写避免琐碎的param/returnJavadocLicense所有新文件必须带 Apache License 2.0 头。八、测试编写规范Testing StandardsAGENTS.md 对测试的约束非常具体新测试一律使用JUnit 5org.junit.jupiter与AssertJorg.assertj.core.api.Assertions禁止 JUnit 4 与 Hamcrest测试类为包私有类上不加public命名约定单元测试*Test.java例如SchemaUtilsTest集成测试需要 Docker / 真实数据库*ITCase.java例如MySqlSourceITCase新行为必须覆盖成功、失败与边界用例测试应自解释避免冗长注释Bug 修复先确认新测试在无修复时失败红再确认带修复后通过绿以证明测试的有效性。仓库中可观察到这一命名体系的实际落地flink-cdc-common测试目录下既有SelectorsTest.java、TableIdHashFunctionProviderTest.java这类单元测试也有JdbcTableDiscovererITCase.java这类需要真实环境的集成测试参见 flink-cdc-common/src/test。九、提交信息与 Pull Request 约定Commits and PRsCommit message 格式[FLINK-XXXX][component] DescriptionFLINK-XXXX为 JIRA issue 编号component为受影响区域例如connect/mysql、pipeline-connector/kafka、docs、runtime无需 JIRA 的小修复使用[hotfix][component] ...或[docs][component] ...纯 CI 改动使用[ci] Description。Pull Request 约定PR 标题格式与 commit message 保持一致[FLINK-XXXX][component] Title除琐碎改动外必须关联 JIRA issue完整填写 PR 模板目的、变更日志、测试方式、文档影响请求 review 前确保 CI 通过在 fork 上启用 GitHub Actions 再开 PR不得直接 push 上游使用 AI 工具时勾选 AI disclosure 复选框并在 PR 模板中取消注释Generated-by行遵循 ASF Generative Tooling Guidance。十、变更边界先询问与禁止事项BoundariesAGENTS.md 明确划分了动手前必须先确认与绝对禁止两类边界这对 AI 代理尤其关键。先询问Ask first的变更类型新增或修改Public/PublicEvolving注解即面向用户的 API 承诺新增依赖大型跨模块重构变更序列化格式或 checkpoint 行为变更热路径逐记录处理、状态访问从而影响性能。绝对禁止Never提交密钥、凭据或 token直接 push 到apache/flink-cdc必须始终从自己的 fork 工作在一个 PR 中混入无关改动在新测试代码中使用 JUnit 4 或 Hamcrest使用org.junit.jupiter.api.Assertions应改用 AssertJ在 commit message 中添加带 AI 代理的Co-Authored-By应改用Generated-by: Tool Name and Version。结语AGENTS.md 是 Flink CDC 仓库中一份信息密度极高的工程协作契约它同时回答了环境怎么搭、构建怎么跑、测试怎么分、代码怎么写、提交怎么提、边界在哪里六类问题并为 AI 编码代理划出了清晰的责任红线。对贡献者而言将本文梳理的构建命令含-Pflink2双版本策略、JUnit 5 AssertJ 测试规范、Checkstyle/Spotless 工具链与FLINK-XXXX提交格式固化为日常工作流即可与 Flink CDC 的既有工程文化无缝衔接。【免费下载链接】flink-cdcFlink CDC is a streaming data integration tool项目地址: https://gitcode.com/GitHub_Trending/flin/flink-cdc创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考