mercur架构设计：现代电商平台的技术实现原理

【免费下载链接】mercur Open-source multi-vendor marketplace platform for B2B & B2C. Built on top of MedusaJS. Create your own custom marketplace. 🛍️ 项目地址: https://gitcode.com/GitHub_Trending/me/mercur

引言：多供应商电商平台的技术挑战

在当今电商领域，多供应商市场平台正成为主流趋势。传统的单体电商架构难以应对复杂的供应商管理、订单分发、佣金计算、支付分账等需求。mercur作为基于MedusaJS构建的开源多供应商市场平台，通过现代化的架构设计解决了这些技术难题。

本文将深入解析mercur的架构设计原理，从技术栈选择、模块化设计、数据模型到系统集成，全面揭示现代电商平台的技术实现奥秘。

技术栈与整体架构

核心技术选型

mercur采用现代化的技术栈，确保系统的高性能和可扩展性：

技术组件	选择	作用
后端框架	MedusaJS 2.8.6	电商核心引擎
数据库	PostgreSQL + MikroORM	关系型数据存储
前端技术	React 18 + Vite	现代化前端开发
构建工具	TurboRepo	Monorepo管理
搜索服务	Algolia	高性能商品搜索
支付集成	Stripe Connect	多供应商支付分账
邮件服务	Resend	交易通知和营销

整体架构设计

mercur采用分层架构设计，确保各组件职责清晰：

模块化架构设计

核心模块体系

mercur采用高度模块化的架构，每个功能模块独立封装：

模块依赖关系

// 典型的模块注册示例
import { Module } from "@medusajs/framework/utils";
import MarketplaceModuleService from "./service";

export const MARKETPLACE_MODULE = "marketplace";

export default Module(MARKETPLACE_MODULE, {
  service: MarketplaceModuleService,
});

数据模型设计

核心实体关系

mercur的数据模型设计充分考虑了多供应商场景的复杂性：

订单分账模型

多供应商订单处理是mercur的核心特性：

// 订单分账处理逻辑示例
interface OrderSplit {
  orderId: string;
  items: Array<{
    productId: string;
    sellerId: string;
    quantity: number;
    price: number;
    commissionRate: number;
  }>;
  payments: Array<{
    sellerId: string;
    amount: number;
    status: 'pending' | 'processed';
  }>;
}

class OrderSplitService {
  async processOrderSplit(order: Order): Promise<OrderSplit> {
    // 计算每个供应商的应得金额
    const splits = order.items.map(item => ({
      sellerId: item.product.sellerId,
      amount: this.calculateSellerAmount(item),
      commission: this.calculateCommission(item)
    }));
    
    return {
      orderId: order.id,
      items: order.items,
      payments: splits
    };
  }
}

API架构设计

RESTful API设计原则

mercur的API设计遵循RESTful最佳实践：

HTTP方法	路径	功能描述
GET	/api/admin/sellers	获取供应商列表
POST	/api/admin/sellers	创建新供应商
GET	/api/admin/sellers/:id	获取供应商详情
PUT	/api/admin/sellers/:id	更新供应商信息
GET	/api/store/products	获取商品列表（带搜索）
POST	/api/store/orders	创建新订单

中间件架构

// API中间件示例
export const adminAuthMiddleware = async (
  req: Request,
  res: Response,
  next: NextFunction
) => {
  try {
    const authHeader = req.headers.authorization;
    if (!authHeader) {
      return res.status(401).json({ error: 'Authentication required' });
    }
    
    const user = await verifyAdminToken(authHeader);
    req.user = user;
    next();
  } catch (error) {
    res.status(403).json({ error: 'Invalid token' });
  }
};

// 路由注册
router.get('/sellers', adminAuthMiddleware, async (req, res) => {
  const sellers = await sellerService.listSellers();
  res.json(sellers);
});

搜索与索引架构

Algolia集成设计

mercur采用Algolia实现高性能商品搜索：

实时索引策略

class AlgoliaIndexingService {
  private client: algoliasearch.Client;
  
  constructor() {
    this.client = algoliasearch(process.env.ALGOLIA_APP_ID, process.env.ALGOLIA_API_KEY);
  }
  
  async indexProduct(product: Product): Promise<void> {
    const index = this.client.initIndex('products');
    
    const record = {
      objectID: product.id,
      name: product.title,
      description: product.description,
      price: product.price,
      seller: product.seller.name,
      categories: product.categories,
      // 其他可搜索字段
    };
    
    await index.saveObject(record);
  }
  
  async searchProducts(query: string, filters: any = {}): Promise<Product[]> {
    const index = this.client.initIndex('products');
    const results = await index.search(query, {
      filters: this.buildFilters(filters),
      hitsPerPage: 20
    });
    
    return results.hits.map(hit => this.transformHitToProduct(hit));
  }
}

支付与分账架构

Stripe Connect集成

mercur使用Stripe Connect处理多供应商支付分账：

分账处理逻辑

