Skip to main content
Version: 1.X

Quick Start for Nacos Spring Projects

This quick start introduces how to enable Nacos configuration management and service discovery features for your Spring project.

For more details about Nacos Spring Boot: nacos-spring-project.

The quick start includes two samples:

  • How to enable Nacos server and Nacos Spring configuration modules to implement dynamic configuration management;
  • How to enable Nacos server and Nacos Spring service discovery modules to implement service registration and discovery.

Prerequisite​

Follow instructions in Nacos Quick Start to download Nacos and start the Nacos server.

Enable Configuration Service​

Once you start the Nacos server, you can follow the steps below to enable the Nacos configuration management service for your Spring project.

Sample project: nacos-spring-config-example

  1. Add the Nacos Spring dependency.
<dependency>
    <groupId>com.alibaba.nacos</groupId>
    <artifactId>nacos-spring-context</artifactId>
    <version>${latest.version}</version>
</dependency>

The the latest version can be available in maven repositories such as "mvnrepository.com".

  1. Add the @EnableNacosConfig annotation to enable the configuration service. In the code below, @NacosPropertySource is used to load the configuration source whose dataId is example , and autorefresh is also enabled:
@Configuration
@EnableNacosConfig(globalProperties = @NacosProperties(serverAddr = "127.0.0.1:8848"))
@NacosPropertySource(dataId = "example", autoRefreshed = true)
public class NacosConfiguration {

}
  1. Specify the property value for the @NacosValue annotation of Nacos. 
@Controller
@RequestMapping("config")
public class ConfigController {

    @NacosValue(value = "${useLocalCache:false}", autoRefreshed = true)
    private boolean useLocalCache;

    @RequestMapping(value = "/get", method = GET)
    @ResponseBody
    public boolean get() {
        return useLocalCache;
    }
}

  1. Start Tomcat and call curl http://localhost:8080/config/get to get configuration information. Because no configuration has been published, a falsemessage is returned.

  2. Now you can call Nacos Open API to publish a configruation to the Nacos server. Assume the dataId is example, and content is useLocalCache=true.

curl -X POST "http://127.0.0.1:8848/nacos/v1/cs/configs?dataId=example&group=DEFAULT_GROUP&content=useLocalCache=true"
  1. Access http://localhost:8080/config/getagain, and you get a return message of true, indicating that the value of useLocalCachein your application has been updated.

Enable Service Discovery​

Now you would like to enable the service discovery function of Nacos in your Spring project.

Sampe project: nacos-spring-discovery-example

  1. Add the Nacos Spring dependency.
<dependency>
    <groupId>com.alibaba.nacos</groupId>
    <artifactId>nacos-spring-context</artifactId>
    <version>${latest.version}</version>
</dependency>

The the latest version can be available in maven repositories such as "mvnrepository.com".

  1. Add the @EnableNacosDiscovery annotation to enable the service discovery function of Nacos:
@Configuration
@EnableNacosDiscovery(globalProperties = @NacosProperties(serverAddr = "127.0.0.1:8848"))
public class NacosConfiguration {

}
  1. Use @NacosInjected to inject a Nacos NamingService instance:
@Controller
@RequestMapping("discovery")
public class DiscoveryController {

    @NacosInjected
    private NamingService namingService;

    @RequestMapping(value = "/get", method = GET)
    @ResponseBody
    public List<Instance> get(@RequestParam String serviceName) throws NacosException {
        return namingService.getAllInstances(serviceName);
    }
}

  1. Start Tomcat and call curl http://localhost:8080/discovery/get?serviceName=example, and the return value is an empty JSON array [].

  2. Call Nacos Open API to register a service called exampleto the Nacos Server.

curl -X POST 'http://127.0.0.1:8848/nacos/v1/ns/instance?serviceName=example&ip=127.0.0.1&port=8080'
  1. Access curl http://localhost:8080/discovery/get?serviceName=exampleagain, and you will get the following return:
[
  {
    "instanceId": "127.0.0.1#8080#DEFAULT#example",
    "ip": "127.0.0.1",
    "port": 8080,
    "weight": 1.0,
    "healthy": true,
    "cluster": {
      "serviceName": null,
      "name": "",
      "healthChecker": {
        "type": "TCP"
      },
      "defaultPort": 80,
      "defaultCheckPort": 80,
      "useIPPort4Check": true,
      "metadata": {}
    },
    "service": null,
    "metadata": {}
  }
]