Проблема именования переменных и структуры зависимостей при работе с JWT-токенами в FastAPI

Столкнулся со следующей архитектурной проблемой при разработке эндпоинта обновления токенов.

Текущая реализация

Имеется эндпоинт для обновления access-токена:

@app.post('/refresh')
@limiter.limit("10/minute")
async def refresh(request: Request, token: str = Depends(check_refresh_token)):
    access_token = create_access_token({"sub": token})
    pass

Зависимость check_refresh_token выполняет валидацию refresh-токена и возвращает username:

def check_refresh_token(token: str = Depends(oauth2_scheme)):
    # логика валидации токена
    return payload.get("sub")

Суть проблемы

Возникает семантическое противоречие:

  • Эндпоинт ожидает параметр с именем token, который по логике должен быть JWT-токеном
  • Однако зависимость check_refresh_token возвращает не токен, а username, извлеченный из payload
  • В теле эндпоинта переменная token фактически содержит username, что создает путаницу при чтении кода: create_access_token({"sub": token})

Возможные решения

Рассматриваю несколько подходов:

  1. Локальное переименование: внутри эндпоинта явно переименовать переменную:
    username = token
    Недостаток: решение точечное, не решает архитектурную проблему.
  2. Возврат полного payload: изменить зависимость на возврат всего payload, а в эндпоинте извлекать нужное поле:
    def check_refresh_token(token: str = Depends(oauth2_scheme)):
    # логика
    return payload

    # В эндпоинте:
    username = token.get("sub")
    Преимущество: более гибко, сохраняется доступ ко всем данным токена.
  3. Использование Pydantic моделей: создать модель для данных токена и возвращать ее экземпляр.

Архитектурный вопрос

Подобные ситуации часто указывают на необходимость:

  • Более четкого разделения ответственности между слоями
  • Улучшения семантики именования переменных
  • Создания специализированных DTO (Data Transfer Objects) для передачи данных между компонентами

Какой подход считается наиболее правильным с точки зрения чистого кода и поддерживаемости FastAPI-приложений? Существуют ли общепринятые паттерны для подобных случаев?