Skip to main content
This guide will help you set up the Ecommerce Order Service on your local machine and walk you through creating and managing orders via the REST API.

​
Prerequisites

Before you begin, ensure you have the following installed:
  • Java 8 or higher
  • Docker (for MySQL and RabbitMQ)
  • Gradle (or use the included Gradle wrapper)
  • Git

​
Setup Infrastructure

The Order Service depends on RabbitMQ and Zipkin for messaging and distributed tracing. You’ll need to set these up first.
1

Clone the devops repository

git clone https://github.com/e-commerce-sample/ecommerce-devops.git
cd ecommerce-devops
2

Start RabbitMQ

cd local/rabbitmq
./start-rabbitmq.sh
RabbitMQ only needs to be started once for all Ecommerce services. It will run on port 5672.
3

Start Zipkin

cd ../zipkin
./start-zipkin.sh
Zipkin provides distributed tracing capabilities. It only needs to be started once for all services.

​
Run the Service Locally

1

Clone the repository

git clone https://github.com/e-commerce-sample/ecommerce-order-service.git
cd ecommerce-order-service
2

Start the service

./run.sh
This script will:
  • Clean the build directory
  • Start a local MySQL database using Docker Compose (port 13306)
  • Launch the Spring Boot application on port 8080
  • Enable remote debugging on port 5005
3

Verify the service is running

curl http://localhost:8080/actuator/health
You should see a response indicating the service is up:
{"status":"UP"}

​
Configuration

The service runs with the local profile by default, which uses these settings: 
spring:
  datasource:
    url: jdbc:mysql://localhost:13306/ecommerce_order_mysql
    username: root
    password: root

​
Make Your First API Call

Now that the service is running, let’s create an order.

​
Create an Order

curl -X POST http://localhost:8080/orders \
  -H "Content-Type: application/json" \
  -d '{
    "items": [
      {
        "productId": "12345",
        "count": 2,
        "itemPrice": 20.00
      }
    ],
    "address": {
      "province": "四川",
      "city": "成都",
      "detail": "天府软件园1号"
    }
  }'
The response includes the newly created order ID. Save this ID for the next steps.
The items array must contain at least one item. Each item requires:
  • productId: A unique product identifier (string)
  • count: Quantity (must be at least 1)
  • itemPrice: Unit price (decimal)

​
Retrieve an Order

Use the order ID from the previous step: 
curl http://localhost:8080/orders/{orderId}

​
List All Orders

Retrieve a paginated list of orders: 
curl "http://localhost:8080/orders?pageIndex=1&pageSize=10"

​
Update Product Count

Change the quantity of a product in an order: 
curl -X POST http://localhost:8080/orders/{orderId}/products \
  -H "Content-Type: application/json" \
  -d '{
    "productId": "12345",
    "count": 5
  }'
The total price will be automatically recalculated based on the new count.

​
Pay for an Order

Submit a payment for an order: 
curl -X POST http://localhost:8080/orders/{orderId}/payment \
  -H "Content-Type: application/json" \
  -d '{
    "paidPrice": 100.00
  }'
After successful payment, the order status will change to PAID.

​
Update Delivery Address

Change the detailed address for an order: 
curl -X POST http://localhost:8080/orders/{orderId}/address/detail \
  -H "Content-Type: application/json" \
  -d '{
    "detail": "天府软件园2号"
  }'

​
Available API Endpoints

Here’s a summary of all available endpoints:
MethodEndpointDescription
POST/ordersCreate a new order
GET/orders/{id}Retrieve an order by ID
GET/ordersList orders (paginated)
POST/orders/{id}/productsUpdate product count
POST/orders/{id}/paymentPay for an order
POST/orders/{id}/address/detailUpdate delivery address detail

​
Useful Commands

Run the full build with all tests:
./local-build.sh
This will:
  • Stop any existing Docker containers
  • Clean the build directory
  • Run unit tests, component tests, and API tests
  • Build the application
Stop MySQL and clear data:
./gradlew composeDown
Clear MySQL data without stopping:
./mysql-clean-local.sh
Login to MySQL:
./mysql-login-local.sh
Manually start MySQL:
./gradlew composeUp
Generate IntelliJ IDEA project:
./idea.sh
This will automatically open the project in IntelliJ IDEA.Remote debugging: The service is configured to listen on port 5005 for remote debugging. Configure your IDE to connect to localhost:5005.

​
Next Steps

Now that you have the service running locally, you can:

​
Troubleshooting

If you see an error about port 8080 or 13306 being in use:
  1. Check if another instance is running: 
    lsof -i :8080
lsof -i :13306
  2. Stop the conflicting service or change the port in application-local.yml
Ensure RabbitMQ is running:
docker ps | grep rabbitmq
If it’s not running, restart it from the devops repository:
cd ecommerce-devops/local/rabbitmq
./start-rabbitmq.sh
The service automatically starts MySQL via Docker Compose. If you encounter issues:
  1. Check Docker is running: 
    docker ps
  2. Manually start the database: 
    ./gradlew composeUp
  3. Check the logs for errors: 
    ./gradlew composeDown
./gradlew composeUp

Build docs developers (and LLMs) love

Get started for freeTalk to us