Эта страница переведена с английской документации. Команды, идентификаторы и примеры не изменены. Среда выполнения 7.24.4 · SDK 2.6.7. Английский оригинал
Совместимость HTTP и OpenAPI
Статус: действует Область: текущее состояние Последняя проверка: 2026-09-02 Владелец: SDK ax-code
У AX Code два пути интеграции:
Имя пакета JSR ниже готово к выпуску, но ещё не получило первую публичную версию.
- Используйте
@defai-digital/ax-code-sdkдля интеграции приложений на TypeScript и JavaScript первой стороны. - Используйте
@defai-digital/ax-code-sdk/headlessили@defai-digital/ax-code-sdk/grpcдля работы приложений и настольного интерфейса первой стороны. - Используйте
ax-code serveплюс контракт OpenAPI, когда нужен другой язык или граница процесса совместимости. - Используйте транспорт собственного SDK для настольного интерфейса первой стороны, где AX Code владеет обоими концами транспорта.
Путь HTTP/OpenAPI — это инфраструктура совместимости и сгенерированных клиентов. Он позволяет Python, Go, Java, Rust и другим клиентам вызывать тот же API сервера, не обязывая AX Code сопровождать полный официальный пакет для каждого языка. Его не следует считать предпочтительным привилегированным мостом внутри настольного интерфейса первой стороны, когда доступен контракт gRPC или собственный контракт, и он больше не открыт как подпути SDK JavaScript первой стороны.
Выбор пути
| Нужно | Рекомендуемый путь | Зачем |
|---|---|---|
| TypeScript или JavaScript в том же процессе | Адаптер рабочей области исходников createAgent() |
Доступен, только когда закрытый исходный пакет среды выполнения AX Code намеренно разрешим |
| Настольный или собственный интерфейс первой стороны | @defai-digital/ax-code-sdk/grpc |
Более узкий контракт headless, серверный поток, удобные метаданные и сроки, меньше открытия WebView |
| TypeScript или JavaScript с локальным сервером | @defai-digital/ax-code-sdk/headless |
Держит жизненный цикл и проекцию событий типизированными, не открывая полную поверхность SDK HTTP |
| Python, Go, Java, Rust или другая среда | Сгенерировать клиент из packages/sdk/openapi.json |
Повторно использует контракт HTTP без сопровождения пакета первой стороны для каждого языка |
| CI, автоматизация или разовые сценарии | Вызовы HTTP к ax-code serve |
Простая модель развёртывания и лёгкая изоляция процесса |
Что официально сегодня
@defai-digital/ax-code-sdk— SDK TypeScript и JavaScript первой стороны. Его публичные границы приложения —headlessиgrpc.@defai-digital/ax-code-sdk/grpc— необязательный фасад транспорта headless для настольного и собственного кода первой стороны.@defai-digital/ax-code-sdk/headless— SDK жизненного цикла и событий TypeScript и JavaScript первой стороны для границ процесса локального сервера.packages/sdk/openapi.json— снимок OpenAPI для сгенерированных клиентов HTTP.- Сгенерированные клиенты не на JavaScript поддерживаются как интеграции поверх HTTP, но не являются опубликованными пакетами первой стороны, пока нет владельца пакета, проверок и рабочего процесса выпуска.
Базовый поток HTTP
Запустите сервер:
export AX_CODE_SERVER_PASSWORD="$(openssl rand -base64 24)"
ax-code serve --hostname=127.0.0.1 --port=4096Помощник жизненного цикла @defai-digital/ax-code-sdk/headless порождает одноразовый пароль Basic Auth и автоматически подключает возвращённый клиент
с соответствующим заголовком Authorization. Пользователям ручного ax-code serve следует явно задать AX_CODE_SERVER_PASSWORD
и отправлять соответствующий заголовок Basic Auth. Живая документация OpenAPI по /doc и все конечные точки сервера
работают только на loopback.
Помощники сервера под управлением SDK всегда отвергают сетевые имена узлов вроде 0.0.0.0. Устаревший параметр allowNetworkBind
сохранён для совместимости исходного кода, но больше не обходит политику только локального доступа. Оболочкам настольного интерфейса следует предпочитать
@defai-digital/ax-code-sdk/grpc или границу SDK в процессе.
Помощники среды HTTP больше не являются публичными подпутями SDK JavaScript. Пакет всё ещё содержит внутренности сгенерированного клиента,
потому что ими пользуются @defai-digital/ax-code-sdk/headless, запасной путь gRPC через HTTP и устаревший код среды выполнения AX Code, но внешним
интеграциям следует использовать headless, gRPC или клиентов, сгенерированных из снимка OpenAPI, а не импортировать значения среды HTTP
из @defai-digital/ax-code-sdk.
Проверьте здоровье сервера:
curl http://127.0.0.1:4096/global/healthСоздайте сгенерированных клиентов из снимка OpenAPI после проверки снимка как JSON и OpenAPI:
openapi-python-client generate --path packages/sdk/openapi.jsonoapi-codegen -package axcode -generate types,client packages/sdk/openapi.json > axcode.gen.goopenapi-generator-cli generate -i packages/sdk/openapi.json -g java -o ./ax-code-javaОграждения генерации
Считайте документ OpenAPI языково-нейтральным контрактом. Не сопровождайте вручную большие обёртки вокруг отдельных маршрутов, если не нужен небольшой слой удобства.
Закрепляйте версию AX Code и версию сгенерированного клиента вместе. Если схема маршрутов сервера меняется, заново сгенерируйте клиент и выпустите его с ясной заметкой о совместимости.
Держите сгенерированный код отдельно от рукописных помощников. Сгенерированные файлы должно быть легко заменить, а рукописные должны содержать только аутентификацию, значения по умолчанию, повторы и API удобства более высокого уровня.
Сохраняйте поведение границы службы. Клиенты не на JavaScript используют путь сервера HTTP и не получают внутрипроцессный createAgent(), выполнение собственных инструментов JavaScript и утилиты @defai-digital/ax-code-sdk/testing.
Прежде чем повышать сгенерированный клиент до статуса первой стороны, покройте трудные части:
- Валидация OpenAPI выполняется в CI.
- Контрактная проверка запускает
ax-code serveи вызывает представительные маршруты. - Поведение потока или SSE проверяется, если клиент открывает API событий.
- Заголовки области каталога и поведение аутентификации документированы.
- Публикация, версии и владение явны.
Пакет SDK включает лёгкую локальную защиту текущего снимка:
pnpm run check:openapiКоманда уровня пакета также доступна при работе внутри пакета SDK:
pnpm --dir packages/sdk/js run validate:openapiОна проверяет, что packages/sdk/openapi.json — разбираемый JSON, объявляет OpenAPI 3.x и содержит основные маршруты, нужные сгенерированным клиентам.