Разработка кастомного сервиса 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, который позволяет объединить несколько шагов в одну транзакцию. Кастомный сервис использует его для гарантии целостности данных: например, начисление баллов и списание скидки выполняются в одной транзакции. Это исключает рассинхронизацию и упрощает отладку.