medusajs-developer

MedusaJS 开发 Agent 技能

专注于 MedusaJS v2.15+ 开发的专家 Agent，重点是借助自定义模块、API 集成和第三方插件构建可扩展的电商解决方案。

核心能力

1. 自定义模块开发

• 数据模型：使用 MedusaJS DML 创建和管理数据模型
• 模块服务：实现带有自动 CRUD 操作的服务层
• 模块配置：设置规范的模块结构和导出项
• 数据库迁移：生成和管理数据库架构变更

2. API 路由开发

• 自定义端点：在 src/api/[route-name]/route.ts 中创建 REST API 路由
• HTTP 方法：实现 GET、POST、PUT、DELETE 处理程序
• 请求/响应处理：管理 MedusaRequest 和 MedusaResponse 对象
• 身份验证：集成 MedusaJS 身份验证系统

3. Commerce 模块集成

• 18 个内置模块：使用 API Key、Auth、Cart、Customer、Order、Payment、Product、Pricing、Promotion、Tax 等模块
• 模块关联：在不同模块之间建立关联
• 自定义字段：为现有模块扩展额外的数据字段
• 模块组合：组合多个模块以实现复杂工作流

4. 工作流与自动化

• 计划任务：使用 cron 表达式创建周期性任务
• 事件处理：实现用于异步操作的订阅器
• 业务逻辑：编排复杂的电商工作流
• 后台处理：高效处理长时间运行的操作

5. 第三方集成

• 支付提供商：集成自定义支付网关
• 外部 API：连接配送、税务和库存服务
• Webhook：处理来自外部系统的传入 Webhook
• 数据同步：与外部平台同步数据

Medusa v2.15+ 更新

身份验证与安全

• Medusa v2.15+ 在身份验证流程中内置了 MFA 基础功能。
• 优先使用由模块管理的 TOTP、SMS 和恢复码验证，而不是自行实现 OTP 存储。
• 将 MFA 纳入 Auth 模块，使其成为登录、注册、验证挑战、确认和恢复流程的一部分。

// Pseudocode: branch on auth result and ask the Auth module to challenge/verify MFA
const result = await authModule.authenticate(credentials)

if (result.mfa_required) {
  await authModule.mfa.challenge({
    user_id: result.user_id,
    method: "totp", // "sms" | "recovery_code"
  })
}

促销

• 促销工作流可以使用上下文钩子进行条件应用。
• 通过工作流传递 customer_group、sales_channel_id、region 或营销活动元数据等上下文数据，以便促销规则进行评估。
• 示例：仅当 context.customer_group === "wholesale" 时应用批发促销。

GET /store/products?query=hoodie&sku=HD-001-BLK-M

Cloud 与平台

• 在调试 Cloud 环境或针对本地应用测试 Webhook 时，使用 mcloud proxy 进行安全的本地到云端隧道连接。
• 当第三方服务需要公共回调 URL，但你希望后端保持在本地时，可使用此功能。

数据模型说明

• 浮点数属性现已在数据模型中统一；建模自定义数值字段时，优先使用更新后的属性类型。

关键迁移说明

• Medusa v2.15.2 包含 MikroORM v6.6.12 安全更新，并修复了 v6.13.6 的快照回归问题。
• 如果你使用的是 v2.13.6+，请先升级，再运行生产迁移，并先清理过期快照：

npx medusa db:migrate --clean-snapshots

• 升级期间，将所有 @medusajs/* 包固定在同一发布系列，避免部分版本不一致。

开发模式

模块结构

// src/modules/my-module/models/post.ts
import { model } from "@medusajs/framework/utils"

const Post = model.define("post", {
  id: model.id().primaryKey(),
  title: model.text(),
  content: model.text().nullable(),
  published: model.boolean().default(false)
})

export default Post

API 路由示例

// src/api/posts/route.ts
import { MedusaRequest, MedusaResponse } from "@medusajs/framework/http"

export const GET = async (req: MedusaRequest, res: MedusaResponse) => {
  const postService = req.scope.resolve("postService")
  const posts = await postService.listPosts()
  
  res.json({ posts })
}

export const POST = async (req: MedusaRequest, res: MedusaResponse) => {
  const postService = req.scope.resolve("postService")
  const post = await postService.createPost(req.body)
  
  res.json({ post })
}

计划任务示例

// src/jobs/sync-inventory.ts
import { MedusaContainer } from "@medusajs/framework/types"

export default async function syncInventoryJob(container: MedusaContainer) {
  const inventoryService = container.resolve("inventoryService")
  await inventoryService.syncWithExternalProvider()
}

export const config = {
  name: "sync-inventory",
  schedule: "0 */6 * * *" // Every 6 hours
}

最佳实践

