How Nacos Powers Service Registration in Spring Cloud: Architecture & Mechanics

Nacos Architecture

Provider APP: service provider

Consumer APP: service consumer

Name Server: implements high‑availability routing via VIP or DNS

Nacos Server: provides Open API, Config Service, Naming Service; uses a Raft‑based consistency protocol for data sync

Nacos Console: management console

Principles of a Service Registry

Service instances register to the registry on startup and deregister on shutdown.

Consumers query the registry to obtain available instances.

The registry performs health‑check calls to verify instance readiness.

When Spring Cloud Completes Registration

Spring Cloud defines the standard registration interface

org.springframework.cloud.client.serviceregistry.ServiceRegistry

. Implementations such as NacoServiceRegistry integrate Nacos.

The auto‑configuration file META-INF/spring.factories registers AutoServiceRegistrationAutoConfiguration, which creates an AutoServiceRegistration bean.

AutoServiceRegistrationAutoConfiguration

injects AutoServiceRegistration, whose hierarchy includes AbstractAutoServiceRegistration and the concrete NacosAutoServiceRegistration.

The registration is triggered by the WebServerInitializedEvent; AbstractAutoServiceRegistration listens to this event and calls this.bind(event), which eventually invokes NacosServiceRegistry.register().

Implementation of NacosServiceRegistry

The registry method calls namingService.registerInstance from the Nacos client SDK.

Heartbeat creation uses beatReactor.addBeatInfo(), while serverProxy.registerService() performs the actual registration.

Heartbeat Mechanism

The client schedules periodic packets to the server; a missing response within the timeout marks the instance as unhealthy, and the server updates the service status accordingly.

Registration Principle

Nacos offers both SDK and Open API for service registration; both ultimately send an HTTP request to nacos/v1/ns/instance.

Open API diagram:

SDK diagram:

On the server side, InstanceController in the nacos-naming module handles the request, extracts serviceName and namespaceId, and calls registerInstance.

Create a Service object stored in a ConcurrentHashMap.

Retrieve the Service via getService.

Add the instance with addInstance.

The service.init() method schedules periodic checks; if a heartbeat is missed, the instance is marked unhealthy and a service‑change event is emitted.

Service Provider Address Query

Open API request to nacos/v1/ns/instance/list returns provider addresses.

SDK provides equivalent functionality.

InstanceController.list

parses request parameters, calls doSrvIPXT to obtain the service list, then assembles a JSON response.

Dynamic Service Address Perception

Clients subscribe to service updates via subscribe (or selectInstance with subscribe=true), receiving push notifications when providers change.

The HostReactor runs an UpdateTask thread that pulls the latest address list every 10 seconds; heartbeat failures trigger server‑side push messages, which the client processes via processServiceJSON to update its local cache.

Client subscribes and periodically pulls updates.

Server pushes notifications when a provider becomes unhealthy.

Client parses the push and refreshes its address list.

In summary, Nacos client registers services via Open API or SDK, the server stores service metadata in a concurrent map, maintains heartbeat checks, synchronizes data using a Raft‑based consistency protocol, and provides dynamic discovery through subscription and pull mechanisms.