本文主要介绍PolarDB-SQL（即PolarDB-X CN计算层）代码结构，首先简要回顾PolarDB-X的架构，然后从目录入手介绍各个模块的功能，最后列出一些关键接口便于读者调试代码。 、
一、整体架构
PolarDB-X包含4个核心组件构成，CN（Compute Node）负责计算、DN（Data Node）负责存储、GMS（Global Meta Service）负责管理元数据和提供TSO服务，CDC（Change Data Capture）负责生成变更日志。其中，CN作为服务入口，完成三个任务：
通过MySQL协议接收用户请求，返回结果。
作为分布式查询引擎，兼容MySQL语法，提供分布式事务、全局索引、MPP等特性。
通过RPC协议与DN交互，下发读写指令，汇总结果。
下文将结合CN的三个任务，介绍代码、目录、模块在其中扮演的角色，并给出一些关键接口，便于读者继续探索。
二、代码简介
CN代码托管在GitHub上，划分为polardbx-sql和polardbx-glue两个仓库。MySQL协议实现和分布式查询引擎包含在polardbx-sql仓库中，由于License原因，与DN交互的RPC协议相关代码单独放在polardbx-glue中。
调试代码前，首先需要下载两个仓库的代码。推荐首先下载polardbx-sql代码，然后通过git submodule引入polardbx-glue，这样可以独立提交两个仓库的变更，具体步骤参考contributing文档。
CN是一个多模块的Java项目，模块之间通过接口暴露服务，模块关系记录在pom.xml中，通过mvn dependency:tree命令可以查看全部依赖。
部分接口使用了SPI机制，这部分接口需要在模块的src/main/resources/META-INF/polardbx目录下查看当前模块中使用的具体实现。
关于编译打包，可以参考编译/初始化文档。CN的main方法在polardbx-server模块下的TddlLauncher类中，“Tddl”代表“Taobao Distributed Data Layer”，产生于PolarDB-X 0.5时代，由于类名被关联系统依赖，保留至今。
三、目录与模块
polardbx-sql项目首页中可以看到很多目录和文件，加上重名为polardbx-rpc后加入工程的polardbx-glue，项目根目录下包含13个文件夹，9个文件。其中，代码目录以polardbx开头，docke_build.sh用于本地生成docker镜像，pom.xml是整个项目的工程文件，saveVersion.sh用于打RPM包时生成版本号后缀。
根目录中，每个以polardbx开头的目录，都代表一个独立的模块，以下展开介绍各个模块。
| 模块 | 包 | 简介 |
| polardbx-calcite | – | PolarDB-X优化器基于Apache Calcite框架做了深度定制，该模块用于引入calcite-core的代码，定制代码在polardbx-optimizer模块下 |
| polardbx-calcite | org.apache.calcite.plan.hep | RBO框架 |
| polardbx-calcite | org.apache.calcite.plan.volcano | CBO框架 |
| polardbx-calcite | org.apache.calcite.sql | AST（抽象语法树）节点数据结构 |
| polardbx-calcite | org.apache.calcite.rel | 逻辑计划相关代码，包括数据结构、优化规则、类型系统以及相关工具类等内容，主要包含calcite-core的原始代码，增加的逻辑/物理算子和优化规则放在polardbx-optimizer模块下 |
| polardbx-calcite | org.apache.calcite.rex | 表达式相关代码，主要包含calcite-core的 |
| 表达式相关代码，主要包含calcite-core的原始代码，新增的表达式相关代码放在polardbx-optimizer模块下 | ||
| polardbx-calcite | org.apache.calcite.schema |
org.apache.calcite.schema |
polardbx-common |
– | 工具类模块 |
| polardbx-executor | – | 执行器模块，所有执行器代码都在这里，比如SQL执行代码，MPP执行器，异步DDL引擎，统计信息收集，scaleout，全局二级索引等，内容比较多，后续文章中展开介绍 |
| polardbx-gms | – | 元数据服务模块 |
| polardbx-gms | com.alibaba.polardbx.gms.listener | 后台监听metaDb配置的接口，用于支持CN感知配置变化 |
| polardbx-gms | com.alibaba.polardbx.gms.metadb | 读写schema，table，column，index等元数据的接口，informaction_schema中展示的信息大部分通过这里的接口获取。metaDb是PolarDB-X持久化元数据的系统库 |
| polardbx-gms | com.alibaba.polardbx.gms.privilege | 授权、鉴权、白名单、读写权限信息相关接口 |
| polardbx-gms | com.alibaba.polardbx.gms.sync | CN节点间通信相关接口 |
| polardbx-gms | com.alibaba.polardbx.gms.topology/ha/locality/partition/tablegroup | 数据拓扑相关接口，记录了物理分区分布（topology），leader/follower(ha)，地域（locality），分区（partition），表组（tablegroup）等信息 |
| polardbx-net | – | MySQL客户端/服务器协议相关接口 |
| polardbx-net | http://com.alibaba.polardbx.net | 包含TCP包处理类和与客户端交互的协议接口（包括登陆鉴权、文本协议、Prepared Statement等） |
| polardbx-net | com.alibaba.polardbx.rpc.cdc | CDC组件变更日志传递相关接口 |
| polardbx-net | com.alibaba.polardbx.ssl | SSL相关处理接口 |
| polardbx-optimizer | – | 优化器模块 |
| polardbx-optimizer | com.alibaba.polardbx.optimizer.config.meta | 包含从逻辑/物理计划中收集信息的工具类，比如统计查询引用了哪些列，计算查询的统计信息等 |
| polardbx-optimizer | com.alibaba.polardbx.optimizer.config.schema/table | 库/表元数据相关实现，实现了 org.apache.calcite.schema 中定义的元数据接口 |
| polardbx-optimizer | com.alibaba.polardbx.optimizer.core.datatype | 数据类型相关代码 |
| polardbx-optimizer | com.alibaba.polardbx.optimizer.core.function | 表达式计算相关代码 |
| polardbx-optimizer | com.alibaba.polardbx.optimizer.core. planner |
RBO/CBO优化规则 |
| polardbx-optimizer | com.alibaba.polardbx.optimizer.core.profiler | 执行过程中，收集运行时资源消耗信息 |
| polardbx-optimizer | com.alibaba.polardbx.optimizer.core.rel | 逻辑/物理算子实现，DQL/DML/DDL/DAL语句经过优化器后，转化为物理算子构成的执行计划 |
| polardbx-optimizer | com.alibaba.polardbx.optimizer.core.hint | HINT处理相关代码 |
| polardbx-optimizer | com.alibaba.polardbx.optimizer.core.sequence | 全局唯一ID相关代码 |
| polardbx-optimizer | com.alibaba.polardbx.optimizer.core.rule/sharding | 分区裁剪相关代码 |
| polardbx-optimizer | com.alibaba.polardbx.optimizer.core.view | 内置视图的执行计划节点，主要为information_schema和SHOW指令涉及的视图 |
| polardbx-parser | – | 语法解析模块，基于alibaba/druid内置的parser |
| polardbx-rpc | – | 与DN通信的相关代码 |
| polardbx-rpc | com.alibaba.polardbx.rpc | rpc协议交互代码 |
| polardbx-rpc | com.alibaba.polardbx.mysql.cj | rpc协议数据对象 |
| polardbx-rule | – | 拆分规则模块 |
| polardbx-server | – | 服务入口，将其他模块组织在一起，main方法在该模块中 |
| polardbx-server | com.alibaba.polardbx.cdc | CDC核心控制模块，包括CDC系统库表维护，CDC元数据初始化，CDC DDL打标等内容 |
| polardbx-server | com.alibaba.polardbx.config | 系统配置加载相关代码 |
| polardbx-server | com.alibaba.polardbx.manager | 管理指令相关代码，用于处理从管理端口传入的指令 |
| polardbx-server | com.alibaba.polardbx.matrix | SQL处理内部入口，串联解析，优化，执行流程 |
| polardbx-server | com.alibaba.polardbx.server | 包含main方法和请求处理主流程相关代码 |
| polardbx-server | com.alibaba.polardbx.server.handler | 解析文本协议和LoadData指令的相关代码 |
| polardbx-server | com.alibaba.polardbx.server.response | 部分管控指令的执行代码 |
| polardbx-transaction | – | 事务管理模块，包含分布式事务的实现代码 |
| polardbx-transaction | com.alibaba.polardbx.transaction.async | 异步任务相关代码，包括死锁检测、事务超时、事务日志滚动等 |
| polardbx-transaction | com.alibaba.polardbx.transaction.log |
事务日志相关代码 |
| polardbx-transaction | com.alibaba.polardbx.transaction.tso | TSO服务相关代码 |
四、如何入手
PolarDB-X是一个复杂的系统，代码、接口、模块众多，阅读代码需要一些技巧，推荐先整体后局部的方式。
1.整体了解
和所有SQL数据库一样，CN可以划分为协议层、优化器和执行器三层，阅读代码可以首先从每层的输入输出入手，了解从用户发起读写请求到收到结果的整体流程。下面简单介绍各层的一些关键接口。
1）协议层
协议层实现了MySQL协议，负责建立连接，接收用户发送的数据包，组装成SQL和参数传递给优化器。根据功能，协议层代码可以分为连接管理，数据包解析和协议解析三部分。连接管理和数据包解析代码在polardbx-net模块中，协议解析代码在polardbx-server模块中。
协议层实现了MySQL协议，负责建立连接，接收用户发送的数据包，组装成SQL和参数传递给优化器。根据功能，协议层代码可以分为连接管理，数据包解析和协议解析三部分。连接管理和数据包解析代码在polardbx-net模块中，协议解析代码在polardbx-server模块中。
连接管理的代码可以从建立连接入手了解，入口在NIOAcceptor#accept。
数据包解析是将数据转换为协议数据对象的过程，推荐从文本协议入手了解，入口在AbstractConnection#read。
协议解析是将协议数据对象分发到具体执行逻辑的过程，入口在FrontendCommandHandler#handle。
2)优化器
对SQL的处理包括语法解析，校验（Validate），生成逻辑计划，逻辑计划优化，物理计划优化五个步骤，优化产出物理执行计划，传入执行器。优化器使用了Apache Calcite的RBO/CBO框架，因此优化器框架代码在polardbx-calcite模块中，具体实现在polardbx-optimizer模块中。优化器入口在Planner#plan，以下列出各个步骤的关键接口。
| 步骤 | 接口 |
| 语法解析 | FastsqlParser#parse |
| 校验 | SqlConverter#validate |
| 逻辑计划生成 | SqlConverter#toRel |
| 逻辑计划优化 | Planner#optimizeBySqlWriter |
| 物理计划优化 | Planner#optimizeByPlanEnumerator |
3)执行器
执行器接收到物理执行计划后，首先根据计划类型确定执行模式，包括cursor/local/mpp三种执行模式。不同行模式下每个算子都对应的执行代码可能有差异，因此还需要将算子绑定到执行代码。执行过程会通过RPC接口与DN通信，下发读写请求并汇总结果。以下列出关键接口：
| 步骤 | 接口 |
| 执行器入口 | PlanExecutor#execute |
| 执行模式选择 | ExecutorHelper#execute |
| cursor模式算子绑定到执行代码 | AbstractGroupExecutor#executeInner |
| local模式算子绑定到执行代码 | LocalExecutionPlanner#plan |
| mpp模式切分执行计划 | PlanFragmenter.Fragmenter#buildRootFragment |
| cursor模式与DN通信 | MyJdbcHandler |
| local/mpp模式与DN通信 | TableScanClient |
2.深入了解
要深入了解模块代码，比较好的方式应该是带着问题去看。比如想要了解协议层代码，首先思考最简单的查询select1的处理流程是怎样的，结合前面的模块和接口介绍，跟踪调试后不难得到答案，然后继续思考其他语句/协议类型（比如SET和Prepared Statement）处理起来有何不同？收到/返回的包过大如何处理？SSL如何处理？等等。另外要注意，虽然是深入了解，依然推荐在阅读过程中分清主次，“目录与模块”小节中列出的包建议重点关注，其它包中的内容则可以先快速带过。
3.小结
本文主要介绍CN（Compute Node）代码，涉及polardbx-sql和polardbx-glue两个仓库，目的是帮助读者快速掌握CN代码的整体结构。从功能上看，CN完成三个任务：协议处理、查询优化、与DN交互，代码也因此可以分为协议层、优化器、执行器三部分。文章首先介绍了代码工程的组织形式，列出编译调试相关文档。然后展开各个目录模块对应的功能，便于需要深入了解代码的读者快速定位。最后给出代码阅读建议，并列举各个模块中的关键接口，供读者调试使用。
