Mastering Microservice Architecture: Core Principles and Practical Guidelines

Introduction

Microservices have become the de‑facto standard for software architecture in recent years. As enterprises digitise, they often migrate from monolithic or SOA systems to microservices, but the transformation must follow clear principles.

Key Principles

Two immutable principles guide our practice: services must revolve around business needs and service interactions must be standardised . We split the practice into an initial stage and a production stage.

Initial Stage

During the early phase the focus is on business modelling rather than on technical frameworks such as RPC, Service Discovery, or Circuit Breaker. The main rules are:

Ensure a single business service aggregates efficiently.

Reduce inter‑service calls to avoid excessive distributed processing.

Domain‑Driven Design (DDD) helps define service boundaries, but there is no one‑size‑fits‑all pattern; services evolve with business requirements.

Production Stage

After business modelling, implementation concentrates on the standardised interaction layer rather than specific frameworks. Interaction standards are defined at three levels: protocol, framework, and interface.

Protocol Standard

We select protocols that match business scenarios, including authentication, encryption, internal API communication, and external service contracts, to ensure consistent communication across units.

Framework Standard

We avoid heavyweight code‑generation tools and choose the minimal runtime framework that satisfies our protocol requirements, tailoring it to the specific business platform.

Interface Standard

Both internal and external APIs follow a unified design: RESTful conventions for business‑exposed services and high‑performance RPC for internal calls, with consistent request methods, headers, parameters, response structures, error handling, and logging.

Service Splitting and Aggregation

Splitting and aggregating services must always keep business goals in mind. Two implementation approaches are considered: business‑support (focus on domain logic and fine‑grained entities) and tool‑support (shared utilities such as logging, exception handling, and configuration).

Service Architecture Selection

Choosing the right stack depends on team expertise, language preferences, service registry, gateway, load balancing, deployment model (bare‑metal, virtual, container), and supported protocols. Our current stack includes Spring Boot, Dubbo, gRPC, Service Mesh, Zookeeper/Eureka/Consul, Kong/OpenResty, Nginx, HAProxy, Kubernetes, Redis, MySQL, RabbitMQ, Jenkins, Maven, GitLab, Swagger, and Docker.

Service Interface Design

APIs are the sole entry point for business logic. We categorise endpoints into collection operations, entity operations, error handling, parameter validation, unified responses, audit logging, etc.

Unified Request & Response Standard

Requests follow RESTful conventions with clear HTTP methods (GET, POST, PUT, PATCH, DELETE) and a uniform URL prefix (e.g., POST /api/cloud/v1/students?exist={skip,replace}). Headers include Content-Type, Accept, Authorization, and optional Accept-Language. Responses contain standard headers and a JSON body with code, message, body, and error fields.

{
  "code": 200,
  "message": "获取学生列表成功",
  "body": {
    "links": [{"rel": "self", "href": "http://localhost:8080/api/cloud/v1/students?..."}],
    "metadata": [],
    "content": [{
      "id": 1,
      "name": "test3",
      "status": "running",
      "props": "test",
      "ownerId": 1,
      "gmtCreate": "2019-03-11 10:42:15"
    }]
  },
  "errors": {}
}

Unified Error Handling

200/201 – success

202 – async processing with status URI

400 – partial success with error list

401 – authentication missing

403 – unauthorized

406 – not acceptable format

415 – unsupported media type

422 – unprocessable entity

429 – too many requests

500 – internal server error

Unified Logging Interception

All inbound and outbound requests are intercepted via AOP to record logs and perform cross‑cutting concerns such as authentication.

Unified Data Return Standard

Responses follow a consistent schema: {"code":..., "message":..., "body":..., "error":...}, enabling centralized handling.

Legacy Issues

During implementation we encountered challenges such as service concurrency limits, internal bottlenecks, database performance, container integration, call‑chain loops, and cache design, which we continue to address.