Промт для создания REST API на Python с FastAPI и документацией
FastAPI — удачный выбор для работы с ИИ: типы в сигнатурах и схемы Pydantic дают модели строгий каркас, в который трудно написать ерунду. Документация при этом генерируется сама, что снимает целый класс задач.
Но по умолчанию модель выдаёт учебный пример: один эндпоинт, словарь вместо базы, никакой обработки ошибок. Чтобы получить работающий код, каркас надо задать в промте.
Промт для ресурса целиком
Ты — backend-разработчик. Напиши CRUD для ресурса [название] на FastAPI. КОНТЕКСТ: Python [версия], FastAPI, SQLAlchemy [версия], PostgreSQL. Аутентификация уже есть, зависимость get_current_user возвращает объект User с полями [перечислить]. МОДЕЛЬ: [поля, типы, обязательность, ограничения] ТРЕБОВАНИЯ: 1. Отдельные схемы Pydantic: Create, Update, Response. В Response не отдавать внутренние поля [перечислить]. 2. Валидация на границе: длины строк, диапазоны чисел, форматы. Ошибка валидации — 422 с указанием поля. 3. Коды ответов явно: 201 на создание, 204 на удаление, 404 если нет, 409 на конфликт уникальности, 403 если чужой объект. 4. Список — с пагинацией через limit/offset, максимум limit = 100, и с общим количеством в ответе. 5. Частичное обновление через PATCH, не подменяя незаданные поля на None. 6. Никаких блокирующих вызовов в async-функциях. Работа с БД — через сессию, переданную зависимостью. 7. Каждый эндпоинт с описанием и примером в docstring — они попадут в OpenAPI. ЧЕГО НЕ ДЕЛАТЬ: - не изобретать структуру проекта, использовать: routers/, schemas/, models/, services/; - не писать бизнес-логику в обработчике маршрута, выносить в сервис; - не ловить голый Exception.
Пункт пятый ловит частую ошибку: наивная реализация PATCH затирает поля, которые клиент не присылал. В Pydantic это решается через exclude_unset, и об этом надо попросить прямо.
Что попросить следом
| Запрос | Что получаете |
|---|---|
| «Опиши ошибки единым форматом» | Общий обработчик исключений и предсказуемое тело ошибки |
| «Добавь фильтры и сортировку в список» | Параметры запроса с валидацией допустимых полей сортировки |
| «Напиши тесты через TestClient» | Проверка кодов, валидации и прав доступа |
| «Что сломается при 100 запросах в секунду» | Список узких мест: N+1, отсутствие индексов, синхронные вызовы |
Документация
OpenAPI FastAPI собирает сам, но по умолчанию она бедная. Отдельный промт:
Дополни эндпоинты метаданными для OpenAPI: summary и description для каждого маршрута, description для каждого поля схем, примеры запроса и ответа через Field(examples=...), описание всех возможных кодов ответа через responses=, теги для группировки маршрутов. Тексты пиши так, чтобы их читал сторонний разработчик, не знакомый с нашей предметной областью.
Последняя фраза важна. Без неё описания получаются в стиле «Создаёт объект» — то есть повторяют название метода и не добавляют ничего.
Что проверять руками
- N+1 в списке. Модель почти всегда забывает про
selectinloadдля связанных объектов. - Права на чужой объект. Проверка владельца часто оказывается только в GET и отсутствует в PATCH и DELETE.
- Транзакции. Где начинается и заканчивается — модель об этом обычно не думает.
- Версии библиотек. Синтаксис Pydantic и SQLAlchemy заметно менялся между мажорными версиями; несоответствие даёт код, который не запустится.
И общее правило: сгенерированный эндпоинт — это черновик, который надо прочитать целиком. Он выглядит законченным гораздо раньше, чем становится таковым, и в этом основная ловушка.