Apache Flink — большой проект. На май 2026 в репозитории apache/flink около 2.8 миллиона строк Java и Scala кода, более 200 maven-модулей, около 4 тысяч контрибьюторов в истории. Если вы первый раз открываете этот код, можно растеряться: куда смотреть, чтобы найти, как работает checkpoint? Где живёт RocksDB-интеграция? Что такое модули flink-runtime и flink-runtime-web и в чём разница?

Этот урок — практический tour. К концу вы будете знать структуру репозитория достаточно, чтобы за минуты находить нужный код. Это не разовый навык — это ежедневный инструмент Flink-инженера. Большинство ответов на ваши production-вопросы находятся в коде, а не в документации.

Где взять source code

git clone https://github.com/apache/flink.git
cd flink
git checkout release-2.2

Для tour лучше использовать релизный tag, потому что master постоянно меняется. На май 2026 актуальная ветка — release-2.2. Если вы работаете с другой версией — git checkout release-1.20 для предыдущей LTS, и так далее.

Опционально клонируйте параллельно три связанных репозитория:

git clone https://github.com/apache/flink-kubernetes-operator.git
git clone https://github.com/apache/paimon.git
git clone https://github.com/apache/fluss.git

Это не core-Flink, но они важны: K8s operator — рекомендуемый deployment-механизм, Paimon — lakehouse-формат для Flink streaming-tables, Fluss — stream-storage layer (бывший Flink Table Store + новая архитектура).

Структура корня репозитория

После клонирования вы видите много директорий. Не все одинаково важны.

Если бы нужно было выбрать три модуля для изучения первыми — это flink-runtime, flink-streaming-java и flink-state-backends. В них живёт основная масса того, что вы будете дебажить в проде.

flink-runtime: сердце Flink

flink-runtime — самый большой и самый важный модуль. Около 600 тысяч строк кода. Внутри — десятки подпакетов, и навигация в них требует mental map.

Главное правило навигации: большинство классов в flink-runtime имеют имя, по которому можно догадаться, что они делают. CheckpointCoordinator — координирует чекпоинты. TaskExecutor — исполняет таски. SlotManager — управляет слотами. Это упрощает поиск: открыли IDE, Cmd-O / Ctrl-N, набрали Checkpoint, увидели 50 классов, нашли что нужно.

flink-streaming-java: DataStream API

Этот модуль — это то, что вы используете каждый день, если пишете DataStream-программы. Здесь живут:

Главный поток понимания: ваш DataStream-код -> StreamGraph (api.graph) -> JobGraph (flink-runtime/jobgraph) -> ExecutionGraph (flink-runtime/executiongraph). На runtime каждая ExecutionVertex становится Task, который запускается через StreamTask#invoke() (runtime.tasks). Внутри StreamTask вызывает operator.processElement() на каждом элементе из input channel.

flink-table: Table и SQL

Это самостоятельный мир. Если вы только DataStream-разработчик, этот модуль для вас второстепенен. Если SQL-инженер — это ваш main фокус.

Структура:

Главный класс — org.apache.flink.table.planner.delegation.PlannerBase. Сюда уходит ваш SQL. Внутри он использует Apache Calcite для синтаксического анализа, построения логического плана, применения optimizer rules (Calcite Volcano planner) и финального code generation. На выходе — код на Java, который JIT-компилируется в runtime и исполняется.

В модуле 09 разберём этот pipeline до деталей.

flink-state-backends: state storage

Здесь живут конкретные state backend implementations. На 2026 их три основных:

Главный класс RocksDB-backend — org.apache.flink.state.rocksdb.RocksDBKeyedStateBackend. Снимок (snapshot) — через RocksIncrementalSnapshotStrategy. ForStDB живёт по аналогичному паттерну в flink-statebackend-forst. В модулях 05 и 10 разберём.

flink-kubernetes-operator: deployment

Отдельный репозиторий: https://github.com/apache/flink-kubernetes-operator. На 2026 это рекомендуемый способ deployment Flink на K8s. Старая native K8s интеграция (flink-kubernetes в core) считается legacy.

Operator управляет:

• FlinkDeployment CRD — описывает кластер (JM + TM).
• FlinkSessionJob CRD — описывает job в существующем session-кластере.
• Lifecycle: запускает JM/TM как pods, мониторит, рестартит при сбое, делает savepoint upgrades.

