Обзор проекта

Чем этот проект отличается от курса «Git Hosting на Go». Там — управляемый практикум: один готовый продукт, и вы шаг за шагом доводите его от 10k до 100k RPS по готовым решениям и trade-offs. Здесь — самостоятельный проект с нуля: вы сами проектируете сервис, пишете ADR и защищаете решения. Git-сервис — лишь сюжет; если хотите тот же сюжет с готовой дорожной картой — берите «Git Hosting на Go», а капстоун делайте на своём проекте.

Что строим

Git-сервис (упрощённый аналог GitHub/GitLab) с возможностями:

• Управление репозиториями (CRUD)
• Pull requests с merge
• Webhooks с HMAC верификацией
• Фоновая обработка (outbox relay, saga orchestrator)
• Наблюдаемость (логи, метрики, трейсы)
• Безопасность (аутентификация, авторизация, секреты)
• Production-ready деплой

Цели Capstone

1. Применить все знания из трёх курсов
2. Построить production-ready сервис с нуля
3. Продемонстрировать понимание архитектуры
4. Защитить технические решения
5. Получить опыт полного цикла разработки

Два варианта реализации

Студент выбирает вариант в зависимости от:

• Предпочтений
• Опыта работы с платформой
• Карьерных целей

Обязательные компоненты (оба варианта)

1. REST API (Course 1-2)

Эндпоинты:

text
POST   /api/v1/repos                    # Создать репозиторий
GET    /api/v1/repos                    # Список репозиториев
GET    /api/v1/repos/{id}               # Получить репозиторий
PUT    /api/v1/repos/{id}               # Обновить репозиторий
DELETE /api/v1/repos/{id}               # Удалить репозиторий

POST   /api/v1/repos/{id}/pulls         # Создать pull request
GET    /api/v1/repos/{id}/pulls         # Список pull requests
POST   /api/v1/repos/{id}/pulls/{pid}/merge  # Слить PR

POST   /api/v1/webhooks                 # Зарегистрировать webhook
POST   /api/v1/webhooks/verify          # Верификация webhook (HMAC)

GET    /healthz                         # Liveness probe
GET    /readyz                          # Readiness probe
GET    /metrics                         # Prometheus метрики

Требования:

• Clean Architecture (handlers -> usecase -> service -> repository)
• DTO для API контрактов
• Валидация запросов (формат + бизнес-правила)
• RFC 7807 Problem Details для ошибок
• Cursor-based пагинация для списков
• OpenAPI спецификация в api/openapi.yaml

2. Database Layer (Course 1-2)

PostgreSQL с таблицами:

text
users (id, email, name, created_at)
repos (id, name, owner_id, is_private, created_at, updated_at)
pull_requests (id, repo_id, title, status, source_branch, target_branch, created_at, merged_at)
webhooks (id, repo_id, url, secret, created_at)
outbox_events (id, type, payload, status, retry_count, created_at, sent_at)
saga_instances (id, type, state, data, current_step, created_at, updated_at)
idempotency_keys (key, user_id, request_hash, status, response_code, response_body, created_at, expires_at)

Требования:

• Миграции через goose (migrations/)
• Repository pattern с интерфейсами
• Транзакции для атомарных операций
• Connection pool с настройкой
• Параметризованные запросы (защита от SQL injection)
• Индексы для частых запросов

3. Background Processing (Course 2)

Фоновые задачи:

text
Outbox Relay
- Читает pending события из outbox_events
- Публикует в Yandex Message Queue
- Обрабатывает retries с exponential backoff
- Перемещает в DLQ после max retries

Saga Orchestrator
- Управляет распределёнными транзакциями (PR merge)
- Выполняет шаги: create_pr -> merge -> notify
- Компенсации при сбое
- Recovery job для stuck sagas

HMAC Rotator
- Ротация HMAC ключей каждые 30 дней
- Двухфазная ротация (current + previous)
- Уведомление команды

Требования:

• Cron scheduling (VDS) или Timer Triggers (Serverless)
• Graceful shutdown
• Метрики: outbox_lag_seconds, saga_duration_seconds
• DLQ с retry API

4. Security (Course 2-3)

Компоненты:

text
Authentication
- JWT токены для API
- Middleware для проверки токенов
- Извлечение user_id в context

