Представляем Forge: конвейер с открытым исходным кодом для создания SDK, CLI, документации и многого другого28.09.2026 16:00

Сегодня мы представляем Forge — новый подход к созданию SDK, интерфейсов командной строки (CLI), документации и библиотек. Forge — это открытый, расширяемый конвейер генерации, который любой желающий может развернуть и запустить бесплатно.

Forge находится на ранней стадии развития, но уже генерирует код, необходимый для cf CLI, а в ближайшие несколько месяцев станет основой для API-документации, SDK и многих других компонентов Cloudflare.

Мы создали Forge, потому что он был нам необходим для того, чтобы относиться к агентам как к нашим клиентам. Теперь мы открываем его исходный код, так как считаем, что у каждого должна быть возможность генерировать все интерфейсы, которые нужны агентам. Раньше CLI, API SDK и MCP-серверы с отличной сопутствующей документацией были нужны только для продуктов для разработчиков. Теперь это базовое требование для любого продукта.

Наш API перерос наши генераторы

API Cloudflare насчитывает более 3 500 операций, а сотни сервисов, обеспечивающих их работу, написаны на самых разных языках программирования, включая Rust, Go, TypeScript и Python. Когда мы приступили к созданию CLI для всего API Cloudflare, включая наши SDK и документацию по API, нам понадобился конвейер генерации кода, способный справиться с таким масштабом. Этот конвейер должен быть достаточно гибким, чтобы работать с разными языками и особенностями рабочих процессов каждой из наших инженерных команд.

Нам нужен был способ снизить накладные расходы на координацию между командами. Когда продуктовая команда Cloudflare вносит изменения в API, у нее должна быть возможность использовать предварительную сборку единого CLI, SDK и сайта документации Cloudflare, сгенерированную до того, как изменения будут объединены и отправлены клиентам. Нам нужен был способ гарантировать, что они случайно не сломают конвейер генерации. И нам требовалась система, которую мы могли бы расширять для генерации не только SDK, но и всего остального — от Cap«n Web до MCP и не только.

Нам требовалось решение, которое генерировало бы превью для каждого пулл-реквеста на фоне сотен репозиториев.

Мы попробовали несколько сторонних облачных продуктов, призванных решить эту задачу, и использовали некоторые из них в продакшене. Ни одно из них не решило нашу проблему полностью, а некоторые и вовсе прекратили свое существование. Одна команда объединяла изменения, которые случайно ломали конвейер генерации, другая обнаруживала это уже на этапе релиза, и мы тратили слишком много времени на преодоление трудностей с помощью облачных инструментов, которые не могли контролировать, координируя изменения между командами и поставщиками.

Так мы начали разработку Forge.

Forge призван решить все эти проблемы: он запускается в CI для API-репозиториев каждой команды, точно так же, как наш рецензент кода на основе ИИ и конвейеры тестирования. Он проводит линтинг каждого изменения, а затем генерирует предварительные сборки CLI, документации и SDK с подсветкой только ваших изменений, которые можно установить для тестирования. Это та же концепция, что и в Workers Previews: полноценная предварительная сборка для каждого изменения, но примененная к генерации SDK в масштбах всей компании, даже когда API распределен по сотням сервисов и репозиториев. Именно это и стремится предоставить Forge.

Forge помогает обнаруживать проблемы в CI до того, как они вызовут неполадки на последующих этапах.

Трансформеры Forge могут генерировать что угодно, включая Cap«n Web

У Cloudflare больше причин, чем у многих других, желать появления генератора, способного выйти далеко за рамки стандартных целевых языков. Cap«n Web — это RPC-система Cloudflare, которая позволяет TypeScript вызывать удаленный API так, будто это локальный метод:

// Authenticate, get the user's ID, fetch their profile, and fetch every friend's profile...
let authed = api.authenticate(apiToken);
let profile = api.getUserProfile(authed.getUserId());
let friends = authed.getFriendIds().map(id => api.getUserProfile(id));

// ...in a *single* request
let [me, myFriends] = await Promise.all([profile, friends]);

Forge позволяет взять спецификацию OpenAPI и напрямую сгенерировать Cap«n Web. Это открывает возможности для генерации привязок (bindings) из Workers к другим API. В конце концов, привязки в среде выполнения Workers реализованы как Workers, предоставляющие RPC-методы.

Это касается не только Cap«n Web: другие популярные инструменты, на которые вы уже можете полагаться, требуют того же самого. Если вы используете TanStack Query, в идеале вам хотелось бы иметь возможность генерировать привязки TanStack Query для вашего приложения прямо из вашего API. Всегда актуальные, всегда проверенные на соответствие вашему реальному API. То же самое справедливо и для генерации схем Zod или Valibot, MCP-серверов или любых других компонентов, упрощающих использование вашего API.

