ИНСТРУКЦИЯ · 11 МИН. ЧТЕНИЯ

Словарь вайбкодера, часть первая

«Добавь rate limit», «Вынеси в .env», «Оберни в транзакцию». Нейросеть употребляет эти слова так, будто вы их знаете. Здесь — 18 терминов: что означает каждый и чем обернётся его отсутствие.

CI/CD

Процесс, при котором каждое изменение автоматически собирается, проверяется и только после этого публикуется. Вы отправляете код, система выполняет сборку, проверку типов, тесты и релиз. Проверка не пройдена — публикации нет.

Без этого об ошибках часто сообщают пользователи. AI может исправить одно и повредить соседнее. Регулярный запуск тестов помогает обнаружить такие регрессии.

Проверка стоит между изменением и рабочим сервером.

Rate limit

Ограничение числа запросов от адреса или ключа за период. Превышение возвращает код 429. Для входа, оплаты и SMS задаются отдельные лимиты: стоимость запросов различается.

Без лимитов один клиент может занять ресурсы. Также упрощается перебор паролей: тысячи попыток в минуту остаются незамеченными, если их не считать.

Запросы в пределах нормы проходят, остальные получают 429.

Cron

Запуск кода по расписанию: ночью, по вторникам, первого числа месяца. Стандартное расписание задаётся пятью полями: минута, час, день месяца, месяц и день недели.

Cron нужен для списаний подписки, напоминаний, загрузки цен и отчётов, когда никто не нажимает кнопку. Защитите задачу от одновременного запуска на двух серверах, особенно если она списывает деньги.

0 3 * * * — каждую ночь в 03:00. Задачу запускает расписание.

Индексы

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

Без индекса поиск читает записи последовательно. На 300 товарах незаметно, на 300 тысячах может тормозить всю базу. Но индекс на каждом столбце тоже вреден: занимает место и замедляет запись.

Без индекса — перебор 300 тысяч записей. С индексом — быстрый переход к нужной строке.

Миграции

Изменения структуры базы, сохранённые последовательными файлами рядом с кодом: добавить столбец, переименовать таблицу, создать индекс. База учитывает применённые шаги, а новый сервер воспроизводит их по порядку.

Без миграций изменения в рабочей базе трудно отслеживать. Откат возможен только там, где он предусмотрен. Удалённый столбец не восстановится вместе с потерянными данными сам собой.

Шаги 001, 002, 003 выполняются по порядку. Возврат возможен, если для него подготовлена процедура.

Транзакция

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

Без транзакции процесс может остановиться между запросами: деньги списаны, доступа нет. Такое промежуточное состояние обнаружится уже у покупателя.

Внутри транзакции нет частично выполненного результата: либо оба шага, либо ни одного.

Кэш

Сохранение тяжёлого результата для повторной выдачи. Без кэша каталог с ценами и скидками пересчитывается каждому посетителю. С кэшем один расчёт обслуживает множество запросов.

Обратная сторона — устаревшие данные. После изменения цены посетитель может ещё видеть старую. Поэтому кэшу задают срок жизни и сбрасывают его при изменении товара.

Первый запрос считает результат, например 800 мс. Следующие получают готовый ответ за 4 мс.

.env

Файл ключей и паролей рядом с кодом, который не должен попадать в репозиторий. Код читает значения по именам. На компьютере можно хранить тестовый ключ оплаты, на рабочем сервере — рабочий.

Если секрет попал в код и коммит, он оказывается в истории Git. Очистки истории недостаточно: ключ нужно отозвать и заменить.

Ключ в .env остаётся вне репозитория. Ключ внутри закоммиченного кода нужно считать раскрытым.

Хеш пароля

В базе хранится не пароль, а результат одностороннего преобразования. При входе введённый пароль проверяют с помощью того же алгоритма.

Уточните алгоритм: bcrypt и Argon2 подходят для паролей; MD5 и SHA-1 слишком быстры и уязвимы к перебору. Нужна соль — случайное дополнение, благодаря которому одинаковые пароли дают разные хеши.

Одностороннее преобразование не позволяет просто восстановить пароли из базы. При утечке стойкость зависит от алгоритма и качества паролей.

CORS

Правило браузера о том, каким сайтам разрешено обращаться к API. Сервер сообщает разрешённые источники в заголовках, браузер применяет ограничения.