1. 项目设置

• 使用 MedusaJS CLI 初始化项目
• 遵循 TypeScript 最佳实践
• 实现完善的错误处理
• 建立全面的测试

2. 模块设计

• 让模块专注于单一领域
• 使用清晰的命名规范
• 实施适当的验证
• 记录模块接口

3. API 设计

• 遵循 RESTful 规范
• 使用适当的 HTTP 状态码
• 为列表端点实现分页
• 全面验证输入数据

4. 性能优化

• 适当使用数据库索引
• 实施缓存策略
• 优化数据库查询
• 高效处理大型数据集

5. 集成模式

• 使用环境变量进行配置
• 为外部调用实施重试机制
• 妥善处理速率限制
• 正确记录集成活动

常见任务

创建新模块

1. 创建模块目录结构
2. 定义具有适当关系的数据模型
3. 实现包含业务逻辑的服务层
4. 生成并运行数据库迁移
5. 为模块操作创建 API 路由
6. 添加全面的测试

设置第三方集成

1. 安装必要的依赖项
2. 配置环境变量
3. 创建用于与外部 API 通信的服务
4. 如有需要，实现 Webhook 处理程序
5. 添加错误处理和日志记录
6. 全面测试集成

实施自定义工作流

1. 确定业务流程步骤
2. 创建必要的数据模型
3. 实施工作流编排
4. 为状态变更添加事件处理程序
5. 创建监控和告警
6. 记录工作流行为

故障排除

常见问题

• 迁移失败：检查模型定义和数据库约束
• 服务解析：验证模块导出和依赖注入
• API 错误：验证请求/响应格式和身份验证
• 性能问题：分析数据库查询并实施缓存

调试策略

• 使用 MedusaJS 调试工具
• 检查应用程序日志中的错误
• 验证数据库架构是否与模型一致
• 使用正确的标头测试 API 端点
• 监控外部服务响应

代码模板

此技能包含 templates/ 目录中的生产就绪代码模板，这些模板基于 MedusaJS 官方文档和最佳实践。

可用模板

module-complete.ts

完整的自定义模块结构，包含：

• 多个具有各种属性类型的数据模型
• 一对多和多对多关系
• 带有自定义方法的主服务
• 带有依赖注入的附加服务

**适用场景：**创建自定义模块（Blog、Brand、Restaurant 等）

api-route-complete.ts

完整的 REST API 路由，包含：

• GET、POST、PUT、DELETE 处理程序
• Zod 验证架构
• 身份验证和验证中间件
• 错误处理和日志记录
• 与相关数据的查询集成

**适用场景：**通过 API 端点公开模块功能

workflow-complete.ts

完整的工作流，包含：

• 带有补偿函数的多个步骤
• 步骤之间的数据转换
• 条件执行
• 与 Medusa 模块集成

**适用场景：**需要回滚的复杂业务逻辑

subscriber-complete.ts

事件订阅者模式：

• 基本事件处理
• 在订阅者中执行工作流
• 多事件订阅者
• 重试逻辑和错误处理

**适用场景：**响应 Medusa 事件（order.placed、product.created 等）

module-link.ts

模块链接模式：

• 模块之间的基本链接
• 列表链接（一对多）
• 链接表中的自定义列
• 创建、解除和查询链接

**适用场景：**在不同模块之间创建关系

scheduled-job.ts

定时任务模式：

• 基本定时任务
• 批处理
• 外部 API 集成
• 常见的 cron 模式

**适用场景：**定期自动化任务（同步、清理、报告）

模板使用示例

# Copy template to your project
cp templates/module-complete.ts src/modules/brand/

# Customize for your needs
# - Rename identifiers
# - Add/remove properties
# - Implement business logic

# Generate and run migrations
./scripts/generate-migration.sh brand
./scripts/run-migrations.sh

常见模板组合

电子商务扩展：

1. module-complete.ts → 创建自定义模块
2. module-link.ts → 链接到 Product 模块
3. api-route-complete.ts → 创建 API 端点
4. workflow-complete.ts → 实现业务逻辑
5. subscriber-complete.ts → 处理事件

数据同步：

1. workflow-complete.ts → 同步工作流
2. scheduled-job.ts → 定期运行
3. subscriber-complete.ts → 在事件触发时运行

请参阅 templates/README.md，了解详细文档、最佳实践和更多示例。

辅助脚本

此技能包含一组位于 scripts/ 目录中的辅助脚本，可简化常见的 MedusaJS 开发任务。

数据库管理脚本

db-setup.sh

通过一条命令创建数据库、运行迁移并同步链接。

./scripts/db-setup.sh [database-name]

示例：

./scripts/db-setup.sh medusa-store

generate-migration.sh

为指定模块生成迁移文件。

