Skip to content

ARCHITECTURE.md

Latest commit

 

History

History
238 lines (182 loc) · 11.8 KB

ARCHITECTURE.md

File metadata and controls

238 lines (182 loc) · 11.8 KB

🏗️ Архитектура CurRate-Go

Детальное описание архитектуры системы

Обзор архитектуры

CurRate-Go построен на многослойной архитектуре с четким разделением ответственности между слоями.

┌─────────────────────────────────────────────────────────┐
│                     GUI Layer (Wails)                   │
│           HTML/CSS/JS → Go Backend (App.go)             │
└─────────────────────────────────────────────────────────┘
                            │
                            ▼
┌─────────────────────────────────────────────────────────┐
│                  Business Logic Layer                   │
│                                                         │
│  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐ │
│  │  Converter   │  │  Validator   │  │  Formatter   │ │
│  │  (главная    │  │  (проверка   │  │  (вывод      │ │
│  │   логика)    │  │   данных)    │  │  результата) │ │
│  └──────────────┘  └──────────────┘  └──────────────┘ │
└─────────────────────────────────────────────────────────┘
                            │
            ┌───────────────┴───────────────┐
            ▼                               ▼
┌─────────────────────────┐   ┌─────────────────────────┐
│   Data Access Layer     │   │   Caching Layer         │
│                         │   │                         │
│  ┌──────────────────┐   │   │  ┌──────────────────┐  │
│  │  Parser (XML)    │   │   │  │   LRU Cache      │  │
│  │  • ParseXML      │   │   │  │   • 100 items    │  │
│  │  • FetchRates    │   │   │  │   • TTL 24h      │  │
│  │  • HTTP Client   │   │   │  │   • Thread-safe  │  │
│  └──────────────────┘   │   │  └──────────────────┘  │
└─────────────────────────┘   └─────────────────────────┘
            │
            ▼
┌─────────────────────────────────────────────────────────┐
│              CBR XML API (ЦБ РФ)                        │
│    https://www.cbr.ru/scripts/XML_daily.asp             │
└─────────────────────────────────────────────────────────┘

Слои архитектуры

1. GUI Layer (Wails)

Назначение: Пользовательский интерфейс и взаимодействие с пользователем

Технологии:

  • Wails v2.11.0 - Desktop UI фреймворк
  • WebView2 - Нативный рендеринг (Windows 11)
  • HTML/CSS/Vanilla JavaScript - Frontend без фреймворков

Компоненты:

  • frontend/index.html - Основная разметка
  • frontend/styles/ - Стили CSS
  • frontend/scripts/ - JavaScript логика
  • main_gui.go - Точка входа для GUI
  • internal/app/app.go - Go backend для Wails bindings

Взаимодействие:

  • Frontend вызывает методы Go через Wails Runtime
  • Go backend обрабатывает запросы и возвращает результаты
  • Двусторонняя связь через события

2. Business Logic Layer

Назначение: Основная бизнес-логика конвертации валют

Модули:

Converter (internal/converter/converter.go)

  • Главный конвертер валют
  • Координация работы всех компонентов
  • Обработка результатов конвертации

Validator (internal/converter/validator.go)

  • Валидация входных данных
  • Проверка корректности суммы и даты
  • Валидация валюты

Formatter (internal/converter/formatter.go)

  • Форматирование результата конвертации
  • Поддержка русского формата чисел
  • Форматирование валют

Взаимодействие:

  • Converter использует Validator для проверки входных данных
  • Converter использует Formatter для форматирования результата
  • Converter взаимодействует с Data Access Layer для получения курсов

3. Data Access Layer

Назначение: Получение данных о курсах валют из внешних источников

Модули:

Parser (internal/parser/)

  • xml.go - XML парсер с поддержкой windows-1251
  • client.go - HTTP клиент с retry логикой
  • cbr.go - Публичный API для получения курсов

Особенности:

  • Поддержка кодировки windows-1251 (конвертация в UTF-8)
  • Exponential backoff retry (1s, 2s, 4s)
  • Обработка HTTP редиректов
  • Таймауты и обработка ошибок

Взаимодействие:

  • Получает данные из CBR XML API
  • Возвращает структурированные данные в Business Logic Layer
  • НЕ занимается кэшированием (это ответственность Converter)

4. Caching Layer

Назначение: Кэширование курсов валют для минимизации запросов к API

Модуль: internal/cache/

Особенности:

  • LRU (Least Recently Used) алгоритм
  • TTL (Time To Live) - 24 часа
  • Thread-safe - безопасен для concurrent использования
  • 100 items - максимальный размер кэша

Взаимодействие:

  • Кэш используется Business Logic Layer (Converter) для хранения курсов
  • Converter проверяет кэш перед запросом к Parser
  • Converter сохраняет полученные курсы в кэш
  • Автоматически инвалидирует устаревшие записи по TTL

Структура модулей

internal/
├── models/         # Модели данных (Currency, ExchangeRate, RateData)
├── parser/         # Парсинг XML API ЦБ РФ
│   ├── xml.go      # XML парсер (encoding/xml + windows-1251)
│   ├── parser.go   # Общие функции парсинга
│   ├── client.go   # HTTP клиент с retry
│   └── cbr.go      # Публичный API
├── cache/          # LRU кэш с TTL
├── converter/      # Бизнес-логика конвертации
│   ├── converter.go    # Главный конвертер
│   ├── validator.go    # Валидация входных данных
│   └── formatter.go    # Форматирование результата
├── telegram/       # Интеграция с Telegram Bot API
│   ├── telegram.go     # Отправка уведомлений
│   └── userid.go       # Генерация анонимного user ID
└── app/            # Wails backend (App.go)

Потоки данных

Конвертация валют (GUI)

  1. Пользователь вводит данные в GUI (сумма, валюта, дата)
  2. Frontend вызывает Go метод через Wails Runtime
  3. App.go получает запрос и передает в Converter
  4. Converter валидирует данные через Validator
  5. Converter проверяет кэш - если курс есть, использует его
  6. Если кэш пуст, Converter запрашивает данные через Parser
  7. Parser делает HTTP запрос к CBR XML API
  8. Parser парсит XML и возвращает структурированные данные
  9. Converter сохраняет полученный курс в кэш для последующих запросов
  10. Converter конвертирует валюту используя полученный курс
  11. Formatter форматирует результат для отображения
  12. Результат возвращается в Frontend через Wails Runtime
  13. GUI отображает результат пользователю

Конвертация валют (API)

  1. Вызов API метода Converter.Convert()
  2. Converter валидирует данные через Validator
  3. Converter проверяет кэш - если курс есть, использует его
  4. Если кэш пуст, Converter запрашивает данные через Parser
  5. Parser получает данные из CBR XML API
  6. Converter сохраняет полученный курс в кэш
  7. Converter конвертирует и форматирует результат
  8. Результат возвращается вызывающему коду

Принципы проектирования

1. Separation of Concerns

  • Каждый слой имеет четкую ответственность
  • Минимальная связанность между слоями
  • Высокая сплоченность внутри слоев

2. Dependency Injection

  • Converter получает зависимости через конструктор
  • Легко тестировать и мокировать
  • Гибкость в замене компонентов

3. Interface-based Design

  • Использование интерфейсов для абстракции
  • Легкая замена реализаций
  • Упрощенное тестирование

4. Error Handling

  • Явная обработка ошибок
  • Понятные сообщения об ошибках
  • Graceful degradation

Связанные документы