Это стало возможным благодаря гибкости генераторов кода Forge. Они созданы для передачи информации из одного вывода в другой.

Исходное определение OpenAPI встроено в SDK TypeScript, который используется для генерации спецификаций cf CLI и Cap’n Web.

Трансформеры Forge можно объединять в цепочки: генерируйте новые результаты на основе других результатов

Мы спроектировали Forge расширяемым и поддерживающим множество типов входов и выходов. Forge предоставляет генераторы CLI, SDK и документации, но ничто не мешает вам добавить трансформер, который генерирует пакет для конкретной библиотеки или даже полноценную панель управления или приложение. На сегодняшний день Forge поддерживает OpenAPI в качестве входного формата, но мы заложили в него возможность работы с AsyncAPI, GraphQL, Cap«n Proto, Protobuf и другими форматами в будущем.

Речь идет не только о совместимости: это позволяет объединять цели в цепочки, используя выходные данные одной цели для получения других. Это часто встречается в других генераторах, где CLI и цели Terraform создаются на основе Go SDK. Но чего не хватает и что предоставляет Forge, так это возможности для самого пользователя управлять этой системой цепочек.

Forge может объединять цели в цепочки для получения новых результатов.

Нам самим потребовалось решение этой проблемы, поскольку наш собственный cf CLI написан на TypeScript, от которого другие генераторы SDK обычно не выстраивают цепочки для создания CLI. Но наша ситуация заставила нас осознать более глубокую проблему: почему какой-либо инструмент генерации SDK должен принимать это решение за вас? Возможно, вы пишите на Python и хотите, чтобы CLI был написан на Python.

Если вы думаете: «Ну и что, какая разница, на Python он или нет? Код ведь сгенерирован автоматически», то дело в том, что CLI — особенные. CLI часто реализуют локальное поведение, которое не имело бы смысла в SDK. Поведение, которое вы пишете вручную, поскольку оно изначально не поддерживается никакими вызовами API. Например, в cf CLI есть такие команды, как cf dev и cf build, которые добавляются поверх остального сгенерированного вывода. Эти команды должны вызывать API TypeScript из других пакетов, таких как Vite.

А теперь добавим к этому документацию. Если вы генерируете CLI и документацию исключительно на основе спецификации OpenAPI, как внедрить эти написанные вручную команды обратно в документацию, чтобы они описывались наравне с остальными?

Мы не смогли найти существующий инструмент, который делает это сегодня, и тем не менее, это именно то, что нужно для cf. Поэтому мы встраиваем эту возможность прямо в Forge.

Меняйте API, не ломая код пользователей

Forge также подготавливает нас к более эффективному управлению версиями API. API v4 от Cloudflare был единственной мажорной версией нашего API на протяжении 10 лет. С тех пор нам может казаться, что мы не выпускали новых мажорных версий, но по стандартам SemVer мы внесли немало изменений, заслуживающих новой мажорной версии. В то же время несколько операций в нашем API содержат внутренние теги «v2» или идентификаторы «beta», которые давно пережили эту часть жизненного цикла продукта.

После стольких лет существования нашего API v4 мы прекрасно понимаем, что крупный релиз v5 оставит позади многих наших клиентов. Именно поэтому, благодаря тому что Forge постоянно выпускает готовые артефакты, мы работаем над таким подходом к версионированию API, который позволяет выпускать новые мажорные версии без ущерба для старых клиентов или SDK.

Совсем скоро мы поделимся новыми подробностями о наших SDK, включая TypeScript, Rust, Python, Go, PHP и Terraform. Особенно о Terraform. Мы знаем, что обновление любого провайдера Terraform требует особого подхода, и уделим процессу перехода на Terraform максимум внимания.

Критические инструменты должны быть доступны всем

Мы верим, что создание инструментов для работы с API — это важнейшая часть инфраструктуры интернета, и вы должны иметь возможность делать это без необходимости покупать SaaS-продукты. Вы должны владеть своими SDK, CLI и документацией. И если вы их генерируете, то можете делать с ними все что угодно и где угодно, причем бесплатно.

Именно поэтому мы делаем Forge доступным с открытым исходным кодом под мягкой лицензией Apache 2.0. Мы хотим, чтобы люди присоединялись к этому путешествию вместе с нами и вносили свой вклад.

Или нет? Может быть, вы хотите оставить все при себе? Пожалуйста! Вы можете запускать Forge самостоятельно для любых целей, с индивидуальными модификациями, бесплатно и в приватном режиме.

Благодарности: Этот проект также стал возможным благодаря усилиям по проектированию и реализации Дэна Картера (Dan Carter), Стивена Чонга (Steven Chong), Кришны Париталы (Krishna Paritala) и Шелли Джонс (Shelley Jones).

© Cloudflare Blog