Розробка кастомного сервісу 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, який дозволяє об'єднати кілька кроків в одну транзакцію. Кастомний сервіс використовує його для гарантії цілісності даних: наприклад, нарахування балів та списання знижки виконуються в одній транзакції. Це виключає розсинхронізацію та спрощує налагодження.