Getting Started with a Hands‑On Microservices Learning Project

Project Overview

The micro-service repository contains three independent Spring Boot applications—gateway, order, and stock—combined with Nacos, MySQL, Redis, RocketMQ, and Seata to illustrate typical microservice scenarios from beginner to advanced levels.

Problem Scenario

Product Management – create products and maintain inventory.

Normal Order – a user places an order; the order service calls the stock service via gRPC to deduct inventory.

Order Sharding – order tables are sharded by user_id across multiple databases.

Distributed Transaction – the "write order + deduct stock" operation must be atomic.

Flash Sale (秒杀) – 100 items, 500 concurrent requests, no overselling, and ability to handle traffic spikes.

Overall Architecture

All HTTP traffic enters through a single gateway at :8890; clients never call order or stock services directly. Synchronous gRPC is used for normal orders, while flash‑sale orders use Redis Lua pre‑deduction plus asynchronous RocketMQ processing.

Technology Stack

Language : Java 21 (LTS, virtual‑thread friendly)

Framework : Spring Boot 3.5.x (Web, gRPC, Actuator)

Architecture : DDD seven‑module layout (domain layer decoupled from infrastructure)

Gateway : Spring Cloud Gateway (routing, TraceId, filter chain)

Service Communication : gRPC + Protobuf (order → stock synchronous call)

Service Registry / Config : Nacos 3.x (service discovery & dynamic configuration)

Data Access : MyBatis‑Plus + Flyway (ORM & DB migration)

Sharding : ShardingSphere‑JDBC (order tables sharded by user_id into 4 shards)

Distributed Transaction : Seata AT (strong consistency for normal orders)

Cache / Messaging : Redis, RocketMQ (flash‑sale pre‑deduction & async throttling)

Containerization : Docker Compose (one‑click local startup of all components)

Project Structure

micro-service/

micro-gateway/ – API gateway

micro-order/ – Order service (includes flash‑sale logic)

micro-stock/ – Stock / product service

docker/ – Docker Compose files and middleware configs

docs/ – Documentation

scripts/ – Nacos initialization, load‑test scripts, etc.

specs/ – Requirement specs & task list

DDD Seven‑Module Layout (per service)

{prefix}-api          → Request/Response DTO

{prefix}-trigger      → REST / gRPC entry point

{prefix}-case         → Use‑case orchestration (application layer)

{prefix}-domain       → Entities, repository interfaces, domain services

{prefix}-infrastructure → MyBatis, gRPC client, Redis, MQ implementations

{prefix}-common       → Common enums, exceptions

{prefix}-bootstrap    → Bootstrap class, application.yml

Dependency direction: trigger → case → domain ← infrastructure. The domain layer does not depend on concrete technology implementations.

Prerequisites

Docker Desktop (Compose v2)

JDK 21

Maven 3.8+

curl (optional jq for JSON formatting)

Clone Repository

git clone https://gitcode.com/qq_37953312/micro-service

cd micro-service

Startup Options

Option 1 – Full‑Stack One‑Click Startup (recommended for first‑time experience)

cd docker && docker compose up -d --build

Check container status: docker compose ps Gateway health check (expect "status":"UP" in the JSON response):

curl -s http://localhost:8890/actuator/health

Option 2 – Infrastructure Only + IDE Debug (daily development)

cd docker && docker compose -f docker-compose.infra.yml up -d

./scripts/init-nacos-namespaces.sh

./scripts/import-nacos-config.sh all

Start services in order with Maven:

cd micro-stock && mvn -pl stock-bootstrap -am spring-boot:run

cd micro-order && mvn -pl order-bootstrap -am spring-boot:run

cd micro-gateway && mvn -pl gateway-bootstrap -am spring-boot:run

Run the First Business Chain

After the environment is ready, use the gateway to execute the full flow: create a product, query it, place an order, and verify stock deduction.

Step 1 – Create Product

curl -s -X POST http://localhost:8890/api/stock/products \
  -H "Content-Type: application/json" \
  -d '{"name":"学习用书","description":"Microservices 101","price":"59.00","stock":100}'

Record the returned data.id as PRODUCT_ID. Expected code: 0.

Step 2 – Query Product List

curl -s "http://localhost:8890/api/stock/products?page=1&size=10"

The list should contain the newly created product.

Step 3 – Create Order

curl -s -X POST http://localhost:8890/api/orders \
  -H "Content-Type: application/json" \
  -H "X-User-Id: 1001" \
  -d '{"productId": PRODUCT_ID, "quantity": 2}'

code: 0

data.status: "PENDING_PAYMENT"

data.totalAmount: "118.00"

(59.00 × 2)

Step 4 – Verify Stock Deduction

curl -s http://localhost:8890/api/stock/products/PRODUCT_ID/stock

Expected availableStock: 98 (100 − 2).

Step 5 – View TraceId (optional)

Resend a request and observe the X-Trace-Id response header; the ID propagates through gateway → order → stock, aiding log tracing.

Port & Management Console Quick Reference

micro-gateway – 8890 – http://localhost:8890/actuator/health micro-order – 8891 – http://localhost:8891/actuator/health micro-stock – 8892 – http://localhost:8892/actuator/health micro-stock gRPC – 9892 – grpcurl debugging

Nacos UI – 8849 – http://localhost:8849 (user: nacos, password: nacos)

Nacos API – 8848 – client connection address

MySQL – 3306 – user: micro, password: micro123 Redis – 6379

RocketMQ Dashboard – 8180 – http://localhost:8180 Seata Server – 8091 –

http://localhost:8091

Business Databases

micro_stock – owned by micro‑stock service

order_db_0 / order_db_1 – sharded databases owned by micro‑order service

nacos – Nacos metadata

Series Reading Roadmap

00 Intro (this article) – project overview and first verification.

01 Platform & Middleware – DDD, gRPC, Nacos, RocketMQ, Redis; code organization and middleware roles.

02 Three Services & Orchestration – responsibilities of each service, gateway routing, development‑mode startup.

03 Data & Transactions – sharding routing and cross‑service strong consistency with Seata.

04 Flash Sale & Consistency – high‑concurrency flash‑sale principles, Redis Lua + RocketMQ, comparison with Seata.

Code Repository

https://gitcode.com/qq_37953312/micro-service