OpenAI API для backend: чек-лист безопасной интеграции

Зафиксируйте границу клиента и сервера

Браузер, мобильное приложение и публичный JavaScript не должны видеть RUSSIAAPI_API_KEY. Клиент обращается к вашему маршруту по своей сессии, а backend получает tenant и роль из доверенного контекста. Затем он проверяет размер входа, назначение вызова, разрешённую модель и локальную квоту. Не принимайте от клиента base URL, Authorization или произвольный model ID: иначе техническая интеграция становится каналом использования чужих настроек.

Секрет хранится в environment или менеджере секретов на сервере и отзывается при подозрении на утечку. В логах оставляйте только внутренний request ID, статус, длительность, версию адаптера и нормализованную ошибку. Полный prompt, заголовки, cookie и объект исключения не нужны для обычной поддержки и часто содержат лишние данные.

Проверьте контракт до product rollout

OpenAI-совместимый API — это проверяемая часть контракта, а не обещание каждого endpoint, параметра или model ID. До релиза выполните минимальный server-side smoke test с указанным в текущем каталоге alias. Проверьте код статуса, форму JSON, timeout, отмену и безопасный сценарий, когда поле отсутствует. Не подменяйте ошибку фиктивным успешным ответом: пользователю лучше показать состояние повторной попытки или очереди.

Отдельно задайте допустимую политику повторов. Повторять можно только идемпотентную операцию и только после классификации сбоя; для действия с записью, оплатой или публикацией нужен локальный idempotency key и явное подтверждение. Тестируйте 401/403, 429, network timeout, невалидный JSON и отмену как самостоятельные случаи, не приписывая причину конкретному поставщику без наблюдаемых данных.

Добавьте наблюдаемость и путь остановки

В production начинайте с малого tenant или внутренней тестовой группы. Зафиксируйте метрики: число попыток, p95 длительности, долю нормализованных ошибок и длину очереди — без текста пользователя. Заранее определите порог паузы и владельца решения. Если контракт меняется или проверка перестаёт проходить, выключите маршрут feature flag-ом, сохраните безопасный request ID и вернитесь к последней проверенной конфигурации.

Проверяйте фактический каталог и условия обработки перед значимым изменением. Не обещайте фиксированную стоимость, скорость или доступность модели. Требования к данным, юридические ограничения и правила поставщиков существуют независимо от кода, поэтому команда должна согласовать их до передачи production-данных.

Контрольный список перед релизом

До изменения production сохраните версию адаптера, владельца решения, дату проверки и безопасный способ отключения. Прогоните положительный сценарий на синтетическом входе и отдельные отрицательные случаи: пустое поле, неверный tenant, недоступный alias, timeout и повтор того же запроса. Измеряйте только технические признаки, достаточные для поддержки, а не содержимое пользователя.

После релиза наблюдайте за нормализованными кодами ошибок, длительностью, очередью и долей отменённых операций. Если один из сигналов выходит за заранее согласованный порог, остановите rollout, не расширяйте доступ автоматически и проверьте текущий договорный каталог. Такая дисциплина полезна независимо от выбранной модели и не подменяет требования к данным, авторским правам, согласию или внутреннему контролю.

Server-side пример

Этот минимальный пример рассчитан на Node.js 18+ и защищённый server-side запуск. Он не содержит реального ключа и не утверждает наличие недокументированной функции; перед интеграцией подтвердите текущий маршрут, alias модели и схему payload.

export async function answerFromBackend({ session, text, fetchImpl = fetch }) {
  if (!session?.tenantId || typeof text !== 'string' || text.length > 6_000) throw new Error('invalid_input');
  const model = process.env.RUSSIAAPI_TEXT_MODEL;
  if (!model || !process.env.RUSSIAAPI_API_KEY) throw new Error('server_config_missing');
  const response = await fetchImpl('https://russiaapi.com/v1/chat/completions', {
    method: 'POST', headers: { authorization: `Bearer ${process.env.RUSSIAAPI_API_KEY}`, 'content-type': 'application/json' },
    body: JSON.stringify({ model, messages: [{ role: 'user', content: text }] }), signal: AbortSignal.timeout(15_000)
  });
  if (!response.ok) return { ok: false, status: response.status };
  const data = await response.json();
  return { ok: true, text: String(data?.choices?.[0]?.message?.content ?? '') };
}
// Invoke from a protected backend route; do not expose credentials to clients.

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