AI иногда устраняет ошибку CORS, разрешая все источники. В рабочем окружении это может создать риск: сторонняя страница обращается к API через браузер пользователя. Проверяйте настройки вместе с авторизацией и защитой запросов.

CORS ограничивает доступ со стороны браузера. Разрешение всем источникам снимает это ограничение и не заменяет проверку прав на сервере.

Webhook

Сервис сам уведомляет о событии: оплате, отмене подписки или отправке посылки. Вы предоставляете endpoint, а сервис отправляет на него запрос с данными события.

Без webhook приходится постоянно опрашивать сервис. Но уведомление тоже может не дойти. Поэтому полезна сверка, например проверка зависших неоплаченных заказов каждые десять минут.

Опрос регулярно задаёт вопрос о состоянии, webhook приходит при событии.

Идемпотентность

Свойство операции сохранять один результат при повторных запросах. По одному ключу сервис возвращает результат первой попытки, не выполняя новую операцию.

Без защиты повторное нажатие может повторно списать деньги. Повторы нормальны: связь пропала, пользователь нажал снова, сервис переслал webhook. Отметка оплаты и выдача доступа должны выполняться однократно.

Один ключ для повторных попыток — одно списание.

Тайм-аут

Предельное время ожидания ответа. Задаётся для обращений к базе, платёжной системе и внешнему API.

Слишком большой тайм-аут удерживает ресурсы и создаёт очередь из-за медленного сервиса. Слишком короткий выдаёт ошибки для ещё работающих запросов. Значение нужно выбирать под операцию.

Обе крайности вредны: ложные ошибки или зависшие обработчики. Нужен подходящий интервал ожидания.

Очередь

Задача добавляется в очередь и выполняется позже: отправка письма, изменение изображения, отчёт или рассылка. Пользователь получает быстрый ответ, а отдельный процесс обрабатывает задания.

Без очереди тяжёлые запросы могут перегружать сайт. Заранее задайте число повторов, интервалы и место хранения окончательно неудачных задач.

Ответ на нажатие приходит сразу, работа выполняется последовательно.

Логи

Записи о работе сервера: время, события и ошибки. Они помогают понять, почему ночью пользователь не смог оплатить.

Логируйте номер заказа, код ответа и этап сбоя. Не записывайте ключи и пароли. Попавший в журнал секрет нужно считать раскрытым.

03:00:01 — создан платёж. 03:00:04 — получен webhook. 03:00:04 — доступ не выдан: отсутствует столбец tier. Именно ради последней строки нужны логи.

Staging

Тестовое окружение, похожее на рабочее: тот же код и структура базы, но отдельные данные и ключи. Изменение сначала проверяют здесь, потом публикуют.

Если сразу публиковать на рабочий сервер, исправлять придётся на реальных пользователях. На staging должны стоять тестовые ключи оплаты: рабочие приведут к настоящим списаниям.

Окружения похожи, но цена ошибки различается. Без staging первым проверяющим становится покупатель.

Резервная копия

Копия базы, создаваемая по расписанию и хранящаяся отдельно от сервера. Копия на том же диске потеряется вместе с ним.

Резервную копию нужно проверить восстановлением. До этого наличие файлов ещё не доказывает возможность вернуть данные.

Надёжность копии подтверждается успешным восстановлением.

Токены

Фрагменты текста, которыми модель измеряет длину: слово, часть слова, знак. Для русского ориентир — 2–3 символа на токен. Оплачиваются и входной текст, и ответ.

При заполнении контекстного окна начало диалога может теряться или сжиматься. Агент возвращает удалённое или забывает договорённости. Сохраните важное в правилах проекта и начните новый диалог.

Когда окно заполнено, ранний контекст может перестать влиять на работу.

В завершение

Не считайте, что агент настроил всё, о чём упомянул. После «Вынести в .env?» он может написать чтение переменных, но не создать их на сервере. Уточняйте, что выполнено и что осталось вам.

Во второй части — Docker, обратный прокси, healthcheck, откат релиза, CDN и WebSocket.

СЛЕДУЮЩИЙ ШАГ

Превратите знания в практику.

В статье — идеи. На живых занятиях в Zoom вы примените их к своему проекту с помощью объяснений, промптов и практики.