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