./scripts/generate-migration.sh <module-name> [additional-modules...]

示例：

./scripts/generate-migration.sh blog
./scripts/generate-migration.sh blog product-custom

run-migrations.sh

运行所有待处理的迁移，并可选择跳过链接或数据迁移。

./scripts/run-migrations.sh [--skip-links] [--skip-data]

示例：

./scripts/run-migrations.sh
./scripts/run-migrations.sh --skip-links

rollback-migration.sh

回滚指定模块的最近一次迁移，并进行安全确认。

./scripts/rollback-migration.sh <module-name> [additional-modules...]

开发与构建脚本

dev-server.sh

以开发模式启动 Medusa 应用，并启用热重载。

./scripts/dev-server.sh [--host HOST] [--port PORT]

示例：

./scripts/dev-server.sh
./scripts/dev-server.sh --host 0.0.0.0 --port 9001

build-production.sh

为 Medusa 应用或仅为管理后台创建可用于生产环境的构建。

./scripts/build-production.sh [--admin-only]

示例：

./scripts/build-production.sh
./scripts/build-production.sh --admin-only

start-production.sh

以生产模式启动已构建的 Medusa 应用。

./scripts/start-production.sh

predeploy.sh

在部署前运行迁移并同步链接（用于 CI/CD 流水线）。

./scripts/predeploy.sh

测试脚本

setup-testing.sh

安装并配置 Jest 和 Medusa 测试工具，创建测试目录和配置文件。

./scripts/setup-testing.sh

run-tests.sh

运行集成测试和单元测试，并可选择不同的测试类型。

./scripts/run-tests.sh [http|modules|unit|all]

示例：

./scripts/run-tests.sh all
./scripts/run-tests.sh http
./scripts/run-tests.sh modules
./scripts/run-tests.sh unit

脚手架脚本

create-module.sh

为新的自定义模块创建基本结构，包括服务和模型目录。

./scripts/create-module.sh <module-name>

示例：

./scripts/create-module.sh blog

生成的结构：

src/modules/<module-name>/
├── index.ts
├── service.ts
├── models/
└── __tests__/

create-api-route.sh

创建包含基本 CRUD 操作（GET、POST、PUT、DELETE）的新 API 路由。

./scripts/create-api-route.sh <route-name>

示例：

./scripts/create-api-route.sh posts

生成的端点：

• GET /api/<route-name> - 列出所有项目
• POST /api/<route-name> - 创建新项目
• GET /api/<route-name>/:id - 获取单个项目
• PUT /api/<route-name>/:id - 更新项目
• DELETE /api/<route-name>/:id - 删除项目

create-scheduled-job.sh

使用 cron 配置模板创建新的定时任务。

./scripts/create-scheduled-job.sh <job-name>

示例：

./scripts/create-scheduled-job.sh sync-inventory

常见 Cron 模式：

• "0 0 * * *" - 每天午夜
• "0 */6 * * *" - 每 6 小时
• "*/15 * * * *" - 每 15 分钟
• "0 9 * * 1" - 每周一上午 9 点

插件开发脚本

plugin-develop.sh

为插件启动开发服务器并启用自动重载（在插件目录中运行）。

./scripts/plugin-develop.sh

plugin-build.sh

构建可发布到 NPM 的插件（在插件目录中运行）。

./scripts/plugin-build.sh

常见工作流

创建新的功能模块

# 1. Create the module structure
./scripts/create-module.sh my-feature

# 2. Add data models in src/modules/my-feature/models/

# 3. Update service.ts with your models

# 4. Generate migrations
./scripts/generate-migration.sh my-feature

# 5. Run migrations
./scripts/run-migrations.sh

# 6. Create API routes
./scripts/create-api-route.sh my-feature

# 7. Write tests
# Add tests in src/modules/my-feature/__tests__/

# 8. Run tests
./scripts/run-tests.sh modules

设置新项目

# 1. Create new project
npx create-medusa-app@latest my-store

# 2. Setup database
./scripts/db-setup.sh my-store-db

# 3. Setup testing environment
./scripts/setup-testing.sh

# 4. Start development server
./scripts/dev-server.sh

部署工作流

# 1. Run tests
./scripts/run-tests.sh all

# 2. Build for production
./scripts/build-production.sh

# 3. In CI/CD pipeline, run predeploy
./scripts/predeploy.sh

# 4. Start production server
./scripts/start-production.sh

资源

• MedusaJS 官方文档
• 社区 Discord 和论坛
• GitHub 仓库和示例
• 插件市场
• 开发者工具和 CLI 命令

此技能支持全面的 MedusaJS 开发，重点在于构建易于维护、可扩展的电子商务解决方案。

版本：2.0 最后更新：2026 年 5 月