代码结构分析

1. 项目概览

Aeron 使用 Gradle 构建系统，代码以 Java 为主（~9 万行），C 为独立客户端/驱动实现（~4 万行），C++ 提供示例和性能测试。

aeron/
├── build.gradle              # 根构建脚本（Java 21+，shadow plugin）
├── settings.gradle           # 11 个子模块注册
├── version.txt               # 版本号（如 1.46.9）
├── gradlew / gradlew.bat     # Gradle Wrapper
├── CMakeLists.txt            # C/C++ 构建入口（顶层 CMake）
├── cppbuild                  # C/C++ 构建脚本
│
├── aeron-client/             # ★ 客户端 API（Java + C）
│   └── src/main/
│       ├── java/io/aeron/    # Java 客户端实现
│       └── c/                # C 客户端实现（独立）
│
├── aeron-driver/             # ★ Media Driver（Java + C）
│   └── src/main/
│       ├── java/io/aeron/driver/
│       │   ├── media/        # UDP 传输层
│       │   ├── buffer/       # 日志存储
│       │   ├── status/       # 状态指标
│       │   └── ext/          # 扩展点
│       └── c/                # C 驱动实现（独立）
│
├── aeron-archive/            # ★ 流持久化与回放
│   └── src/main/
│       ├── java/io/aeron/archive/
│       └── c/client/         # C Archive 客户端
│
├── aeron-cluster/            # ★ Raft 共识集群
│   └── src/main/java/io/aeron/cluster/
│
├── aeron-agent/              # ★ 事件日志与监控
│   └── src/main/java/io/aeron/agent/
│
├── aeron-samples/            # 示例程序（Java/C/C++）
│   └── src/main/
│       ├── java/io/aeron/samples/
│       ├── cpp/              # C++ 示例（Ping/Pong/Throughput）
│       └── c/                # C 示例
│
├── aeron-system-tests/       # 系统集成测试
├── aeron-test-support/       # 测试工具类
├── aeron-annotations/        # 自定义注解（@Versioned）
└── aeron-all/                # 合并发布 JAR

2. 模块依赖关系

                    ┌────────────────┐
                    │ aeron-all      │  ← uber JAR (shadow plugin)
                    └───────┬────────┘
                            │ 聚合发布
        ┌───────────────────┼────────────────────┐
        │                   │                    │
  ┌─────▼──────┐   ┌────────▼───────┐   ┌───────▼────────┐
  │ aeron-     │   │ aeron-archive  │   │ aeron-cluster  │
  │ samples    │   │                │   │                │
  └─────┬──────┘   └───────┬────────┘   └───────┬────────┘
        │                   │                    │
  ┌─────▼──────┐           │           ┌────────▼────────┐
  │ aeron-     │◄──────────┼───────────┤ aeron-agent     │
  │ client     │           │           │ (拦截器+日志)    │
  └─────┬──────┘           │           └─────────────────┘
        │                   │
  ┌─────▼──────┐   ┌───────▼────────┐
  │ aeron-     │   │ aeron-archive  │
  │ driver     │   │ (使用client+   │
  └────────────┘   │  driver)       │
                   └────────────────┘

核心依赖链：

aeron-driver → aeron-client：驱动使用客户端定义的协议和 log buffer 结构
aeron-archive → aeron-client + aeron-driver：Archive 是驱动功能的一个客户端
aeron-cluster → aeron-client + aeron-driver + aeron-archive：集群使用所有下层模块
aeron-agent → aeron-client + aeron-driver：监控拦截所有组件事件

3. Java 代码组织

3.1 aeron-client（客户端 API）

Module 入口 settings.gradle:3

包	内容
`io.aeron`	核心客户端 API：Aeron, Publication, Subscription, Image
`io.aeron.logbuffer`	LogBuffer 结构和 term 操作
`io.aeron.protocol`	UDP 协议帧 flyweight 定义
`io.aeron.command`	Client-Driver 命令协议
`io.aeron.status`	状态常量
`io.aeron.exceptions`	异常类型

关键文件：

Aeron.java — 客户端入口，管理所有 Publication/Subscription
Publication.java — 消息发布抽象基类
Subscription.java — 消息订阅
Image.java — 接收端镜像（接收到的流）
ClientConductor.java — 客户端核心协调器
LogBufferDescriptor.java — Term Buffer 元数据布局

3.2 aeron-driver（Media Driver）

Module 入口 settings.gradle:4

