Автоматическая генерация TypeScript типов¶

Система автоматической генерации TypeScript типов из Go структур для проекта Saga.

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

backend/shared/models/*.go
          ↓
   backend/cmd/typegen/
          ↓
frontend/shared/types/generated-types.ts
          ↓
   frontend/shared/types/unified-types.ts
          ↓
   frontend/{user-app,admin-app}/

Компоненты системы¶

Go Type Generator (backend/cmd/typegen/main.go)
Анализирует Go структуры через reflection и AST
Конвертирует Go типы в TypeScript интерфейсы
Генерирует файл generated-types.ts
Unified Types (frontend/shared/types/unified-types.ts)
Экспортирует сгенерированные типы
Добавляет frontend-специфичные типы
Обеспечивает обратную совместимость
Build Integration
Автоматическая проверка при make build-container и make build
Make команды для ручного управления
Скрипты для мониторинга изменений

Использование¶

Автоматическая генерация¶

Типы автоматически проверяются и обновляются при:

# Запуск полной системы (рекомендуемый способ)
make build-container  # Включает генерацию типов, собирает и запускает единый контейнер

# Альтернативно для отдельных компонентов через Makefile:
make build     # Сборка всех компонентов

Ручная генерация¶

# Генерация типов из Go структур
make generate-types

# Проверка совместимости с frontend
make types-check

# Мониторинг изменений в Go файлах
make types-watch

# Обновление через скрипт
./scripts/update-types.sh
./scripts/update-types.sh --force      # Принудительная генерация
./scripts/update-types.sh --show-diff  # Показать изменения

Интеграция в разработку¶

// Проверка типов через Node.js скрипт
node frontend/shared/scripts/check-types.js
node frontend/shared/scripts/check-types.js --force   # Принудительная генерация
node frontend/shared/scripts/check-types.js --quiet   # Тихий режим (только exit code)

Конфигурация типов¶

Маппинг Go → TypeScript¶

Go тип	TypeScript тип	Примечание
`string`	`string`
`bool`	`boolean`
`int`, `int64`, `float64`	`number`
`time.Time`	`string`	ISO 8601 формат
`decimal.Decimal`	`string`	Денежные суммы как строки
`[]Type`	`Type[]`	Массивы
`map[string]Type`	`Record<string, Type>`	Объекты
`*Type`	`Type?`	Опциональные поля
`interface{}`	`any`
`JSONB`	`Record<string, any>`	PostgreSQL JSONB

Специальная обработка¶

Денежные поля: decimal.Decimal → string для точности вычислений
Временные метки: time.Time → string в формате ISO 8601
Опциональные поля: указатели и поля с omitempty становятся опциональными
JSON теги: используются для именования полей в TypeScript

Структура файлов¶

`frontend/shared/types/generated-types.ts`¶

// ===================================================================
// АВТОМАТИЧЕСКИ СГЕНЕРИРОВАННЫЕ TYPESCRIPT ТИПЫ
// Источник: backend/shared/models Go структуры
// 
// ⚠️  НЕ РЕДАКТИРУЙТЕ ЭТОТ ФАЙЛ ВРУЧНУЮ!
// ===================================================================

export interface UnifiedInvestment {
  id: string;
  userID: string;
  amount: string;          // decimal.Decimal как строка
  currentValue: string;    // decimal.Decimal как строка
  status: string;
  createdAt: string;       // time.Time как ISO строка
  updatedAt: string;
  strategyID?: string;     // опциональное поле
  metadata?: Record<string, any>;  // JSONB поле
}

// ... остальные интерфейсы

`frontend/shared/types/unified-types.ts`¶

// Экспортируем все автоматически сгенерированные типы
export * from './generated-types';

// Дополнительные frontend-специфичные типы
export interface FrontendUser {
  // ... frontend-только поля
  displayName?: string;
  avatar?: string;
}

// Типы для UI компонентов
export interface TableColumn {
  // ...
}

// Совместимость с существующими типами
export type { 
  UnifiedInvestment as Investment,
  UnifiedInvestmentWithUser as InvestmentWithUser,
} from './generated-types';

Рабочий процесс¶

Изменение Go моделей¶

Модифицируйте структуры в backend/shared/models/
Типы автоматически обновятся при следующем make build или при сборке контейнера
Или запустите make generate-types вручную

Добавление нового типа¶

Создайте Go структуру в backend/shared/models/
Добавьте анализ в backend/cmd/typegen/main.go если нужно
Запустите генерацию типов
Используйте новый тип в frontend через unified-types.ts

Проверка изменений¶

# Посмотреть какие типы изменились
git diff frontend/shared/types/generated-types.ts

# Проверить совместимость с приложениями
make types-check

# Статистика генерации
./scripts/update-types.sh --show-diff

Интеграция с CI/CD¶

GitHub Actions¶

- name: Generate and check TypeScript types
  run: |
    make generate-types
    make types-check

    # Проверить что нет несинхронизированных изменений
    git diff --exit-code frontend/shared/types/generated-types.ts

Pre-commit хуки¶

# Добавить в .git/hooks/pre-commit
make generate-types
git add frontend/shared/types/generated-types.ts

Troubleshooting¶

Типы не обновляются¶

# Принудительная генерация
make generate-types

# Проверка статуса файлов
ls -la frontend/shared/types/generated-types.ts
ls -la backend/shared/models/*.go

Ошибки компиляции TypeScript¶

# Проверка синтаксиса сгенерированных типов
make types-check

# Детальная диагностика
node frontend/shared/scripts/check-types.js

Конфликты типов¶

# Сравнение с предыдущей версией
git show HEAD:frontend/shared/types/generated-types.ts > /tmp/old-types.ts
diff /tmp/old-types.ts frontend/shared/types/generated-types.ts

Расширение системы¶

Добавление нового генератора¶

Расширьте analyzeGoStructs() в main.go
Добавьте специальную обработку в goTypeToTypeScript()
Обновите документацию по маппингу типов

Кастомизация вывода¶

// В backend/cmd/typegen/main.go
func (g *TypeGenerator) generateTypeScript() (string, error) {
    // Добавьте свою логику генерации
}

Интеграция с другими инструментами¶

OpenAPI: генерация из TypeScript типов
GraphQL: создание схем из типов
Validation: использование типов для runtime валидации

Метрики и мониторинг¶

Статистика генерации¶

make generate-types
# Выводит:
# ✅ TypeScript типы успешно сгенерированы
# 📊 Создано типов: 118

Мониторинг изменений¶

# Автоматический мониторинг (требует fswatch)
make types-watch

# Периодическая проверка
watch -n 60 'make generate-types'

Качество типов¶

Покрытие: все Go структуры в shared/models покрыты
Точность: 1:1 соответствие между Go и TypeScript
Актуальность: автоматическое обновление при изменениях

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

Разработка Go моделей¶

Используйте JSON теги для корректного именования полей
Добавляйте комментарии к структурам для документации
Группируйте связанные типы в одном файле
Используйте понятные имена для полей и структур

Frontend разработка¶

Импортируйте из unified-types.ts а не напрямую из generated-types.ts
Не модифицируйте сгенерированные типы
Создавайте алиасы для сложных типов если нужно
Используйте type guards для runtime проверок

Совместимость¶

Добавляйте алиасы при переименовании типов
Используйте deprecated комментарии для устаревших полей
Тестируйте миграцию на staging окружении
Документируйте breaking changes в CHANGELOG

Заключение¶

Система автоматической генерации TypeScript типов обеспечивает:

Консистентность типов между backend и frontend
Автоматизацию процесса синхронизации
Безопасность типов на уровне компиляции
Простоту использования и интеграции

Это фундаментальная часть архитектуры проекта, которая устраняет класс ошибок связанных с несоответствием типов и упрощает разработку новых функций.