文档中心开发者技术手册常见业务场景快速开发配方 (Recipes)

系统深度定制与新功能二次开发实战指南

本篇指南专为手握完整源码、希望增添个性化业务逻辑、拓展商品属性多语言或打造全新特色区块的开发者编写。

实战范例 1：商品选项管理、多语言翻译及颜色色板 (`color`) 规范

关于颜色属性命名 (Color Swatches) 的刚性约定

在 Medusa 管理后台录入商品规格时，颜色的属性名称（Option Title）必须严格命名为英文单词 color（或 Color）。Next.js 前端据此特定标识提取 HEX 颜色代码，以渲染直观的彩色色板圆点及多维筛选器。

在 Strapi 中配置多语言选项名称的步骤：

对于其余常规选项（如尺码、面料、品牌），可自由使用任何语言录入命名。
对应各语言的本地化展示名称，可在 Strapi CMS 字典面板中动态配置映射。
Next.js 前台依据用户当前 Locale 语言环境向 Strapi 调取本地化标签，而底层核心筛选逻辑仍稳定基于 color。

前端根据 Strapi 本地化字典解析商品选项范例

typescript

// store/src/lib/strapi-client/get-option-translations.ts
export async function getOptionTranslation(optionKey: string, locale: string = "fa") {
  const res = await fetch(
    `${process.env.NEXT_PUBLIC_STRAPI_URL}/api/option-translations?filters[key][$eq]=${optionKey}&locale=${locale}`,
    { headers: { Authorization: `Bearer ${process.env.STRAPI_API_TOKEN_FOR_FRONT}` } }
  )
  const json = await res.json()
  return json.data?.[0]?.translated_name || optionKey
}

实战范例 2：在 Medusa v2 中编写全新 Workflow 业务流与 REST API 端点

在 Medusa v2 架构下，所有商业逻辑均被标准化封装为原子步骤（Steps）与编排工作流（Workflows）：

store-admin/src/workflows/daily-deals.ts

typescript

import { createWorkflow, createStep, StepResponse, WorkflowResponse } from "@medusajs/framework/workflows-sdk";
 
const fetchDealsStep = createStep("fetch-deals-step", async () => {
  const deals = [{ id: "deal_1", title: "今日限时特惠", discount: "25%" }];
  return new StepResponse(deals);
});
 
export const getDailyDealsWorkflow = createWorkflow("get-daily-deals", function () {
  const deals = fetchDealsStep();
  return new WorkflowResponse(deals);
});

store-admin/src/api/store/daily-deals/route.ts

typescript

import { MedusaRequest, MedusaResponse } from "@medusajs/framework/http";
import { getDailyDealsWorkflow } from "../../../workflows/daily-deals";
 
export async function GET(req: MedusaRequest, res: MedusaResponse) {
  const { result } = await getDailyDealsWorkflow(req.scope).run();
  res.json({ deals: result });
}

实战范例 3：从零打造全新的首页模块化动态区块

所有首页区块组件均存放在 store/src/modules/home/components/ 目录下。新增区块涉及三部分协作：homepage.ts 中的类型定义、Strapi 中的组件 Schema 描述文件，以及对应的 React 组件目录。

项目现有成熟架构参考

系统中现存的 FeaturesBlock、BlogPostsBlock、ProductShowcase 以及 ProductSplitView 等区块均拥有独立的物理目录，并在 BlockRenderer 中通过 Strapi 响应的 __component 字段实现分发渲染。

完整演练：新增一个「限时倒计时」区块 (Countdown Block)

定义 TypeScript 接口类型 — 在 store/src/lib/data/homepage.ts 文件中声明新区块接口并纳入全量联合类型：

store/src/lib/data/homepage.ts

typescript

export interface CountdownBlock {
  __component: "ui.countdown-block"
  id: number
  title?: string
  target_date: string
}
 
// 纳入全量联合类型中
export type HomepageBlock =
  | ProductSplitViewBlock
  | ProductShowcaseBlock
  | FeaturesBlock
  | BlogPostsBlock
  | CategoryCollectionBlock
  | CountdownBlock   // <-- 在此处注册新类型

创建 React 组件目录与视图 — 在 store/src/modules/home/components/ 下新建 CountdownBlock 目录并编写组件代码：

store/src/modules/home/components/CountdownBlock/index.tsx

tsx

import React from "react"
import type { CountdownBlock as CountdownBlockType } from "@lib/data/homepage"
 
 
interface CountdownBlockProps {
  block: CountdownBlockType
}
 
export default function CountdownBlock({ block }: CountdownBlockProps) {
  return (
    <section className="py-16 text-center">
      <h2 className="text-xl font-bold mb-4">{block.title}</h2>
      <p className="text-gray-500">{block.target_date}</p>
    </section>
  )
}

在 BlockRenderer 中注册分支 — 打开 store/src/modules/home/components/BlockRenderer/index.tsx 文件，在 switch 分支中新增 case：

store/src/modules/home/components/BlockRenderer/index.tsx

tsx

import CountdownBlock from "../CountdownBlock"
 
// 在 BlockRenderer 的 switch(block.__component) 分支中追加：
case "ui.countdown-block":
  BlockContent = <CountdownBlock block={block} />
  break

在 Strapi 中建立对应组件 Schema — 在 website-admin/src/components/ui/ 目录下创建对应的 JSON 描述定义：

website-admin/src/components/ui/countdown-block.json

json

{
  "collectionName": "components_ui_countdown_blocks",
  "info": {
    "displayName": "Countdown Block",
    "icon": "clock",
    "description": "A countdown timer block for the homepage"
  },
  "options": {},
  "attributes": {
    "title": { "type": "string" },
    "target_date": { "type": "datetime", "required": true }
  }
}

最终验证生效

重启 Strapi 后进入 Homepage > Dynamic Zone 管理界面。您将惊喜地看到全新的「倒计时区块」已出现在可选列表中，即可立即添加到首页！

实战范例 4：接入全新的第三方支付渠道提供商 (Payment Provider)

如需接入全新的支付网关，只需在 store-admin/src/modules/payment/ 目录下新建服务继承并实现 AbstractPaymentProvider 抽象类，并在 medusa-config.ts 的 payment 模块 providers 数组中完成注册配置。