class StripeConnectService {
  async createConnectedAccount(seller: Seller): Promise<string> {
    const account = await stripe.accounts.create({
      type: 'express',
      country: seller.country,
      email: seller.email,
      capabilities: {
        card_payments: { requested: true },
        transfers: { requested: true },
      },
    });
    
    return account.id;
  }
  
  async processSplitPayment(order: Order): Promise<PaymentResult> {
    const paymentIntent = await stripe.paymentIntents.create({
      amount: Math.round(order.total * 100), // 转换为分
      currency: order.currency,
      payment_method_types: ['card'],
      application_fee_amount: this.calculatePlatformFee(order),
      transfer_data: {
        destination: order.seller.stripeAccountId,
      },
    });
    
    return {
      paymentIntentId: paymentIntent.id,
      clientSecret: paymentIntent.client_secret,
      status: 'requires_payment_method'
    };
  }
}

性能优化策略

数据库优化

mercur采用多种数据库优化策略：

优化技术	实现方式	效果
索引优化	为查询字段创建复合索引	查询性能提升5-10倍
查询优化	使用MikroORM的Dataloader	减少N+1查询问题
缓存策略	Redis缓存热点数据	降低数据库负载
分表分库	按时间或业务分片	支持海量数据存储

前端性能优化

// React组件优化示例
const ProductList = React.memo(({ products, onProductClick }) => {
  return (
    <div className="product-grid">
      {products.map(product => (
        <ProductCard
          key={product.id}
          product={product}
          onClick={onProductClick}
        />
      ))}
    </div>
  );
});

// 使用React Query进行数据缓存
const { data: products, isLoading } = useQuery({
  queryKey: ['products', searchTerm],
  queryFn: () => api.searchProducts(searchTerm),
  staleTime: 5 * 60 * 1000, // 5分钟缓存
});

安全架构设计

多层次安全防护

mercur构建了完整的安全防护体系：

权限控制系统

// RBAC权限控制示例
enum UserRole {
  ADMIN = 'admin',
  SELLER = 'seller',
  CUSTOMER = 'customer'
}

enum Permission {
  MANAGE_PRODUCTS = 'manage:products',
  VIEW_ORDERS = 'view:orders',
  PROCESS_PAYMENTS = 'process:payments'
}

const rolePermissions = {
  [UserRole.ADMIN]: [
    Permission.MANAGE_PRODUCTS,
    Permission.VIEW_ORDERS,
    Permission.PROCESS_PAYMENTS
  ],
  [UserRole.SELLER]: [
    Permission.MANAGE_PRODUCTS,
    Permission.VIEW_ORDERS
  ],
  [UserRole.CUSTOMER]: [
    Permission.VIEW_ORDERS
  ]
};

function hasPermission(user: User, permission: Permission): boolean {
  return rolePermissions[user.role]?.includes(permission) || false;
}

部署与扩展架构

容器化部署

mercur支持Docker容器化部署：

# Dockerfile示例
FROM node:20-alpine

WORKDIR /app

# 复制package文件
COPY package*.json ./
COPY yarn.lock ./

# 安装依赖
RUN yarn install --frozen-lockfile

# 复制源代码
COPY . .

# 构建应用
RUN yarn build

# 暴露端口
EXPOSE 9000

# 启动应用
CMD ["yarn", "start"]

水平扩展策略

监控与运维架构

observability设计

mercur集成了完整的可观测性体系：

监控维度	工具选择	监控指标
应用性能	Prometheus + Grafana	请求延迟、错误率、吞吐量
日志管理	ELK Stack	应用日志、错误跟踪
用户体验	Real User Monitoring	页面加载时间、交互延迟
业务指标	Custom Dashboards	订单量、GMV、转化率

健康检查机制

// 健康检查端点
router.get('/health', async (req, res) => {
  const healthCheck = {
    status: 'ok',
    timestamp: new Date().toISOString(),
    services: {
      database: await checkDatabaseHealth(),
      redis: await checkRedisHealth(),
      algolia: await checkAlgoliaHealth(),
      stripe: await checkStripeHealth()
    }
  };
  
  const allHealthy = Object.values(healthCheck.services).every(
    service => service.status === 'healthy'
  );
  
  res.status(allHealthy ? 200 : 503).json(healthCheck);
});

总结与最佳实践

mercur的架构设计体现了现代电商平台的最佳实践：

1. 模块化设计：通过功能模块的分离，确保系统的可维护性和可扩展性
2. 微服务架构：基于MedusaJS的插件体系，支持灵活的功能扩展
3. 云原生部署：容器化部署和水平扩展能力，支持业务快速增长
4. 性能优化：从数据库到前端的全方位性能优化策略
5. 安全防护：多层次的安全体系，保护平台和用户数据安全

【免费下载链接】mercur Open-source multi-vendor marketplace platform for B2B & B2C. Built on top of MedusaJS. Create your own custom marketplace. 🛍️ 项目地址: https://gitcode.com/GitHub_Trending/me/mercur