- carry the lab 2 solution over and plan lab 3 (PLAN.md, OpenSpec change instance-id-idempotency) - rename the compose project to mtusi-lab3 and the image to :lab3 - add X-Instance-Id to every response and instance_id to every log record ([app] instance_id, hostname by default) - require Idempotency-Key on POST messages: keys table in Postgres, key and message in one transaction, replay returns the same 201, another body gets 409, TTL from [idempotency] ttl_seconds - send the key from student-tests, k6 scenarios and the skill driver; add idempotency, X-Instance-Id, key race and fault tests Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
98 lines
6.8 KiB
Markdown
98 lines
6.8 KiB
Markdown
---
|
||
paths:
|
||
- "src/api/**"
|
||
- "src/main.py"
|
||
---
|
||
|
||
# Слой API (`src/api/`, `src/main.py`)
|
||
|
||
FastAPI, один процесс на реплику; реплик ≥2 за HAProxy (`balancer.md`).
|
||
Что обязан отдавать HTTP — `.claude/rules/api-contract.md`; здесь — как
|
||
устроен слой.
|
||
|
||
- В памяти процесса нет состояния, от которого зависит ответ: любой
|
||
запрос может прийти на любую реплику. Сессии, данные и ключи
|
||
идемпотентности — в Postgres; глобалы модулей — только клиенты
|
||
хранилищ и неизменяемые значения (`instance_id`, фиктивный хэш
|
||
пароля).
|
||
|
||
## Роутинг
|
||
|
||
| Что | Файл | Путь |
|
||
|---|---|---|
|
||
| health | `routers/health.py` | `/health/live`, `/health/ready` — вне версии, без идентификации, из access-лога исключены |
|
||
| ручки v1 | `routers/v1/<domain>.py` | `/api/v1/<prefix>/...` |
|
||
|
||
- Модуль домена: `router = APIRouter(prefix="/users", tags=["users"])`.
|
||
Вложенный ресурс — префикс с параметром: `message.py` →
|
||
`prefix="/chats/{chat_id}/messages"`. Логгер модуля
|
||
`module="api_<domain>_router"`.
|
||
- Версию задаёт `v1_router` (`API_V1_PREFIX` из `src/utils/constants.py`)
|
||
в `routers/v1/__init__.py`. Регистрация домена — импорт и
|
||
`v1_router.include_router(...)` там, больше нигде.
|
||
- `src/main.py`: `app = FastAPI(...)`, lifespan, middlewares, обработчики
|
||
ошибок (`errors.register(app)`), `include_router` для health и
|
||
`v1_router`. `src/__init__.py` пустой: импорт любого модуля `src` не
|
||
должен поднимать приложение.
|
||
- Новая версия API — пакет `routers/v2/` рядом с v1, v1 не ломать.
|
||
|
||
## Внутри ручки
|
||
|
||
- Ручки и зависимости — только `async def`: драйвер БД асинхронный, а
|
||
синхронная `def` ушла бы в threadpool. CPU-тяжёлую работу (KDF пароля)
|
||
явно выносят в поток (`auth.md`).
|
||
- Ручка: зависимости → вызов сервиса именованными аргументами →
|
||
DTO в модель ответа (`UserOut.model_validate(dto)`, у модели
|
||
`from_attributes=True`). Логики, импортов repo и хранилища здесь нет.
|
||
- Текущий пользователь — `Depends(get_current_user)` из
|
||
`dependencies.py`, по Bearer-токену (`auth.md`). Сервис —
|
||
зависимость-фабрика (`Depends(get_chat_service)`), которая собирает
|
||
его из `AsyncSession`. Сессию БД открывает `get_db_session` из
|
||
глобального `session_factory` (`src/infra/db/session.py`): одна на
|
||
запрос, закрывается после ответа, вся работа с БД ограничена сроком,
|
||
отказ БД — 503 (`infra.md`). Commit делает сервис (`service-layer.md`).
|
||
- Ошибки — доменные исключения из сервиса. `HTTPException` не бросать.
|
||
Статус, `code` и заголовки ответа (`WWW-Authenticate` у 401)
|
||
назначает одна таблица в `errors.py`.
|
||
- Модели запросов и ответов — `src/api/schemas/<domain>.py`, имена по
|
||
схемам контракта (`CreateUser`, `User`, `ChatPage`...). В сервис модели
|
||
API не передавать: разбирать в именованные аргументы или
|
||
`Create<Entity>DTO`.
|
||
- POST создания — `status_code=201` в декораторе; `response_model` —
|
||
модель контракта.
|
||
- `Idempotency-Key` (лаба 3) — параметр ручки `POST` сообщения:
|
||
`Annotated[str, Header(alias="Idempotency-Key", pattern=...,
|
||
max_length=128)]`, шаблон — константа в `src/utils/constants.py`. Так
|
||
он есть в `/openapi.json`, а отсутствие и неверный формат дают 400
|
||
через общий обработчик валидации. В сервис ключ уходит именованным
|
||
аргументом вместе с телом; повтор с тем же ключом отвечает тем же 201,
|
||
что и первый вызов (`api-contract.md`).
|
||
|
||
## Middlewares и обработчики ошибок
|
||
|
||
- Request id: генерируется на каждый запрос, пишется в contextvar
|
||
логгера и в `request.state.request_id` и ставится заголовком
|
||
`X-Request-Id` в ответ.
|
||
- 500 от необработанного исключения формирует `ServerErrorMiddleware`.
|
||
Он стоит снаружи пользовательских middleware, и заголовок из них в этот
|
||
ответ не попадёт. Поэтому обработчик `Exception` в `errors.py` сам
|
||
берёт id из `request.state` и ставит заголовок. Сам он не логирует:
|
||
Starlette после ответа повторно бросает исключение, и traceback пишет
|
||
uvicorn (`logging.md`).
|
||
- Итоговая запись о запросе — одна строка: метод, полный шаблон пути,
|
||
статус, длительность. Без тела, заголовков идентификации и query.
|
||
Логи uvicorn access выключены (`access_log=False`), чтобы не было
|
||
дублей.
|
||
- Полный шаблон пути не брать из `scope["route"].path`: с FastAPI 0.137
|
||
роутеры включаются деревом, и там путь без префикса `include_router`
|
||
(`/chats/{chat_id}` вместо `/api/v1/chats/{chat_id}`). Источник —
|
||
таблица из публичного `iter_route_contexts(app.routes)` в
|
||
`request_context.py`. Структуру роутеров ради логов не менять.
|
||
- `X-Instance-Id` (лаба 3) ставит тот же middleware, что и
|
||
`X-Request-Id`, на каждый ответ, включая health, 404 и 405. Значение
|
||
— `settings.app.instance_id` (по умолчанию hostname процесса, в
|
||
compose — короткий ID контейнера), вычисляется один раз при старте.
|
||
Ответ 500 собирает `ServerErrorMiddleware` снаружи пользовательских
|
||
middleware, поэтому обработчик `Exception` в `errors.py` ставит и этот
|
||
заголовок сам, как `X-Request-Id`.
|