0

Medusa v2: hiểu module và workflow trước khi viết dòng code đầu tiên

Medusa v2 không phải bản nâng cấp nhỏ của v1. Cách tổ chức code thay đổi gần như hoàn toàn: logic nghiệp vụ nằm trong module, còn luồng xử lý nhiều bước nằm trong workflow. Nếu mang tư duy v1 hoặc tư duy Express thông thường sang, bạn sẽ thấy khó chịu khá sớm.

Bài này tóm tắt những điểm nên nắm trước khi bắt tay vào làm. Stack mình nói tới là Medusa v2 chạy cùng PostgreSQL, storefront Next.js App Router. Đây cũng là stack của shibaSIM, một shop bán eSIM du lịch.

Module: mỗi phần tự quản dữ liệu của mình

Module là một gói độc lập gồm data model, service và có thể có migration riêng. Các commerce module có sẵn như Product, Cart, Order, Payment đều là module theo đúng nghĩa đó.

Điểm quan trọng nhất: module bị cô lập. Service của module A không resolve trực tiếp service của module B. Data model của module này cũng không khai báo relation trực tiếp sang bảng của module khác.

Một module tự viết tối thiểu gồm ba file. Ví dụ minh họa dưới đây là một module quản lý pool mã QR.

// src/modules/esim/models/qr-code.ts
import { model } from "@medusajs/framework/utils"

const QrCode = model.define("qr_code", {
  id: model.id().primaryKey(),
  payload: model.text(),
  used: model.boolean().default(false),
})

export default QrCode
// src/modules/esim/service.ts
import { MedusaService } from "@medusajs/framework/utils"
import QrCode from "./models/qr-code"

class EsimModuleService extends MedusaService({ QrCode }) {}

export default EsimModuleService
// src/modules/esim/index.ts
import { Module } from "@medusajs/framework/utils"
import EsimModuleService from "./service"

export const ESIM_MODULE = "esim"

export default Module(ESIM_MODULE, { service: EsimModuleService })

MedusaService tự sinh các method CRUD như listQrCodes, createQrCodes, updateQrCodes. Bạn không phải viết repository bằng tay.

Sau đó:

  • Đăng ký module trong mảng modules của medusa-config.ts.
  • Chạy npx medusa db:generate esim để sinh migration.
  • Chạy npx medusa db:migrate để áp vào database.

Quên bước đăng ký là lỗi rất dễ mắc: code compile bình thường nhưng resolve service thì không thấy.

Link và Query: nối dữ liệu giữa các module

Vì module không được trỏ relation sang nhau, Medusa v2 dùng module link. Bạn khai báo link bằng defineLink trong thư mục src/links, ví dụ nối một product với dữ liệu của module tự viết. Link được lưu ở bảng riêng, cũng cần chạy migrate.

Khi đọc dữ liệu xuyên module, dùng Query với query.graph(...). Query đi theo các link đã khai báo và trả về dữ liệu gộp. Đừng cố join tay giữa các bảng của module khác nhau, vì như vậy là phá đúng cái ranh giới mà kiến trúc này dựng lên.

Workflow: chỗ đặt logic nhiều bước

Workflow là chuỗi các step. Mỗi step có thể kèm một hàm compensation để hoàn tác khi step phía sau thất bại. Đây là lý do nên đưa logic ghi dữ liệu vào workflow thay vì nhét hết vào API route.

import {
  createStep,
  createWorkflow,
  StepResponse,
  WorkflowResponse,
} from "@medusajs/framework/workflows-sdk"
import { ESIM_MODULE } from "../modules/esim"

const reserveQrStep = createStep(
  "reserve-qr",
  async (_, { container }) => {
    const esim = container.resolve(ESIM_MODULE)
    const [qr] = await esim.listQrCodes({ used: false }, { take: 1 })
    await esim.updateQrCodes({ id: qr.id, used: true })
    return new StepResponse(qr, qr.id)
  },
  async (qrId, { container }) => {
    if (!qrId) return
    const esim = container.resolve(ESIM_MODULE)
    await esim.updateQrCodes({ id: qrId, used: false })
  }
)

export const reserveQrWorkflow = createWorkflow("reserve-qr", () => {
  const qr = reserveQrStep()
  return new WorkflowResponse(qr)
})

Đoạn code trên chỉ để minh họa cấu trúc. Trong thực tế, cặp list rồi update không phải thao tác nguyên tử, hai request đồng thời có thể lấy trùng một bản ghi. Với tài nguyên kiểu pool dùng một lần, bạn cần khóa hàng hoặc một câu update có điều kiện ở tầng database.

Gọi workflow từ API route:

const { result } = await reserveQrWorkflow(req.scope).run({ input: {} })

Bẫy hay gặp trong hàm createWorkflow

Hàm truyền vào createWorkflow không chạy như hàm bình thường. Nó được dùng để dựng định nghĩa workflow, các biến bên trong là tham chiếu chứ chưa phải giá trị thật. Hệ quả:

  • Không dùng async/await trong thân workflow.
  • Không viết if, toán tử ba ngôi hay thao tác trực tiếp trên biến. Dùng transform để biến đổi dữ liệu và when để rẽ nhánh.
  • Logic thật sự đặt trong step.

Nắm điểm này sớm sẽ tiết kiệm nhiều thời gian debug.

Các thư mục còn lại

  • src/api: API route, mỗi route.ts export hàm GET, POST.
  • src/subscribers: lắng nghe event, ví dụ sau khi đơn được tạo.
  • src/jobs: scheduled job.
  • src/admin: widget và trang tùy biến cho dashboard admin.

Trong route, subscriber hay job, service đều được lấy qua container (req.scope.resolve hoặc container.resolve).

Thứ tự nên học

  1. Đọc kỹ phần module và tự viết một module nhỏ.
  2. Thử một link và một câu query.graph.
  3. Viết workflow có compensation, cố tình cho step sau throw lỗi để xem rollback.
  4. Sau cùng mới tới subscriber, job và admin.

Đi theo thứ tự này, phần còn lại của Medusa v2 sẽ dễ đoán hơn nhiều.


All rights reserved

Viblo
Hãy đăng ký một tài khoản Viblo để nhận được nhiều bài viết thú vị hơn.
Đăng kí