包	内容
`io.aeron.driver`	核心驱动：Conductor/Sender/Receiver
`io.aeron.driver.media`	UDP 传输层：Channel/Transport/Poller
`io.aeron.driver.buffer`	Log Buffer 存储
`io.aeron.driver.status`	驱动状态计数器
`io.aeron.driver.ext`	调试/扩展

关键文件：

MediaDriver.java (4842 行) — 驱动入口和配置上下文
DriverConductor.java (3549 行) — 驱动核心协调器
Sender.java (232 行) — UDP 发送 Agent
Receiver.java (365 行) — UDP 接收 Agent

3.3 aeron-archive

Module 入口 settings.gradle:5

ArchiveConductor.java — 持久化存储协调器
Catalog.java — 录制索引
RecordingSession.java — 录制会话
ReplaySession.java — 回放会话

3.4 aeron-cluster

Module 入口 settings.gradle:6

ConsensusModule.java — Raft 共识模块入口
Election.java — Leader 选举
ConsensusModuleAgent.java — 共识引擎
RecordingLog.java — Raft 日志

3.5 aeron-agent

Module 入口 settings.gradle:7

提供事件日志和字节码增强拦截功能，用于调试和监控：

EventLogAgent.java — 事件日志 Agent
DriverEventLogger.java — 驱动事件日志
ArchiveEventLogger.java — Archive 事件日志
ClusterEventLogger.java — Cluster 事件日志

4. C/C++ 代码组织

C 代码与 Java 代码完全独立实现，共享相同的协议和数据结构定义：

4.1 C 客户端 (aeron-client/src/main/c/)

对应的 Java aeron-client 模块：

aeronc.h — C 客户端主头文件
aeron_client.c — C 客户端实现
aeron_publication.c — Publication
aeron_subscription.c — Subscription
aeron_client_conductor.c — 客户端协调器
concurrent/ — Lock-free 数据结构（broadcast, ring buffer, atomic）

4.2 C 驱动 (aeron-driver/src/main/c/)

对应 Java aeron-driver 模块：

aeronmd.h — C 驱动主头文件
aeron_driver_conductor.c — 驱动协调器
aeron_driver_sender.c — 发送端
aeron_driver_receiver.c — 接收端
media/ — UDP 传输层

4.3 C++ 示例 (aeron-samples/src/main/cpp/)

BasicPublisher.cpp — C++ Publisher 示例
BasicSubscriber.cpp — C++ Subscriber 示例
PingPong.cpp — 延迟测试

5. 构建系统

5.1 Gradle（Java 构建）

根脚本 build.gradle 定义：

Java 版本：通过 BUILD_JAVA_VERSION 环境变量或当前 JDK
版本号：从 version.txt 读取
子模块版本：aeronVersion

模块构建由各子模块的独立 build.gradle 控制：

aeron-client 和 aeron-driver 生成独立 JAR
aeron-all 通过 Gradle Shadow plugin 合并所有模块为一个 uber JAR

5.2 CMake（C/C++ 构建）

顶层 CMakeLists.txt 管理 C 客户端、C 驱动、C++ 示例的编译：

BUILD_AERON_DRIVER — 是否构建 C 驱动
BUILD_AERON_ARCHIVE_API — 是否构建 Archive C 客户端
AERON_TESTS — 是否构建测试

构建脚本在 cppbuild / cppbuild.ps1 中封装，自动下载 Google Test、HdrHistogram 依赖。

5.3 版本管理

版本号存储在 version.txt，由 Gradle 和 CMake 分别读取，保证 Java 和 C 版本一致。

6. 测试体系

模块	测试类型	说明
`aeron-client`	Unit Test	核心 API、协议编码、LogBuffer 测试
`aeron-driver`	Unit Test	流控、驱动逻辑、媒体层测试
`aeron-system-tests`	Integration Test	端到端 IPC/UDP 测试、Archive、Cluster
`aeron-samples`	Benchmark	吞吐/延迟基准测试
C tests	Unit Test (Google Test)	C 客户端和驱动独立测试

7. 关键设计决策

决策	说明
Java + C 双语言独立实现	共享协议定义，各自独立实现，无 JNI 依赖
模块拆分精简	仅 11 个 Gradle 模块，职责清晰
aeron-all Uber JAR	通过 Shadow Plugin 合并，方便分发
CMake 与 Gradle 并行构建	C 构建不依赖 Java 构建
system-tests 独立模块	端到端测试独立于单元测试