Главный controller-класс — org.apache.flink.kubernetes.operator.controller.FlinkDeploymentController в репозитории flink-kubernetes-operator.

В модуле 21 (Capstone) разберём, как построить полноценный production platform на этом operator-е.

FLIP: как читать предложения по дизайну

FLIP (Flink Improvement Proposal) — это форма design document. Каждая значимая фича Flink начинается с FLIP-документа, который обсуждается на dev@flink mailing list, голосуется, и потом имплементируется.

Список всех FLIP: https://cwiki.apache.org/confluence/display/FLINK/Flink+Improvement+Proposals

На 2026 их около 540. Несколько ключевых для нашего курса:

Как читать FLIP: открываете confluence-страницу FLIP-N, видите структуру: Motivation -> Public Interfaces -> Proposed Changes -> Compatibility/Migration Plan -> Test Plan -> Rejected Alternatives. Самая ценная часть — Rejected Alternatives: там описано, какие были обсуждены подходы и почему не выбраны. Это даёт глубочайший контекст для понимания дизайн-решений.

Как навигироваться по коду эффективно

Несколько практических приёмов.

1. IDE setup

Используйте IntelliJ IDEA. Откройте проект как Maven (если IDE не подтянул автоматически — File -> Open -> выберите root pom.xml). Это позволит делать Cmd-O (поиск класса), Cmd-Alt-B (find usages), Cmd-B (go to definition). Без IDE навигация по 2.8M строкам становится мучением.

2. Поиск по конкретным методам

Если знаете, что в логах видели сообщение типа Triggering checkpoint 12345 for job ..., поиск этой строки даст вам класс, который её генерирует:

grep -rn "Triggering checkpoint" --include="*.java" .

Скорее всего вы попадёте в CheckpointCoordinator#triggerCheckpoint.

3. Trace через interfaces

Многие ключевые компоненты Flink — это interfaces с несколькими implementations:

• Scheduler -> DefaultScheduler, AdaptiveScheduler, AdaptiveBatchScheduler
• StateBackend -> HashMapStateBackend, EmbeddedRocksDBStateBackend, ForStStateBackend
• RpcGateway -> много подклассов

Если хотите понять, как что-то работает, начните с interface (он маленький), посмотрите method signatures, потом выберите конкретный implementation для глубокого разбора.

4. Smoke tests как примеры

В flink-tests лежит много end-to-end тестов. Если непонятно, как использовать какой-то API — найдите тест, который его использует. Например, тест для checkpoint API: flink-tests/src/test/java/org/apache/flink/test/checkpointing/CheckpointStorageCheckpointingITCase.java.

5. Git blame для исторического контекста

Когда видите код, который вас удивляет (if (someComplexCondition)), сделайте git blame на соответствующую строку. Найдёте commit, найдёте PR (обычно [FLINK-NNNNN] в commit message), найдёте Jira-тикет, найдёте обсуждение. Это часто отвечает на “почему?”.

Параллельные репозитории

Помимо core apache/flink, есть несколько важных репозиториев, с которыми вы будете работать:

С 1.17 core-Flink перестал хостить большинство connectors внутри monorepo. Connector-релизы теперь независимы от core-Flink-релизов. Это значит, что у flink-connector-kafka своя версия (например, 3.2.0), и она ставится отдельно как dependency.

Глобальный workflow с source code

Типичный workflow Flink-инженера, который дебажит production:

1. Видит проблему в production: метрика, лог, ошибка.
2. Открывает курс, находит соответствующий раздел.
3. Курс ссылается на класс (CheckpointCoordinator).
4. Открывает класс в IDE, читает.
5. Если нужно — find usages на метод, проходит call chain.
6. Если непонятно — git blame -> PR -> Jira -> дискуссия -> понимание.

Это — норма. Никакая документация не даст такого уровня деталей. Source code — единственная истина.

Что дальше

Это был последний урок модуля 00. Дальше — модуль 01: философия Flink internals. Там разберём:

• “Stream first, batch is bounded stream” — почему именно так, и как это влияет на runtime-архитектуру.
• State и time как first-class citizens — историческая перспектива из Storm/MillWheel/Dataflow.
• Эволюция Flink: что было удалено в 1.x -> 2.x, какие фичи добавлены, почему.

После модуля 01 — фундаментальный блок: архитектура (02), network (03), memory (04), state (05), checkpoint (06), savepoints (07), watermarks (08).