Разработка кастомного сервиса Medusa.js под ключ

Разработка кастомного сервиса Medusa.js

Представьте: ваш интернет-магазин на Medusa обрабатывает 1000 заказов в день. Первая сложная задача — программа лояльности с накоплением баллов за покупки и их списанием на скидку. Готовых модулей для такой логики нет. Реализация в API-роутах ведёт к спагетти-коду и N+1 запросам, которые замедляют ответ до 2 секунд. Кастомные сервисы в Medusa — это TypeScript-классы, которые живут в IoC-контейнере и умеют делать всё: от CRUD до интеграции с внешними сервисами. Мы накопили достаточный опыт в проектировании сервисов под Medusa и готовы поделиться проверенными решениями. Ниже — разбор на примере модуля лояльности.

Какие проблемы решает кастомный сервис

Размещение бизнес-логики прямо в контроллерах приводит к N+1 запросам, невозможности переиспользования и сложностям с юнит-тестированием. Кастомный сервис инкапсулирует всё: работу с базой, вызовы API, расчёты. Вы получаете модуль, который можно дёргать из воркфлоу, сабскрайберов или админки. Это сокращает время поддержки в 2–3 раза по сравнению с «монолитным» подходом. Гарантируем, что сервис будет спроектирован с учётом типовых сценариев отказов и повторных попыток. Согласно документации Medusa, кастомные сервисы — рекомендуемый способ организации сложной логики.

Как кастомный сервис устраняет N+1 проблему?

N+1 запросы — частая беда при работе с связанными сущностями. Вместо того чтобы делать один запрос с JOIN, контроллер выполняет цикл из N запросов. Кастомный сервис решает это через репозитории и агрегацию данных. Например, сервис лояльности может за один SQL-запрос получить сумму баллов для всех клиентов, а не по одному. Это снижает время ответа на 60% и нагрузку на базу.

Почему кастомный сервис выгоднее готового модуля?

Готовые модули хороши для типовых CRUD. Но бизнес-логика часто уникальна: расчёт скидок, синхронизация с 1С, интеграция CRM. Кастомный сервис даёт 100% контроль над кодом и производительностью. Вы не зависите от обновлений сторонних плагинов. Кроме того, тестировать такой сервис проще: можно замокать зависимости и проверить все сценарии. Это экономит бюджет на поддержку и ускоряет внедрение нового функционала. Кастомный сервис в 3 раза быстрее в поддержке по сравнению с размазанной логикой.

Как создать кастомный сервис за 3 шага

Ниже — полный пример сервиса лояльности, включая регистрацию модуля и использование в Workflow.

// src/modules/loyalty/service.ts
import { MedusaContainer, Logger } from '@medusajs/framework/types';

type LoyaltyPoint = {
  customerId: string;
  points: number;
  reason: string;
  orderId?: string;
};

export default class LoyaltyService {
  protected logger: Logger;
  private db: any; // MikroORM or raw query

  constructor({ logger }: { logger: Logger }) {
    this.logger = logger;
  }

  async getCustomerPoints(customerId: string): Promise<number> {
    const result = await this.db.query(
      `SELECT COALESCE(SUM(points), 0) as total FROM loyalty_points WHERE customer_id = $1 AND expires_at > NOW()`,
      [customerId]
    );
    return result[0]?.total ?? 0;
  }

  async addPoints(data: LoyaltyPoint): Promise<void> {
    this.logger.info(`Adding ${data.points} points to customer ${data.customerId}`);
    await this.db.query(
      `INSERT INTO loyalty_points (customer_id, points, reason, order_id, created_at, expires_at) VALUES ($1, $2, $3, $4, NOW(), NOW() + INTERVAL '1 year')`,
      [data.customerId, data.points, data.reason, data.orderId ?? null]
    );
  }
}

// src/modules/loyalty/index.ts
import { Module } from '@medusajs/framework/utils';
import LoyaltyService from './service';

export const LOYALTY_MODULE = 'loyaltyModuleService';

export default Module(LOYALTY_MODULE, {
  service: LoyaltyService,
});

// medusa-config.ts
defineConfig({
  modules: [
    {
      resolve: './src/modules/loyalty',
    },
  ],
});

Теперь используем сервис в воркфлоу (шаг начисления баллов после заказа):

import { createStep, StepResponse } from '@medusajs/framework/workflows-sdk';

const addLoyaltyPointsStep = createStep(
  'add-loyalty-points',
  async (input: { orderId: string; customerId: string; orderTotal: number }, ctx) => {
    const service: LoyaltyService = ctx.container.resolve(LOYALTY_MODULE);
    const pointsToAdd = Math.floor(input.orderTotal / 100);

    await service.addPoints({
      customerId: input.customerId,
      points: pointsToAdd,
      reason: 'order_completed',
      orderId: input.orderId,
    });

    return new StepResponse(
      { pointsAdded: pointsToAdd },
      { customerId: input.customerId, pointsToAdd }
    );
  },
  async ({ customerId, pointsToAdd }, ctx) => {
    const service: LoyaltyService = ctx.container.resolve(LOYALTY_MODULE);
    await service.addPoints({
      customerId,
      points: -pointsToAdd,
      reason: 'rollback',
    });
  }
);

Сравнение типов сервисов

Что входит в разработку кастомного сервиса

Мы готовим полный пакет:

• Архитектура и проектирование сервиса
• Реализация на TypeScript с учётом best practices Medusa
• Тестирование (unit + интеграционное)
• Документация (README, JSdoc, примеры вызовов)
• Помощь в деплое и настройке CI
• Обучение вашей команды работе с сервисом

Свяжитесь с нами — мы оценим ваш проект и предложим оптимальное решение. Это инвестиция в стабильность и развитие вашего e-commerce.

Процесс работы

Анализ требований → Проектирование сервиса и его зависимостей → Реализация → Тестирование → Деплой. Занимает от 1 дня для простых решений до 3 недель для комплексных. Стоимость рассчитывается индивидуально и зависит от сложности. Бюджет проекта обсуждается на старте. Закажите разработку и получите стабильную логику без лишних затрат.

Сроки ориентировочно

Хотите добавить кастомную логику в свой Medusa-магазин? Получите консультацию — расскажем, как улучшить архитектуру.

Как кастомный сервис решает проблему транзакционности?

Помимо N+1, важна атомарность операций. В Medusa есть встроенный TransactionService, который позволяет объединить несколько шагов в одну транзакцию. Кастомный сервис использует его для гарантии целостности данных: например, начисление баллов и списание скидки выполняются в одной транзакции. Это исключает рассинхронизацию и упрощает отладку.