Payment Microservice (Функциональный TypeScript)

Универсальный модульный микросервис для обработки платежей на основе функционального TypeScript. Поддерживает множественные платёжные провайдеры: Stripe, YooKassa, TRON, TON.

Основные возможности

• Функциональный TS: Чистый код без классов, наследования, this
• Архитектура плагинов: Динамическая загрузка провайдеров через ES модули
• Мониторинг webhook: Реалтайм обновления статусов платежей
• Поллинг fallback: Регулярные проверки статуса для провайдеров без webhook
• Repository Pattern: Абстракция хранилища (PostgreSQL, HTTP API, Mock)
• Кеширование TTL: Дедупликация запросов и оптимизация производительности с Redis
• Retry логика: Обработка ошибок с экспоненциальным backoff
• Circuit Breaker: Толерантность к сбоям нестабильных провайдеров
• Конфигурационное управление: Управление поведением через переменные окружения

Архитектура

Сервис использует модульную архитектуру, где платежные провайдеры загружаются динамически как плагины. Ядро системы предоставляет:

• Единую API для платежных операций
• Мониторинг и обновления статусов
• Абстракцию персистентности данных
• Управление конфигурацией и ошибками

Быстрый старт

Предварительные требования

• Node.js >= 18
• npm или yarn

1. Установите зависимости:

   npm install

2. Настройте переменные окружения:

   cp .env.example .env
   # Отредактируйте .env с вашими ключами API

3. Сборка и запуск:

   npm run build
   npm start

Сервис будет доступен на http://localhost:3000

API Endpoints

Платежи

Создание платежа

POST /payments
Content-Type: application/json

{
  "amount": 10.99,
  "currency": "usd",
  "provider": "stripe",
  "description": "Тестовый платеж",
  "metadata": {
    "user_id": "12345",
    "order_id": "ORD-001"
  }
}

Получение платежа

GET /payments/stripe-pi_xxx

Список платежей

GET /payments?limit=10&offset=0&provider=stripe

Webhooks

Stripe Webhook

POST /webhooks/stripe
Content-Type: application/json
X-Stripe-Signature: ...

# Тело webhook от Stripe

Здоровье сервиса

GET /health

Поддерживаемые провайдеры

Реализованные

• Stripe (FIAT): создание PaymentIntent, webhook, статусы
• Mock Repository: in-memory хранилище для тестирования

Запланированные

• YooKassa (FIAT): поддержка российский платежей
• TRON (Blockchain): смарт-контракты для TRX/USDT
• TON (Blockchain): поддержка TON crystal

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

Все настройки управляются через .env файл. Основные параметры:

# Сервер
PORT=3000
NODE_ENV=production

# Stripe
STRIPE_SECRET_KEY=sk_live_...
STRIPE_WEBHOOK_SECRET=whsec_...

# YooKassa
YOOKASSA_SHOP_ID=123456
YOOKASSA_SECRET_KEY=your_secret_key

# Blockchain провайдеры
TRON_NETWORK=mainnet
TON_ENDPOINT=https://toncenter.com/api/v2

# Базы данных
DATABASE_URL=postgres://user:pass@localhost:5432/payment_db
REDIS_URL=redis://localhost:6379

# Кеширование
CACHE_TTL=300

# Логи
LOG_LEVEL=info

Разработка

Доступные скрипты

npm run dev      # Дев сервер с hot reload
npm run build    # Сборка для продакшена
npm run start    # Запуск продакшена
npm run test     # Запуск тестов
npm run lint     # Проверка ESLint

Добавление нового провайдера

1. Создайте папку под src/providers/
2. Реализуйте интерфейс PaymentProvider
3. Экспортируйте фабричную функцию
4. Зарегистрируйте провайдер в основном приложении

Пример:

import { PaymentProvider, PaymentProviderConfig } from '../../types';

class MyProvider implements PaymentProvider {
  // Имплементация методов
}

export default (config: PaymentProviderConfig): PaymentProvider => {
  return new MyProvider(config);
};

Имплементация репозитория

Реализуйте интерфейс PaymentRepository для различных бэкендов хранения:

• mock: in-memory для тестирования
• postgresql: персистентное хранение
• http: API бэкэнд
• redis: кеширование

Деплой

На Heroku

1. Создайте приложение Heroku
2. Установите переменные окружения в Dashboard
3. Пушите код:

   git push heroku main

На Docker

FROM node:18-alpine
WORKDIR /app
COPY package*.json ./
RUN npm ci --only=production
COPY dist/ ./dist/
CMD ["npm", "start"]

На VPS

# Установите Node.js
curl -fsSL https://deb.nodesource.com/setup_18.x | sudo -E bash -
sudo apt-get install -y nodejs

# Загрузите код
git clone https://github.com/your-repo/payment-microservice
cd payment-microservice

# Установите PM2
npm install -g pm2

# Запустите
npm run build
pm2 start dist/index.js --name payment-service

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

# Запуск тестов
npm test

# С тестовым покрытием
npm run test:coverage

Примеры тестов в src/__tests__/

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

• Webhook сигнатуры: Проверяйте подписи вебхуков в продакшене
• API ключи: Никогда не коммитите секреты в код
• Rate limiting: Добавьте ограничение запросов для API
• HTTPS: Всегда используйте SSL в продакшене
• Валидация: Проверяйте входящие данные

Мониторинг

Интегрируйте с:

• Prometheus для метрик
• ELK Stack для логов
• Grafana для дашбордов
• Sentry для ошибок

Contributing

1. Fork репозиторий
2. Создайте feature branch
3. Добавьте тесты для новых функций
4. Зарегистрируйте pull request

Лицензия

MIT License - см. LICENSE файл для деталей.