Authorization
- RBAC (admin, user, viewer)
- Проверка владения ресурсом
- Middleware RequirePermission

HMAC Signing
- Подпись webhook payloads
- Verification с multi-key support
- Replay protection (timestamp + nonce)

Secrets Management
- Lockbox для секретов (Serverless)
- Environment variables (VDS)
- Ротация через cron job

API Security
- Rate limiting (per user, per IP)
- Input validation
- PII masking в логах
- Security headers

5. Observability (Course 2-3)

Компоненты:

text
Logging
- Structured logging через slog
- JSON формат для production
- Request ID для корреляции
- PII masking
- Audit logging для критичных операций

Metrics (Prometheus)
- RED: requests_total, request_duration_seconds, requests_in_flight
- Business: repos_created_total, prs_merged_total
- Infrastructure: db_pool_usage, outbox_lag_seconds
- SLO: availability, error_rate

Tracing (OpenTelemetry)
- Spans для HTTP handlers
- Spans для database queries
- Spans для external calls
- Propagation через W3C Trace Context
- Sampling 10% для production

Health Checks
- /healthz: liveness (всегда 200)
- /readyz: readiness (проверка БД, NFS)

Alerting
- High Error Rate (>5% за 5 минут)
- High Latency (p99 > 1s за 5 минут)
- Service Down (health check fails)
- Outbox Lag (> 60 секунд)
- SLO Burn Rate (budget conчится за 1 час)

6. Testing (Course 1-2)

Требования к тестам:

text
Unit Tests (покрытие > 70%)
- Domain models с методами
- Services с mock repositories
- Use cases с mock services
- Handlers с httptest

Integration Tests
- Repository с testcontainers (PostgreSQL)
- Миграции
- Outbox relay с реальной БД

E2E Tests
- Полный API workflow
- Создание репо -> PR -> merge
- Webhook верификация

Load Tests (k6)
- Load test: 50 VU, 5 минут
- Stress test: поиск предела
- Thresholds: p99 < 500ms, error rate < 1%

7. CI/CD (Course 3)

GitHub Actions workflows:

text
ci.yml (на каждый PR)
- golangci-lint
- go test -race -cover
- go build
- govulncheck
- gosec

security.yml (ежедневно + на PR)
- Trivy image scan
- gitleaks для секретов

deploy-staging.yml (на merge в main)
- Build Docker image
- Push to registry
- Deploy to staging
- Health check
- E2E tests

deploy-prod.yml (по тегу v*)
- Manual approval
- Deploy to production
- Health check
- Automated rollback если health check fails

8. Documentation (Course 3)

Требования:

text
ADR (минимум 5)
- ADR-01: Выбор архитектуры (Clean Architecture)
- ADR-02: Выбор БД (PostgreSQL vs YDB)
- ADR-03: Outbox pattern vs Direct publish
- ADR-04: Saga orchestration vs Choreography
- ADR-05: Observability stack (Prometheus + Grafana)

Runbooks (минимум 3)
- High Error Rate
- Database Connection Failed
- Outbox Lag

Migration Plans
- Plan для миграции данных при изменении схемы
- Rollback strategy

API Documentation
- OpenAPI спецификация
- Swagger UI

Architecture Diagrams
- C4 Level 1: System Context
- C4 Level 2: Containers

Вариант A: Serverless Implementation

Платформа

Yandex Cloud Functions + Yandex Managed PostgreSQL + Yandex Message Queue

Архитектура

text
API Gateway
    |
    ├── Cloud Function: api (REST API)
    ├── Cloud Function: git-gateway (Git Smart HTTP)
    └── Cloud Function: webhooks (Webhook delivery)

Timer Triggers
    ├── outbox-relay (каждые 5 секунд)
    ├── saga-orchestrator (каждые 10 секунд)
    └── hmac-rotator (каждый день)

Storage
    ├── Yandex Managed PostgreSQL (метаданные)
    ├── Yandex Object Storage (git объекты)
    └── Yandex Message Queue (события)

Специфичные требования

1. Cloud Functions

   • Каждая функция — отдельный бинарник
   • cmd/api/main.go
   • cmd/git-gateway/main.go
   • cmd/webhooks/main.go
   • cmd/outbox-relay/main.go
   • cmd/saga-orchestrator/main.go
   • cmd/hmac-rotator/main.go

