Частые вопросы разработчиков и краткие ответы.
Окружение и запуск
Q: Какая версия Python нужна?
A: Python 3.12+. Рекомендуется использовать uv для управления окружением.
Q: Как запустить Identity service локально?
A: См. Local Setup: поднять Docker Compose (PostgreSQL, Redis, Kafka), создать БД, применить миграции Alembic, запустить identity_service.api и отдельно worker для outbox.
Q: Kafka не поднимается / connection refused.
A: Подождать 30–60 секунд после docker-compose up; Zookeeper и Kafka стартуют не сразу. Проверить логи: docker-compose logs kafka.
Q: Где брать переменные окружения?
A: Примеры в Local Setup; реальные значения — из внутреннего хранилища секретов или от тимлида. Файл .env не коммитить.
Код и архитектура
Q: Куда класть новую доменную сущность?
A: В core/<aggregate>/: entities, repositories (протокол), при необходимости domain service. Реализацию репозитория — в infra/repositories/.
Q: Как публиковать событие в Kafka?
A: Через Transactional Outbox: в той же транзакции с бизнес-данными писать запись в outbox_events; worker забирает и шлет в Kafka. См. Event-Driven Patterns.
Q: Можно ли вызывать другой сервис по gRPC из use case? A: В use case — только абстракции (протоколы). Реализацию gRPC-клиента инжектировать в infra и вызывать из use case через интерфейс (например, сервис-адаптер).
Git и процесс
Q: Как оформить коммит?
A: Conventional Commits, одна строка: feat(scope): message. См. Git Workflow.
Q: Pre-commit падает на mypy/ruff.
A: Исправить ошибки локально: ruff check ., ruff format ., mypy src/. Не отключать хуки без согласования.
Q: Нужно ли обновлять документацию в том же MR? A: Если меняются контракты, конфигурация или поведение, важное для других — да. См. Definition of Done.
Тесты
Q: Как запустить только unit-тесты?
A: uv run pytest tests/unit -v. Integration: uv run pytest tests/integration -v (нужен Docker для testcontainers).
Q: Как сгенерировать coverage?
A: uv run pytest tests/unit --cov=src --cov-report=html (при необходимости добавить tests/integration).
Контакты и владельцы
Q: Кто владелец Identity/Credential/…? A: См. Who to Contact и Service Catalog / Owners.
Q: Где смотреть список всех сервисов? A: Service Catalog.
Связанные страницы
- Getting Started — быстрый старт
- Local Setup — настройка окружения
- Git Workflow — ветки и коммиты