API gateway: маршрутизация запросов по классу данных

Короткий ответ: классификация должна быть до вызова модели

Не отправляйте произвольный текст в один и тот же endpoint, а затем пытайтесь объяснить решение по логам. Класс данных определяется на server-side маршруте до формирования запроса: например, synthetic, публичный, внутренний с разрешением и ограниченный. У каждого класса есть описание допустимых полей, владельца, условий теста, разрешённых model ID и поведения при неопределённости. Если приложению не хватает данных для классификации, безопасный исход — запросить подтверждение или не выполнять вызов, а не выбирать более широкий маршрут.

Классы должны быть понятны продуктовой и инженерной команде. «Конфиденциально» без правил бесполезно: укажите, какие признаки переводят объект в этот класс, что нельзя логировать, нужна ли дополнительная проверка и сколько живёт временный файл. Не выдавайте внутреннюю классификацию за правовое заключение. Персональные данные, трансграничная передача, договорные обязательства и требования отрасли оцениваются отдельно. Gateway лишь исполняет утверждённую политику и оставляет технический след решения.

Составьте матрицу классов и действий

Небольшой продукт может начать с четырёх строк: synthetic — только тестовые данные; public — опубликованные материалы; approved-internal — данные с подтверждённым владельцем и назначением; restricted — всё, что требует отдельного процесса. Для каждой строки укажите, разрешён ли внешний вызов, какие поля надо удалить или заменить, какие маршруты допустимы, какие события фиксируются и кто может изменить правило. Не делайте «restricted» синонимом автоматического разрешения: чаще это стоп-сигнал до решения владельца.

Матрица помогает не смешивать возможности gateway и обязательства поставщика. Даже если каталог показывает модель, это не означает, что она подходит для каждого класса, хранится нужным образом или поддерживает требуемые параметры. Сверяйте model ID, документацию и условия именно для выбранного сценария. Не обещайте пользователю фиксированную доступность, цену или место обработки. Вместо этого интерфейс может сообщить: «сценарий требует подтверждения» и сохранить только минимальные метаданные, нужные для дальнейшего решения.

Примените allowlist, минимизацию и server-side ключ

Браузер или мобильный клиент не выбирает provider, base URL и ключ. Он передаёт вашему backend только данные, которые уже прошли локальную валидацию. Backend присваивает tenant, класс, policy version и correlation ID, удаляет неразрешённые поля и выбирает маршрут из allowlist. RussiaAPI key хранится в переменной окружения сервера; в клиенте не должно быть ни секрета, ни возможности подменить класс на более удобный. Отдельная аутентификация пользователя не заменяет проверку класса данных.

Минимизация означает не только убрать поле email. Файловые имена, URL, заголовки, history диалога и логи ошибок тоже могут нести лишний контекст. Для каждого класса составьте schema: какие поля обязательны, какие запрещены, какие можно заменить техническим идентификатором. При проверке schema возвращайте нейтральный код ошибки, а не детали внутренней политики или подсказки обхода. Такой контракт удобен для тестов: можно доказать, что запрещённое поле не дошло до исходящего запроса, не записывая его значение в лог.

Журналируйте решение, но не содержимое запроса

Audit trail должен отвечать на инженерные вопросы: кто вызвал маршрут, какой policy version применён, какой класс получен, был ли запрос разрешён, какой безопасный reason code выдан и какой request_id связан с операцией. Для диагностики обычно достаточно hash или счётчика полей, а не полного body. Хранение текста prompt «на всякий случай» увеличивает риск и часто не помогает понять, почему policy сработала. Срок и доступ к журналу задаются внутренней политикой, а не этим примером.

Просматривайте агрегированные отказы и переопределения: если многие пользователи попадают в restricted из-за одного неоднозначного поля, уточните форму или правила. Если кто-то часто меняет policy, это событие должно быть заметно владельцу. При инциденте связывайте технический журнал с версией кода и тест-кейсом, не пересылая содержимое запроса в общий чат. Это позволяет исправить правило воспроизводимо и не превратить систему наблюдаемости в ещё одну неконтролируемую копию данных.

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

До rollout подготовьте synthetic fixtures для каждого класса: допустимый публичный запрос, запрещённое поле, неопределённая классификация, чужой tenant, неподдерживаемый model ID и timeout. Для каждого ожидайте конкретное server-side действие: разрешить, обезличить, направить на review или отказать. Проверьте, что ключ не появляется в ответе, логах и сборке клиента, а ошибка не раскрывает внутренние маршруты. После изменения policy повторите набор, иначе обновление может тихо открыть ранее заблокированный путь.

Начните с тестового проекта и малой доли согласованных сценариев. Измеряйте время решения, технические отказы, долю запросов на review и ошибки контракта, но не называйте эти числа гарантией соответствия или качества модели. RussiaAPI — независимый API gateway; текущие модели, параметры и условия доступны только в актуальном каталоге и документации. Когда условия обработки неизвестны или требования выходят за рамки технической схемы, остановите маршрут и привлеките владельца процесса. Честная пауза безопаснее, чем автоматическое переназначение чувствительных данных.

Server-side пример

Пример показывает локальную проверку на сервере. Ключи берутся только из окружения; до запуска подтвердите маршрут, model ID и параметры в текущем каталоге RussiaAPI.

const POLICY = {
  synthetic: { routes: ['test'], redact: [] },
  public: { routes: ['standard'], redact: ['email', 'phone'] },
  restricted: { routes: [], redact: ['*'] },
};

export function selectRoute({ dataClass, model, payload }) {
  const rule = POLICY[dataClass];
  if (!rule || rule.routes.length === 0) return { state: 'needs_review' };
  if (!process.env.RUSSIAAPI_MODEL_ALLOWLIST?.split(',').includes(model)) throw new Error('model_not_allowed');
  return { state: 'allowed', route: rule.routes[0], payload: Object.fromEntries(Object.entries(payload).filter(([key]) => !rule.redact.includes(key))) };
}
// Invoke RussiaAPI only after this server-side decision; never expose the API key to the client.

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