Quick Start for Nacos Spring Cloud Projects

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

For more details about Nacos Spring Cloud: Nacos Config and Nacos Discovery.

The quick start includes two samples:

  • How to enable dynamic configuration updates with Nacos server and spring-cloud-starter-alibaba-nacos-config;
  • How to enable service registration and discovery with Nacos server and spring-cloud-starter-alibaba-nacos-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 Cloud project.

Sample project: nacos-spring-cloud-config-example

  • Add the Nacos Spring Cloud dependency.
  1. <dependency>
  2.     <groupId>org.springframework.cloud</groupId>
  3.     <artifactId>spring-cloud-starter-alibaba-nacos-config</artifactId>
  4.     <version>${latest.version}</version>
  5. </dependency>

Note: Version 0.2.x.RELEASE is compatible with the Spring Boot 2.0.x line. Version 0.1.x.RELEASE is compatible with the Spring Boot 1.x line.

  • Configure the Nacos Server address and Specify the application name in bootstrap.properties :
  1. spring.cloud.nacos.config.server-addr=127.0.0.1:8848
  3. spring.application.name=example

Note: The value of spring.application.name will be used to construct part of the dataId in Nacos configuration management.

In Nacos Spring Cloud, the format of dataId is as follows:

  1. ${prefix}-${spring.profile.active}.${file-extension}
  • The value of prefix is the value of spring.application.name by default. You can also configure this value in spring.cloud.nacos.config.prefix.
  • spring.profile.active is the profile of the current environment. For more details, refer to Spring Boot Document.Note: When the value of spring.profile.active is empty, the corresponding hyphen - will be deleted, and the format of dataId becomes: ${prefix}.${file-extension}
  • file-exetension is the data format of the configuration content, and can be configured in spring.cloud.nacos.config.file-extension . Currently only the properties and yaml type is supported.
  • Add the native @RefreshScope annotation of Spring Cloud to enable autorefresh of configuration updates:
  1. @RestController
  2. @RequestMapping("/config")
  3. @RefreshScope
  4. public class ConfigController {
  6.     @Value("${useLocalCache:false}")
  7.     private boolean useLocalCache;
  9.     @RequestMapping("/get")
  10.     public boolean get() {
  11.         return useLocalCache;
  12.     }
  13. }
  • Call Nacos Open API to publish a configuration to the Nacos server. Assume the dataId is example.properties，and the content is useLocalCache=true.
  1. curl -X POST "http://127.0.0.1:8848/nacos/v1/cs/configs?dataId=example.properties&group=DEFAULT_GROUP&content=useLocalCache=true"

  • Run NacosConfigApplicationand call curl http://localhost:8080/config/get，You will get a returned value of true.

  • Call Nacos Open API again to publish an updated configuration to the Nacos server. Assume the dataId isexample.properties，and the content is useLocalCache=false.

  1. curl -X POST "http://127.0.0.1:8848/nacos/v1/cs/configs?dataId=example.properties&group=DEFAULT_GROUP&content=useLocalCache=false"
  • Access http://localhost:8080/config/getagain and the returned value became false，indicating that the value of useLocalCachein your application has been updated.

Enable Service Discovery

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

Sample project: nacos-spring-cloud-discovery-example

  • Add the Nacos Spring Cloud dependency.
  1. <dependency>
  2.     <groupId>org.springframework.cloud</groupId>
  3.     <artifactId>spring-cloud-starter-alibaba-nacos-discovery</artifactId>
  4.     <version>${latest.version}</version>
  5. </dependency>

Note: Version 0.2.x.RELEASE is compatible with the Spring Boot 2.0.x line. Version 0.1.x.RELEASE is compatible with the Spring Boot 1.x line.

  • Configure the service provider, so that it can register its services to the Nacos server.
    i. Add the Nacos server address in application.properties :
  1. server.port=8070
  2. spring.application.name=service-provider
  4. spring.cloud.nacos.discovery.server-addr=127.0.0.1:8848

ii. Enable service discovery by adding the Spring Cloud native annotation of @EnableDiscoveryClient:

  1. @SpringBootApplication
  2. @EnableDiscoveryClient
  3. public class NacosProviderApplication {
  5.     public static void main(String[] args) {
  6.         SpringApplication.run(NacosProviderApplication.class, args);
  7.     }
  9.     @RestController
  10.     class EchoController {
  11.         @RequestMapping(value = "/echo/{string}", method = RequestMethod.GET)
  12.         public String echo(@PathVariable String string) {
  13.             return "Hello Nacos Discovery " + string;
  14.         }
  15.     }
  16. }
  • Configure the service consumer so that it can discover the services that it would like to call on the Nacos server.
    i. Configure the Nacos server address in application.properties :
  1. server.port=8080
  2. spring.application.name=service-consumer
  4. spring.cloud.nacos.discovery.server-addr=127.0.0.1:8848

ii. Add the Spring Cloud native annotation of @EnableDiscoveryClient to enable service discovery. Add the @LoadBalanced annotation for the RestTemplate instance, and enable the integration of @LoadBalanced and Ribbon:

  1. @SpringBootApplication
  2. @EnableDiscoveryClient
  3. public class NacosConsumerApplication {
  5.     @LoadBalanced
  6.     @Bean
  7.     public RestTemplate restTemplate() {
  8.         return new RestTemplate();
  9.     }
  11.     public static void main(String[] args) {
  12.         SpringApplication.run(NacosConsumerApplication.class, args);
  13.     }
  15.     @RestController
  16.     public class TestController {
  18.         private final RestTemplate restTemplate;
  20.         @Autowired
  21.         public TestController(RestTemplate restTemplate) {this.restTemplate = restTemplate;}
  23.         @RequestMapping(value = "/echo/{str}", method = RequestMethod.GET)
  24.         public String echo(@PathVariable String str) {
  25.             return restTemplate.getForObject("http://service-provider/echo/" + str, String.class);
  26.         }
  27.     }
  28. }
  • Start ProviderApplication and ConsumerApplication , and call http://localhost:8080/echo/2018. You will get a returned message of Hello Nacos Discovery 2018.