You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@servicecomb.apache.org by li...@apache.org on 2020/05/29 09:15:01 UTC
[servicecomb-docs] branch master updated: [SCB-1950]add document on
how to using local registry to call 3rd parties
This is an automated email from the ASF dual-hosted git repository.
liubao pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/servicecomb-docs.git
The following commit(s) were added to refs/heads/master by this push:
new ab663e7 [SCB-1950]add document on how to using local registry to call 3rd parties
ab663e7 is described below
commit ab663e75927aeffb3c8ff9f64367813d0a06916d
Author: liubao <bi...@qq.com>
AuthorDate: Fri May 29 11:15:51 2020 +0800
[SCB-1950]add document on how to using local registry to call 3rd parties
---
.../docs/featured-topics/upgrading/2_0_1T2_1_0.md | 9 ++
.../zh_CN/docs/registry/introduction.md | 50 +++++++--
.../zh_CN/docs/registry/multi-registries.md | 123 +++++++++++++++++++++
java-chassis-reference/zh_CN/docs/toc.md | 1 +
java-chassis-reference/zh_CN/mkdocs.yml | 1 +
5 files changed, 175 insertions(+), 9 deletions(-)
diff --git a/java-chassis-reference/zh_CN/docs/featured-topics/upgrading/2_0_1T2_1_0.md b/java-chassis-reference/zh_CN/docs/featured-topics/upgrading/2_0_1T2_1_0.md
index 08c91fb..1ed76e8 100644
--- a/java-chassis-reference/zh_CN/docs/featured-topics/upgrading/2_0_1T2_1_0.md
+++ b/java-chassis-reference/zh_CN/docs/featured-topics/upgrading/2_0_1T2_1_0.md
@@ -47,3 +47,12 @@ servicecomb.service.registry.discovery.enabled: true
```
详细开发指南参考[注册发现说明](../../registry/introduction.md)
+
+## 服务注册发现 API 的变化
+
+如果直接使用了 `RegistryUtils` 接口， 建议切换到 `DiscoveryManager` 或者 `RegistrationManager`，
+尽管 `RegistryUtils` 接口仍然可以使用。
+
+如果直接使用了 `DiscoveryTreee` 接口，2.1. 将服务发现的接口移动到了 `org.apache.servicecomb.registry`，
+当出现编译错误的时候，重新 import 对应的新 package 类即可。
+
diff --git a/java-chassis-reference/zh_CN/docs/registry/introduction.md b/java-chassis-reference/zh_CN/docs/registry/introduction.md
index 0dc65ff..718d3e4 100644
--- a/java-chassis-reference/zh_CN/docs/registry/introduction.md
+++ b/java-chassis-reference/zh_CN/docs/registry/introduction.md
@@ -6,8 +6,8 @@
最常见的服务发现机制是引入一个中间件服务， 微服务 B 启动的过程中，向中间件服务注册自己的网络地址信息，微服务 A
访问 B 的时候， 首先从中间件服务查询微服务 B 的网络地址信息。
-对于规模较小的系统，也可以不使用中间件服务，而是通过配置文件的方式，在微服务 A 中指定微服务 B 的地址。由于这种
-静态配置的方式，需要提前知道地址信息，比较适合很小规模的系统。
+对于规模较小的系统，也可以不使用中间件服务，而是通过配置文件的方式，在微服务 A 中指定微服务 B 的地址。这种方式
+适合组网情况固定，不会弹性扩缩容的场景。
在局域网环境下，还可以通过广播协议，比如 mDNS 发现其他的服务，这种方式不需要做额外的配置。
@@ -15,15 +15,14 @@
* 微服务信息
- servicecomb 的微服务信息在类 `Microservice` 中定义。 它主要包含应用ID (appId)， 微服务名称 (serviceName),
- 微服务版本(version)，环境(environment) 等信息， 还包括契约。 契约是 servicecomb 治理管控的基础，注册
- 发现的实现，需要包括契约。
+ servicecomb 的微服务信息在类 `Microservice` 中定义。 它主要包含应用 ID (appId)， 微服务名称 (serviceName),
+ 微服务版本(version)，环境(environment) 等信息， 还包括契约。 契约是 servicecomb 治理管控的基础。
* 实例信息
servicecomb 的实例信息在类 `MicroserviceInstance` 中定义。 它主要包含网络地址(endpoints) 信息。
-不同的注册发现机制，可能注册的信息和发现的信息不包括上述信息的全集，可以通过不同的注册发现机制，提供完整的信息。
+不同的注册发现机制，可能注册的信息和发现的信息不包括上述信息的全集，可以通过组合不同的注册发现机制，提供完整的信息。
比如，可以通过 mDNS 的方式发现网络地址(endpoints)信息， 可以通过配置文件的方式，发现契约信息。
## 使用服务中心
@@ -31,7 +30,7 @@
服务中心(servicecomb-service-center) 提供了完备的注册发现机制， 实现了所有 `Microservice` 和 `MicroserviceInstance` 信息的注册和发现，
是 servicecomb 缺省使用的注册发现机制。
-服务中心支持使用PULL和PUSH两种模式通知实例变化， 开发者可以配置服务中心集群地址、连接参数以及心跳管理等。
+服务中心支持使用 `PULL` 和 `PUSH` 两种模式通知实例变化， 开发者可以配置服务中心集群地址、连接参数以及心跳管理等。
* 表1-1 访问服务中心常用的配置项
@@ -53,8 +52,7 @@ servicecomb 提供了本地注册发现机制。服务注册时， `Microservice
都注册到微服务本地内存。 服务发现时，从配置文件(registry.yaml)中读取其他服务的 `Microservice` 和
`MicroserviceInstance` 信息，从目录 `microservices/{serviceName}/{schemaId}.yaml` 或者
`applications/{appId}/{serviceName}/{schemaId}.yaml` 读取微服务的契约
-信息。本地注册发现主要用于一些小规模，组网确定的场景使用。由于一个微服务只有一个存放契约的目录，不能存放
-多个版本的微服务契约，本地注册发现不支持灰度场景。
+信息。本地注册发现主要用于一些小规模，组网确定的场景使用。
* registry.yaml 格式
@@ -92,3 +90,37 @@ servicecomb 提供了本地注册发现机制。服务注册时， `Microservice
`registry.yaml` 指定了微服务的基本信息：应用ID (appId)， 微服务名称 (serviceName),
微服务版本(version)，环境(environment) 和契约；微服务实例基本信息：网络地址(endpoints)。
+
+## 同时使用多个注册发现
+
+从 2.1.0 版本开始，可以同时使用多个注册发现的实现。组合不同的注册发现的实现，能够满足一些非常重要场景的需求。
+详细参考[组合使用多个实现](multi-registries.md)的介绍。
+
+### 使用多个服务中心的约束和行为
+
+* 服务注册
+
+使用多个服务中心，同时往多个服务中心注册。 当需要获取本服务 `Microservice` 和 `MicroserviceInstance`
+信息的时候，不同的注册中心的 `Microservice` ID 和 `MicroserviceInstance` ID 是不同的。
+`RegistrationManager` 接口返回的实例是优先级最高的 `Registration` 实现的实例。
+
+* 服务发现
+
+如果多个注册中心都存在同一个微服务信息， 这些微服务信息必须满足 java chassis 的接口兼容性策略。 比如微服务
+A 存在 v1, v2, v3 三个版本， 在不同的注册中心注册的同一个版本 v3， 必须契约一样；v1， v2，v3 并存的情况下，
+v2 的接口需要兼容 v1， v3 的接口需要兼容 v2 （接口可以多，不能少， 要求开发的时候， 只增加接口，不删除接口）。
+
+如果不能满足上述约束， 请求过程中可能出现 404 找不到接口的错误。 这种错误在使用单个注册发现的情况下极少
+出现，参考[微服务接口兼容常见问题](../question-and-answer/interface-compatibility.md)。 在多个
+注册中心的情况下，使用不恰当就容易出现，比如通过 `本地服务注册发现` 定义了微服务 A 的信息， 只包含 2 个
+schema， 同时往 `服务中心` 注册了全量的 5 个 schema ， 并且本地服务注册发现的版本 v3 高于 服务中心
+的 v1 版本， 那么这种情况就可能出现调用接口提示 404 的错误。
+
+因此建议在使用多个注册中心的时候， 满足下面的约束：
+
+ 1. 一个微服务只在一个注册中心有信息，比如 本地注册中心只定义三方服务，服务中心用于 java chassis 服务注册发现。 或者，
+ 2. 一个微服务在多个注册中心的信息是一样的，比如 使用多个 region 的服务中心，他们注册发现流程一样，可以保证信息一样。
+
+这样能够避免违背接口兼容性策略。
+
+
diff --git a/java-chassis-reference/zh_CN/docs/registry/multi-registries.md b/java-chassis-reference/zh_CN/docs/registry/multi-registries.md
new file mode 100644
index 0000000..cd8ad22
--- /dev/null
+++ b/java-chassis-reference/zh_CN/docs/registry/multi-registries.md
@@ -0,0 +1,123 @@
+# 组合使用多个实现
+
+通过组合多个服务注册发现实现，能够满足很多特殊场景的开发要求。
+
+***注意：*** 组合使用多个实现，必须使用 2.1.0 及其以上版本。
+
+## 调用第三方服务
+
+可以有非常多的方式调用第三方服务，比如采用第三方提供的Rest Client。 但是需要提供一种
+透明的方式，让调用第三方服务的客户端代码和调用 servicecomb 微服务的
+客户端代码风格完全一样，并且拥有所有 servicecomb 的客户端治理能力。
+
+在[调用第三方服务](../build-consumer/3rd-party-service-invoke.md)里面介绍了servicecomb提供的一种
+调用第三方服务的使用方式，这种方式依赖于使用服务中心作为注册发现。 下面介绍一种组合使用服务中心和本地注册发现，
+实现调用第三方服务。
+
+* 首先在项目中引入两种注册发现的实现
+
+```xml
+ <dependency>
+ <groupId>org.apache.servicecomb</groupId>
+ <artifactId>registry-local</artifactId>
+ </dependency>
+ <dependency>
+ <groupId>org.apache.servicecomb</groupId>
+ <artifactId>registry-service-center</artifactId>
+ </dependency>
+```
+
+* 在 `registry.yaml` 中定义第三方的微服务信息
+
+```yaml
+thirdParty-service-center:
+ - id: "001"
+ version: "4.0.0"
+ appid: demo-multi-registries
+ schemaIds:
+ - ServiceCenterEndpoint
+ instances:
+ - endpoints:
+ - rest://localhost:30100
+```
+
+* 在 `microservices/thirdParty-service-center/ServiceCenterEndpoint.yaml` 中定义契约内容
+
+```yaml
+swagger: "2.0"
+info:
+ version: "1.0.0"
+ title: "swagger definition for org.apache.servicecomb.demo.registry.ServiceCenterEndpoint"
+ x-java-interface: "gen.swagger.ServiceCenterEndpointIntf"
+basePath: "/v4/default/registry"
+schemes:
+ - "http"
+consumes:
+ - "application/json"
+produces:
+ - "application/json"
+paths:
+ /instances:
+ get:
+ operationId: "getInstances"
+ parameters:
+ - name: "appId"
+ in: "query"
+ required: true
+ type: "string"
+ - name: "serviceName"
+ in: "query"
+ required: true
+ type: "string"
+ - name: "global"
+ in: "query"
+ required: true
+ type: "string"
+ - name: "version"
+ in: "query"
+ required: true
+ type: "string"
+ - name: "x-domain-name"
+ in: "header"
+ required: true
+ type: "string"
+ responses:
+ "200":
+ description: "response of 200"
+ schema:
+ type: "object"
+```
+
+* 经过上面的准备，就可以像访问 servicecomb 的微服务一样访问第三方服务了。 比如采用 RPC 的方式访问这个
+ 服务的代码如下：
+
+```java
+public interface IServiceCenterEndpoint {
+ // java name can not be `x-domain-name`, so interfaces define all parameters.
+ @GetMapping(path = "/instances")
+ Object getInstances(@RequestParam(name = "appId") String appId,
+ @RequestParam(name = "serviceName") String serviceName,
+ @RequestParam(name = "global") String global,
+ @RequestParam(name = "version") String version,
+ @RequestHeader(name = "x-domain-name") String domain);
+}
+
+@Component
+public class ServiceCenterTestCase implements CategorizedTestCase {
+ @RpcReference(microserviceName = "thirdParty-service-center", schemaId = "ServiceCenterEndpoint")
+ IServiceCenterEndpoint serviceCenterEndpoint;
+
+ @Override
+ public void testRestTransport() throws Exception {
+ // invoke service-center(3rd-parties)
+ @SuppressWarnings("unchecked")
+ Map<String, List<?>> result = (Map<String, List<?>>) serviceCenterEndpoint.getInstances(
+ "demo-multi-registries",
+ "demo-multi-registries-server",
+ "true",
+ "0.0.2",
+ "default");
+ TestMgr.check(result.get("instances").size(), 1);
+ }
+}
+```
diff --git a/java-chassis-reference/zh_CN/docs/toc.md b/java-chassis-reference/zh_CN/docs/toc.md
index a893662..ed58746 100644
--- a/java-chassis-reference/zh_CN/docs/toc.md
+++ b/java-chassis-reference/zh_CN/docs/toc.md
@@ -70,6 +70,7 @@
* [HTTP2](transports/http2.md)
* 管理注册发现:
* [注册发现说明](registry/introduction.md)
+ * [组合使用多个实现](registry/multi-registries.md)
* 管理服务配置:
* [通用配置说明](config/general-config.md)
* [配置注入机制](config/inject-config.md)
diff --git a/java-chassis-reference/zh_CN/mkdocs.yml b/java-chassis-reference/zh_CN/mkdocs.yml
index ad80a15..88c106c 100644
--- a/java-chassis-reference/zh_CN/mkdocs.yml
+++ b/java-chassis-reference/zh_CN/mkdocs.yml
@@ -17,6 +17,7 @@ nav:
- HTTP2: transports/http2.md
- 管理注册发现:
- 注册发现说明: registry/introduction.md
+ - 组合使用多个实现: registry/multi-registries.md
- 管理服务配置:
- 通用配置说明: config/general-config.md
- 配置注入机制: config/inject-config.md