2. Timer Triggers

   • Terraform конфигурация для triggers
   • Environment variables для функций

3. Object Storage

   • S3 API для git объектов
   • internal/adapters/s3/storage.go

4. Terraform

   • deploy/terraform/main.tf
   • Все ресурсы описаны декларативно
   • Remote state в Object Storage

5. Cold Start Optimization

   • Минимальный размер функций
   • Connection pooling с keep-alive
   • Lazy initialization

Деплой

bash
# Сборка всех функций
make build-serverless

# Terraform apply
cd deploy/terraform
terraform init
terraform apply

# Проверка
curl https://functions.yandexcloud.net/xxx/healthz

Вариант B: VDS Implementation

Платформа

Yandex Cloud Compute (VDS) + Yandex Managed PostgreSQL + Yandex Message Queue

Архитектура

text
Nginx (reverse proxy)
    |
    v
git-server (single binary)
    ├── HTTP server (REST API + Git Smart HTTP)
    ├── Outbox relay worker
    ├── Saga orchestrator worker
    └── HMAC rotator worker

Storage
    ├── Yandex Managed PostgreSQL (метаданные)
    ├── NFS (git объекты)
    └── Yandex Message Queue (события)

Специфичные требования

1. Single Binary

   • cmd/app/main.go с subcommands:
     • git-server serve (HTTP server)
     • git-server worker (background workers)
     • git-server migrate (миграции)
     • git-server fsck (проверка целостности)
     • git-server version

2. Systemd Units

   • /etc/systemd/system/git-server.service
   • /etc/systemd/system/git-server-worker.service
   • Graceful shutdown
   • Auto-restart on failure

3. NFS для Git

   • internal/adapters/nfs/storage.go
   • POSIX file operations
   • Git fsck для проверки целостности

4. Docker

   • Multi-stage Dockerfile
   • Non-root user
   • Health checks
   • docker-compose.yml для локальной разработки

5. Ansible

   • deploy/ansible/playbook.yml
   • Роли: app, nginx, monitoring
   • Templates для конфигов

6. Prometheus + Grafana

   • Prometheus scraping /metrics
   • Grafana dashboards
   • Alertmanager для алертов

7. Loki для логов

   • Promtail для сбора
   • Correlation через trace_id

Деплой

bash
# Сборка бинарника
make build-vds

# Docker image
docker build -t registry.example.com/git-server:v1.0.0 .
docker push registry.example.com/git-server:v1.0.0

# Terraform для инфраструктуры
cd deploy/terraform
terraform apply

# Ansible для конфигурации
cd deploy/ansible
ansible-playbook -i inventory.yml playbook.yml --limit staging

# Проверка
curl https://staging.example.com/healthz

Quiz "Проверь себя"

outbox_events (status=pending)
  -> publish to Yandex Message Queue
  -> retries with exponential backoff
  -> DLQ after max retries

Критерии приёмки

Обязательные (must have)

• REST API работает, все эндпоинты отвечают
• PostgreSQL с миграциями
• Clean Architecture соблюдена
• Unit тесты > 70% покрытия
• Integration тесты для repository
• Outbox relay работает
• Saga orchestrator работает
• HMAC signing/verification
• JWT authentication
• Rate limiting
• Structured logging с request ID
• Prometheus метрики (/metrics)
• Health checks (/healthz, /readyz)
• OpenAPI спецификация
• CI pipeline (lint, test, build)
• Docker image (VDS) или Cloud Functions (Serverless)
• Минимум 5 ADR
• Минимум 3 runbooks

Желательные (nice to have)

• E2E тесты
• Load testing с k6
• OpenTelemetry tracing
• Grafana dashboards
• Alertmanager с Slack уведомлениями
• GitOps (ArgoCD или Flux)
• CD pipeline (staging + production)
• Automated rollback
• Performance profiling (pprof)
• Security scanning в CI (Trivy, gosec, govulncheck)

Бонусные (extra credit)

• Multi-tenancy
• Read replicas
• Caching (Redis)
• Bulk operations
• Webhook delivery с retries
• API versioning (v1 + v2)
• Feature flags
• Chaos engineering experiments

Процесс защиты проекта

Этап 1: Подготовка (неделя 1-2)

1. Выбор варианта (Serverless или VDS)
2. Настройка репозитория
3. Реализация core functionality
4. Настройка CI pipeline

