labdigital/commercetools-mock-server

commercetools API模拟Docker镜像文档

镜像概述

本Docker镜像提供commercetools平台API的模拟服务，主要用于开发阶段，帮助开发者在无需连接真实commercetools服务的情况下，实现各类集成工具的开发、测试与调试工作。通过本地模拟API响应，可有效降低外部依赖，加速开发周期。

核心功能与特性

• API模拟：完整模拟commercetools平台核心API端点及标准响应格式
• 轻量高效：基于精简基础镜像构建，启动速度快，资源占用低
• 场景自定义：支持通过配置模拟不同业务场景（如成功响应、错误状态、边界条件等）
• 零外部依赖：无需真实commercetools账户、API密钥或网络连接
• 跨平台兼容：可在任何支持Docker的环境中运行（Linux、macOS、Windows）

使用场景与适用范围

主要适用场景

• 开发与commercetools平台集成的工具时进行本地功能测试
• CI/CD流水线中作为测试环节的依赖服务
• 前端开发中需要API数据响应的界面调试
• 学习或评估commercetools API时的本地实验环境
• 后端服务开发中验证API交互逻辑

适用人群

• 与commercetools平台集成的工具开发者
• 需要API模拟环境的前端/后端工程师
• DevOps工程师（配置CI/CD测试环境）
• 学习commercetools API的开发人员

使用方法

基本运行命令

通过以下命令启动基础模拟服务：

bash
docker run -d -p 8080:8080 --name ct-api-mock [镜像名称]

• -p 8080:8080：将容器内8080端口映射到主机8080端口（默认服务端口）
• --name ct-api-mock：指定容器名称，便于后续管理
• [镜像名称]：替换为实际的Docker镜像名称（如commercetools/api-mock）

服务启动后，可通过http://localhost:8080访问模拟API端点，例如：

• 获取产品列表：GET http://localhost:8080/products
• 创建订单：POST http://localhost:8080/orders

自定义配置

环境变量配置

通过环境变量可调整模拟行为，常用参数如下：

示例：模拟20%错误率和300ms响应延迟

bash
docker run -d -p 8080:8080 \
  -e MOCK_ERROR_RATE=20 \
  -e MOCK_RESPONSE_DELAY=300 \
  --name ct-api-mock [镜像名称]

数据持久化

如需使用自定义模拟数据，可通过挂载卷实现：

bash
docker run -d -p 8080:8080 \
  -v /本地自定义数据目录:/data \
  -e CUSTOM_DATA_PATH=/data \
  --name ct-api-mock [镜像名称]

注：自定义数据需符合commercetools API响应格式的JSON文件

Docker Compose示例

在多服务开发环境中，可通过docker-compose.yml集成该镜像：

yaml
version: '3'
services:
  api-mock:
    image: [镜像名称]
    ports:
      - "8080:8080"
    environment:
      - MOCK_RESPONSE_DELAY=200
      - LOG_LEVEL=debug
    volumes:
      - ./custom-data:/data
    restart: unless-stopped

  # 其他服务（如应用服务）可通过 http://api-mock:8080 访问模拟API
  app:
    build: .
    depends_on:
      - api-mock

注意事项

• 本镜像仅用于开发和测试环境，不可用于生产环境
• 模拟API可能不包含commercetools平台的全部端点，具体支持范围请参考镜像官方文档
• 如需模拟复杂业务场景，建议结合自定义数据文件进行配置

故障排除

• 服务无法访问：检查端口映射是否正确，容器是否正常运行（docker ps）
• 响应不符合预期：确认是否正确配置环境变量或自定义数据，查看容器日志（docker logs ct-api-mock）
• 启动失败：检查本地Docker环境是否正常，或尝试使用最新版本镜像