Лучшие практики

Границы модулей

• Один класс route-модуля на основной ресурс
• Импортируйте route-модули из точки входа только ради побочных эффектов регистрации
• Выносите общую логику в library-пакеты вместо перекрёстных импортов между route-модулями

Именование

• Предпочитайте имена классов *Module, чтобы стемы [module] оставались читаемыми
• Предпочитайте имена методов *Action при использовании [action]
• Следуйте рекомендациям CLI по именам пакетов (fusion_<name>_mod / fusion-<name>-mod)

Конфигурация

• Храните секреты в переменных окружения, на которые ссылается JSON (плейсхолдеры ALL_CAPS), или в менеджере секретов
• Используйте отдельные файлы fusion.dev.json / fusion.prod.json
• Отключайте Swagger в production, если публичный UI документации не нужен

Middleware

• Выносите сквозные задачи (логирование, разбор auth) в глобальный middleware
• Ставьте область авторизации (roles=...) на те маршруты, которым она нужна
• В production всегда передавайте реальный callback verify для JWT — декодирование по умолчанию не проверяет подпись

Маршрутизация

• Используйте version= для ломающих изменений API и версии в navbar Swagger
• Предпочитайте токены ([module], {id}) дублирующимся жёстко прошитым путям
• Держите handlers тонкими; бизнес-логику вызывайте через хелперы/пакеты

Тестирование

• Юнит-тестируйте чистые хелперы в library-пакетах
• Ориентируйтесь на тесты фреймворка (test_http_route.py, test_middleware.py в репозитории framework)
• Smoke-тесты через Swagger UI или HTTP-клиенты против fusion command run:dev

Безопасность

• Не выставляйте debug-настройки или Swagger с ослабленной auth в production без явного намерения
• Валидируйте path/query/body; при неверных типах Python-коэрция возвращает 400
• Санитизируйте имена файлов перед header.download(...) / хелперами вложений