diff --git a/spring-cloud-alibaba-docs/src/main/asciidoc-zh/nacos-discovery.adoc b/spring-cloud-alibaba-docs/src/main/asciidoc-zh/nacos-discovery.adoc index 21a1177b..388e68f6 100644 --- a/spring-cloud-alibaba-docs/src/main/asciidoc-zh/nacos-discovery.adoc +++ b/spring-cloud-alibaba-docs/src/main/asciidoc-zh/nacos-discovery.adoc @@ -1 +1,317 @@ -== Spring Cloud Alibaba Nacos Discovery += Spring Cloud Alibaba Nacos Discovery + +该项目通过自动配置以及其他 Spring 编程模型的习惯用法为 Spring Boot 应用程序在服务注册与发现方面提供和 Nacos 的无缝集成。 +通过一些简单的注解,您可以快速来注册一个服务,并使用经过双十一考验的 Nacos 组件来作为大规模分布式系统的服务注册中心。 + +== 1. 服务注册发现: Nacos Discovery Starter + +服务发现是微服务架构体系中最关键的组件之一。如果尝试着用手动的方式来给每一个客户端来配置所有服务提供者的服务列表是一件非常困难的事,而且也不利于 +服务的动态扩缩容。Nacos Discovery Starter 可以帮助您将服务自动注册到 Nacos 服务端并且能够动态感知和刷新某个服务实例的服务列表。除此之外,Nacos +Discovery Starter 也将服务实例自身的一些元数据信息-例如 host,port,健康检查URL,主页等-注册到 Nacos 。Nacos 的获取和启动方式可以参考 https://nacos.io/zh-cn/docs/quick-start.html[Nacos 官网]。 + +=== 如何引入 Nacos Discovery Starter + +为了能够在你的工程下引入 Nacos Discovey Starter,使用group ID 为 `org.springframework.cloud` 和 artifact ID 为 `spring-cloud-starter-alibaba-nacos-discovery`。 +pom.xml 示例如下所示: + +[source,xml,indent=0] +---- + + + + + org.springframework.cloud + spring-cloud-alibaba-dependencies + 0.2.0.RELEASE + pom + import + + + + + + + + org.springframework.cloud + spring-cloud-starter-alibaba-nacos-discovery + + +---- + +=== 启动一个 Provider 应用 + +如果您使用的 Spring Cloud 版本是 Finchley.SR1 版本,那么这个时候您的Spring Boot版本的选择可需要额外的小心了,因为版本的不匹对,可能会导致许多意外的效果。 +Spring Cloud 的 Finchley.SR1 版本最佳实践的 Spring Boot 版本是 2.0.6.RELEASE。在启动您的一个 Provider 应用时请检查依赖的 Spring Boot 版本是否是 +1.X.Y.RELEASE 或者 2.1.0.RELEASE 的版本。如果不是,请更正到 2.0.6.RELEASE 版本。 + +以下步骤向您展示了如何将一个服务注册到 Nacos。 + +1. pom.xml的配置。一个完整的 pom.xml 配置如下所示: +[source, xml] +---- + + + 4.0.0 + + open.source.test + nacos-discovery-test + 1.0-SNAPSHOT + nacos-discovery-test + + + org.springframework.boot + spring-boot-starter-parent + 2.0.6.RELEASE + + + + + UTF-8 + UTF-8 + 1.8 + + + + + + org.springframework.cloud + spring-cloud-dependencies + Finchley.SR1 + pom + import + + + org.springframework.cloud + spring-cloud-alibaba-dependencies + 0.2.0.RELEASE + pom + import + + + + + + + org.springframework.boot + spring-boot-starter-web + + + + org.springframework.boot + spring-boot-starter-actuator + + + + org.springframework.cloud + spring-cloud-starter-alibaba-nacos-discovery + + + + + + + org.springframework.boot + spring-boot-maven-plugin + + + + +---- + +2. application.properties 配置。一些关于 Nacos 基本的配置也必须在 application.properties(也可以是application.yaml)配置,如下所示: +application.properties +[source,properties] +---- +server.port=8081 +spring.application.name=nacos-producer +spring.cloud.nacos.discovery.server-addr=127.0.0.1:8848 +management.endpoints.web.exposure.include=* +---- + + +NOTE: 如果不想使用 Nacos 作为您的服务注册与发现,可以将 `spring.cloud.nacos.discovery` 设置为 `false`。 + +3. 启动 Provider 示例。如下所示: +[source,java,indent=0] +---- +@SpringBootApplication +@EnableDiscoveryClient +public class NacosProviderDemoApplication { + + public static void main(String[] args) { + SpringApplication.run(NacosProducerDemoApplication.class, args); + } + + @RestController + public class EchoController { + @GetMapping(value = "/echo/{string}") + public String echo(@PathVariable String string) { + return "Hello Nacos Discovery " + string; + } + } +} +---- + +这个时候你就可以在 Nacos的控制台上看到注册上来的服务信息了。 + +NOTE: 再启动 Provider 应用之前 请先将 Nacos 服务启动。具体启动方式可参考 https://nacos.io/zh-cn/docs/quick-start.html[Naco 官网]。 + +=== 服务的 EndPoint + +spring-cloud-starter-alibaba-nacos-discovery 在实现的时候提供了一个EndPoint,EndPoint的访问地址为 `http://ip:port/actuator/nacos-discovery`。 +EndPoint 的信息主要提供了两类: + + 1、subscribe: 显示了当前有哪些服务订阅者 + 2、NacosDiscoveryProperties: 显示了当前服务实例关于 Nacos 的基础配置 + +一个服务实例访问 EndPoint 的信息如下所示: + +[source, json] +---- +{ + "subscribe": [ + { + "jsonFromServer": "", + "name": "nacos-provider", + "clusters": "", + "cacheMillis": 10000, + "hosts": [ + { + "instanceId": "30.5.124.156#8081#DEFAULT#nacos-provider", + "ip": "30.5.124.156", + "port": 8081, + "weight": 1.0, + "healthy": true, + "enabled": true, + "cluster": { + "serviceName": null, + "name": null, + "healthChecker": { + "type": "TCP" + }, + "defaultPort": 80, + "defaultCheckPort": 80, + "useIPPort4Check": true, + "metadata": { + + } + }, + "service": null, + "metadata": { + + } + } + ], + "lastRefTime": 1541755293119, + "checksum": "e5a699c9201f5328241c178e804657e11541755293119", + "allIPs": false, + "key": "nacos-producer", + "valid": true + } + ], + "NacosDiscoveryProperties": { + "serverAddr": "127.0.0.1:8848", + "endpoint": "", + "namespace": "", + "logName": "", + "service": "nacos-provider", + "weight": 1.0, + "clusterName": "DEFAULT", + "metadata": { + + }, + "registerEnabled": true, + "ip": "30.5.124.201", + "networkInterface": "", + "port": 8082, + "secure": false, + "accessKey": "", + "secretKey": "" + } +} +---- + +=== 启动一个 Consumer 应用 + +Consumer 的应用可能还没像启动一个 Provider 应用那么简单。因为在 Consumer 端需要去调用 Provider 端提供的REST 服务。例子中我们使用最原始的一种方式, +即显示的使用 LoadBalanceClient 和 RestTemolate 结合的方式来访问。 +pom.xml 和 application.properties 的配置可以参考 1.2 小结。启动一个 Consumer应用的示例代码如下所示: + +NOTE: 通过带有负载均衡的RestTemplate 和 FeignClient 也是可以访问的。 + +[source, java] +---- +@SpringBootApplication +@EnableDiscoveryClient +public class NacosConsumerApp { + + @RestController + public class NacosController{ + + @Autowired + private LoadBalancerClient loadBalancerClient; + @Autowired + private RestTemplate restTemplate; + + @Value("${spring.application.name}") + private String appName; + + @GetMapping("/echo/app-name") + public String echoAppName(){ + //使用 LoadBalanceClient 和 RestTemolate 结合的方式来访问 + ServiceInstance serviceInstance = loadBalancerClient.choose("nacos-provider"); + String url = String.format("http://%s:%s/echo/%s",serviceInstance.getHost(),serviceInstance.getPort(),appName); + System.out.println("request url:"+url); + return restTemplate.getForObject(url,String.class); + } + + } + + //实例化 RestTemplate 实例 + @Bean + public RestTemplate restTemplate(){ + + return new RestTemplate(); + } + + public static void main(String[] args) { + + SpringApplication.run(NacosConsumerApp.class,args); + } +} +---- + +这个例子中我们注入了一个 LoadBalancerClient 的实例,并且手动的实例化一个 RestTemplate,同时将 `spring.application.name` 的配置值 注入到应用中来, +目的是调用 Provider 提供的服务时,希望将当前配置的应用名给显示出来。 + +NOTE: 在启动 Consumer 应用之前请先将 Nacos 服务启动好。具体启动方式可参考 https://nacos.io/zh-cn/docs/quick-start.html[Nacos 官网]。 + +启动后,访问 Consumer 提供出来的 `http://ip:port/echo/app-name` 接口。我这里测试启动的 port是 8082。访问结果如下所示: + + 访问地址:http://127.0.0.1:8082/echo/app-name + 访问结果:Hello Nacos Discovery nacos-consumer + +== 2. 关于 Nacos Starter 更多的配置项信息 + +更多关于 spring-cloud-starter-alibaba-nacos-discovery 的 starter 配置项如下所示: + +:frame: topbot +[width="60%",options="header"] +|==== +^|配置项 ^|Key ^|默认值 ^|说明 +|`服务端地址`|`spring.cloud.nacos.discovery.server-addr`|`无`| `Nacos Server 启动监听的ip地址和端口` +|`服务名`|`spring.cloud.nacos.discovery.service`|`${spring.application.name}`|`给当前的服务命名` +|`权重`|`spring.cloud.nacos.discovery.weight`|`1`|`取值范围 1 到 100,数值越大,权重越大` +|`网卡名`|`spring.cloud.nacos.discovery.network-interface`|`无`|`当IP未配置时,注册的IP为此网卡所对应的IP地址,如果此项也未配置,则默认取第一块网卡的地址` +|`注册的IP地址`|`spring.cloud.nacos.discovery.ip`|`无`|`优先级最高` +|`注册的端口`|`spring.cloud.nacos.discovery.port`|`-1`|`默认情况下不用配置,会自动探测` +|`命名空间`|`spring.cloud.nacos.discovery.namespace`|`无`|`常用场景之一是不同环境的注册的区分隔离,例如开发测试环境和生产环境的资源(如配置、服务)隔离等。` +|`AccessKey`|`spring.cloud.nacos.discovery.access-key`|`无`|`当要上阿里云时,阿里云上面的一个云账号名` +|`SecretKey`|`spring.cloud.nacos.discovery.secret-key`|`无`|`当要上阿里云时,阿里云上面的一个云账号密码` +|`Metadata`|`spring.cloud.nacos.discovery.metadata`|`无`|`使用Map格式配置,用户可以根据自己的需要自定义一些和服务相关的元数据信息` +|`日志文件名`|`spring.cloud.nacos.discovery.log-name`|`无`| +|`接入点`|`spring.cloud.nacos.discovery.enpoint`|`UTF-8`|`地域的某个服务的入口域名,通过此域名可以动态地拿到服务端地址` +|`是否集成Ribbon`|`ribbon.nacos.enabled`|`true`|`一般都设置成true即可` +|==== +