Этап 2: Реализация (неделя 3)

1. Background processing (outbox, saga)
2. Security (auth, HMAC, rate limiting)
3. Observability (logs, metrics, traces)
4. Documentation (ADR, runbooks)

Этап 3: Деплой и тестирование (неделя 4)

1. Деплой в staging
2. Load testing
3. Исправление багов
4. Подготовка к защите

Этап 4: Защита (30-45 минут)

Структура защиты:

text
1. Презентация (15 минут)
   - Архитектура (C4 диаграммы)
   - Ключевые решения (ADR)
   - Demo работающего сервиса
   - Observability (Grafana dashboards)

2. Q&A (15 минут)
   - Вопросы по архитектуре
   - Вопросы по реализации
   - Сценарии сбоев (что если...)
   - Масштабирование и эволюция

3. Code review (15 минут)
   - Review 2-3 ключевых файлов
   - Объяснение дизайна
   - Альтернативные подходы

Вопросы на защите

Архитектура:

• Почему выбрали Clean Architecture?
• Какие альтернативы рассматривали?
• Как будете масштабировать?

Реализация:

• Как работает outbox pattern?
• Как реализована saga?
• Как обрабатываете частичные сбои?

Operations:

• Что делать при High Error Rate?
• Как ротируете секреты?
• Как восстанавливаете после сбоя?

Security:

• Как защищаете от SQL injection?
• Как работает HMAC verification?
• Что если JWT токен украден?

Performance:

• Какой bottleneck в системе?
• Как оптимизировали запросы к БД?
• Что показали результаты load testing?

Оценка проекта

Критерии оценки

Уровни оценки

Финальная ретроспектива

Вопросы для студента

1. Что было самым сложным?
2. Что нового узнал?
3. Какие решения оказались правильными?
4. Что бы сделал иначе?
5. Какой совет дал бы себе в начале трека?

Вопросы для ментора

1. Сильные стороны проекта?
2. Области для улучшения?
3. Готов ли студент к production работе?
4. Рекомендации по дальнейшему развитию?
5. Какие навыки нужно развивать дальше?

Что дальше после Capstone

Для студента

1. Production опыт

   • Мониторинг в реальной эксплуатации
   • Реагирование на инциденты
   • Эволюция системы

2. Развитие навыков

   • Kubernetes (если VDS)
   • Service mesh (Istio)
   • Advanced observability (eBPF)
   • FinOps и cost optimization

3. Карьерные возможности

   • Senior Go Developer
   • Backend Tech Lead
   • Platform Engineer
   • Solutions Architect

Для ментора

1. Feedback по треку

   • Что работало хорошо?
   • Что нужно улучшить?
   • Какие модули добавить/убрать?

2. Кейсы для улучшения

   • Реальные инциденты из capstone
   • Паттерны которые использовали студенты
   • Проблемы с которыми столкнулись

Итог трека

Что освоил студент

Курс 1: Go Foundation

• Синтаксис Go и идиомы
• Базовые паттерны
• Тестирование
• HTTP серверы
• PostgreSQL

Курс 2: Go Backend Developer

• Clean Architecture
• REST API design
• Background processing
• Observability
• Security

Курс 3: Go Service Architect

• Distributed systems patterns
• Reliability engineering
• Performance optimization
• CI/CD и infrastructure as code
• Architecture documentation

Capstone Project

• Production-ready сервис
• Полный цикл разработки
• Защита технических решений
• Операционная готовность

Competency matrix

Готовность к production

Студент готов:

• Работать в production codebase
• Проектировать новые сервисы
• Реагировать на инциденты
• Принимать архитектурные решения
• Менторить junior разработчиков

Поздравляем!

Вы завершили полный трек Go API Service Development!

Теперь вы:

• Пишете идиоматичный Go код
• Проектируете production-ready сервисы
• Понимаете distributed systems
• Умеете работать с observability
• Обеспечиваете security
• Автоматизируете CI/CD
• Документируете решения

Следующие шаги:

1. Продолжайте развивать свой capstone проект
2. Мониторьте его в production
3. Применяйте знания в реальных проектах
4. Делитесь опытом с командой
5. Развивайтесь в направлении Senior/Staff Engineer

Удачи в вашем пути Go Service Architect! 🚀