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 5f4cd22 update build consumers (#324)
5f4cd22 is described below
commit 5f4cd2287368b01f0d61ce201cb5e4cc6f759c4e
Author: liubao68 <[email protected]>
AuthorDate: Wed Feb 21 15:46:46 2024 +0800
update build consumers (#324)
---
.../zh_CN/docs/build-consumer/basics.md | 96 ++++++++++++++++++++++
.../docs/build-consumer/common-configuration.md | 33 --------
.../features => build-consumer}/invoker.md | 5 +-
.../docs/build-consumer/using-resttemplate.md | 67 +++------------
.../zh_CN/docs/build-consumer/with-contract.md | 52 ------------
.../zh_CN/docs/featured-topics/features.md | 1 -
java-chassis-reference/zh_CN/mkdocs.yml | 17 ++--
7 files changed, 118 insertions(+), 153 deletions(-)
diff --git a/java-chassis-reference/zh_CN/docs/build-consumer/basics.md
b/java-chassis-reference/zh_CN/docs/build-consumer/basics.md
new file mode 100644
index 0000000..6b7e61e
--- /dev/null
+++ b/java-chassis-reference/zh_CN/docs/build-consumer/basics.md
@@ -0,0 +1,96 @@
+# 基础概念
+
+Java Chassis 是以 OpenAPI 为基础的微服务开发框架。一个微服务提供的功能，可以通过 OpenAPI 进行描述。
微服务消费者和提供者完全解耦，开发消费者无需知道提供者的开发方式，只需要知道提供者的OpenAPI信息。
+
+本章节介绍基于[开发服务提供者-基础概念](../build-provider/basics.md)提供的 `HelloWorld` 契约,
描述如何开发服务消费者。
+
+```yaml
+openapi: 3.0.1
+info:
+ version: 1.0.0
+servers:
+- url: /
+paths:
+ /helloWorld:
+ post:
+ operationId: helloWorld
+ requestBody:
+ content:
+ application/json:
+ schema:
+ type: string
+ application/protobuf:
+ schema:
+ type: string
+ text/plain:
+ schema:
+ type: string
+ x-name: name
+ responses:
+ "200":
+ description: response of 200
+ content:
+ application/json:
+ schema:
+ type: string
+ application/protobuf:
+ schema:
+ type: string
+ text/plain:
+ schema:
+ type: string
+components: {}
+```
+
+## Restful风格 - 使用 RestOperations
+
+```java
+RestOperations restOperation =
+ RestTemplateBuilder.create();
+String result = restOperation
+ .postForObject("servicecomb://provider-service/helloWorld",
+ "World", String.class);
+Assertions.assertTrue("Hello World", result);
+```
+
+使用Restful风格开发消费者，需要关注Open
API的Path、参数位置（Body、Header等）、参数类型以及响应类型，并且使用RestOperations的相关接口和参数一一对应。 其中
`servicecomb://provider-service` 表示目标微服务，使用目标微服务的服务名称。
+
+## RPC风格
+
+RPC风格是一种语言有关的开发方法，更加贴近语言的使用习惯。访问服务提供者的服务，就像调用本地的API一样。
+
+使用RPC风格，首先需要声明一个 `interface` 与提供者的服务对应。
+
+```java
+interface HelloWorldService {
+ String helloWorld(String name);
+}
+```
+
+声明 `interface` 会使用到 Open API 的 `operationId`、 参数名称和参数类型、响应类型。
只需要保证方法名等于`operationId`， 参数名称等于Open API里面的参数名称（对于body，使用扩展属性x-name）。
+
+使用起来就非常简单了：
+
+```java
+@RpcReference(schemaId = "HelloWorld",
+ microserviceName = "provider-service")
+private HelloWorldService helloWorldService;
+
+String result = helloWorldService.helloWorld("World");
+Assertions.assertTrue("Hello World", result);
+```
+
+>>>
在具体的开发实践中，开发Provider定义interface（API），然后Consumer依赖Provider发布的包，直接使用Provider的接口也是非常常见的。如果已经习惯这种使用方式，可以继续使用。
在讨论完全解耦和API依赖的好处的时候，存在非常复杂和细节的差异。完全解耦的形式，可以给独立开发带来很大的灵活性，能够提高并行开发的效率。
+
+## 泛化调用 - InvokerUtils
+
+```java
+Map<String, Object> args = new HashMap<>();
+args.put("name", "World");
+String result = InvokerUtils.syncInvoke("provider-service",
+ "HelloWorld", "helloWorld", args, String.class));
+Assertions.assertTrue("Hello World", result);
+```
+
+泛化调用使用服务名、契约名称、`operationId`、 参数直接请求服务提供者，对应到 Open API
的`operationId`、参数名称和参数类型、响应类型。
+
diff --git
a/java-chassis-reference/zh_CN/docs/build-consumer/common-configuration.md
b/java-chassis-reference/zh_CN/docs/build-consumer/common-configuration.md
deleted file mode 100644
index b177171..0000000
--- a/java-chassis-reference/zh_CN/docs/build-consumer/common-configuration.md
+++ /dev/null
@@ -1,33 +0,0 @@
-# Consumer的通用配置项
-
-* 请求超时
- * 配置项
- servicecomb.request.timeout
- * 默认值
- 30000，单位为毫秒
- * 含义
- Consumer传输层开始发送时，开始计时，指定时间内未收到应答，则处理为请求超时
-* 指定传输通道
- * 配置项
- servicecomb.references.${目标微服务名}.transport
- servicecomb.references.transport
- 同时支持全局和微服务级的两级控制
- * 默认值
- 无
- * 含义
-
如果目标微服务同时开放多种transport的访问能力时，而Consumer也同时部署了相应的多个transport，但是作为Consumer调用该微服务时，只想使用其中一种transport，则可以通过本配置项指定transport
- 如果不配置，则轮流使用多个transport
-* 指定目标实例的版本规则
- * 配置项
- servicecomb.references.${目标服务名}.version-rule
- servicecomb.references.version-rule
- 同时支持全局和微服务级的两级控制
- * 默认值
- latest
- * 含义
- 目标实例的版本规则，支持以下规则：
- * 最新版本： latest
- * 大于指定版本，比如：1.0.0+
- * 指定版本范围，比如：1.0.0-2.0.0，表示大于等于版本1.0.0，并且小于版本2.0.0
- * 精确版本，比如：1.0.0
-
diff --git
a/java-chassis-reference/zh_CN/docs/featured-topics/features/invoker.md
b/java-chassis-reference/zh_CN/docs/build-consumer/invoker.md
similarity index 91%
rename from
java-chassis-reference/zh_CN/docs/featured-topics/features/invoker.md
rename to java-chassis-reference/zh_CN/docs/build-consumer/invoker.md
index f19eae2..7812204 100644
--- a/java-chassis-reference/zh_CN/docs/featured-topics/features/invoker.md
+++ b/java-chassis-reference/zh_CN/docs/build-consumer/invoker.md
@@ -1,7 +1,6 @@
-# 特性介绍： 泛化调用
+# 泛化调用
-泛化调用指在不知道 Provider 接口定义信息的情况下，访问 Provider 提供的服务。 与泛化调用对应的方式包括透明 RPC（POJO）和
-RestTemplate。 透明 RPC 需要提供 Provider 对应的接口， RestTemplate 需要提供 Provider 对应的 URL 和
数据 Model 。 泛化
+泛化调用指在不知道 Provider 接口定义信息的情况下，访问 Provider 提供的服务。 泛化
调用需要提供 Provider 的服务元数据： 微服务名称， 版本， Schema ID， Operation ID, 契约参数等信息。
## 使用泛化调用
diff --git
a/java-chassis-reference/zh_CN/docs/build-consumer/using-resttemplate.md
b/java-chassis-reference/zh_CN/docs/build-consumer/using-resttemplate.md
index cd54bca..54b3f04 100644
--- a/java-chassis-reference/zh_CN/docs/build-consumer/using-resttemplate.md
+++ b/java-chassis-reference/zh_CN/docs/build-consumer/using-resttemplate.md
@@ -1,67 +1,51 @@
-# 使用RestTemplate开发服务消费者
+# Restful风格 - 使用 RestOperations
## 概念阐述
-RestTemplate是Spring提供的RESTful访问接口，ServiceComb提供该接口的实现类用于服务的调用。
+RestOperations是Spring提供的RESTful访问接口，ServiceComb提供该接口的实现类用于服务的调用。
## 场景描述
-用户使用ServiceComb提供的RestTemplate实例，可以使用自定义的URL进行服务调用，而不用关心服务的具体地址。
+用户使用ServiceComb提供的RestOperations实例，可以使用自定义的URL进行服务调用，而不用关心服务的具体地址。
## 示例代码
-RestTemplate实例通过调用`RestTemplateBuilder.create()`方法获取，再使用该实例通过自定义的URL进行服务调用，代码如下：
+RestOperations实例通过调用`RestTemplateBuilder.create()`方法获取，再使用该实例通过自定义的URL进行服务调用，代码如下：
* Spring MVC 客户端示例代码：
```java
-@Component
-public class SpringmvcConsumerMain {
- private static RestTemplate restTemplate = RestTemplateBuilder.create();
+public class SpringmvcConsumerExample {
+ private static RestOperations restTemplate = RestTemplateBuilder.create();
- public static void main(String[] args) throws Exception {
- init();
+ public static void test() throws Exception {
Person person = new Person();
person.setName("ServiceComb/Java Chassis");
String sayHiResult = restTemplate
- .postForObject("cse://springmvc/springmvchello/sayhi?name=Java
Chassis", null, String.class);
+
.postForObject("servicecomb://springmvc/springmvchello/sayhi?name=Java
Chassis", null, String.class);
String sayHelloResult = restTemplate
- .postForObject("cse://springmvc/springmvchello/sayhello",
person, String.class);
+
.postForObject("servicecomb://springmvc/springmvchello/sayhello", person,
String.class);
System.out.println("RestTemplate consumer sayhi services: " +
sayHiResult);
System.out.println("RestTemplate consumer sayhello services: " +
sayHelloResult);
}
-
- public static void init() throws Exception {
- Log4jUtils.init();
- BeanUtils.init();
- }
}
```
* JAX RS 客户端示例代码：
```java
-
-@Component
public class JaxrsConsumerMain {
-
- public static void main(String[] args) throws Exception {
- init();
+ public static void test() throws Exception {
//其他都类似spring MVC示例的客户端代码，注意如果服务端只接收 GET 请求，要使用方法 getForObject()
RestTemplate restTemplate = RestTemplateBuilder.create();
- String result =
restTemplate.getForObject("cse://jaxrs/jaxrshello/saybye", String.class);
- }
-
- public static void init() throws Exception {
- Log4jUtils.init();
- BeanUtils.init();
+ String result =
restTemplate.getForObject("servicecomb://jaxrs/jaxrshello/saybye",
String.class);
}
}
```
> 说明：
>
-> *
URL格式为：`cse://microserviceName/path?querystring`。以[用SpringMVC开发微服务](../build-provider/springmvc.md)中定义的服务提供者为例，其微服务名称是`springmvc`，basePath是`/springmvchello`，那么URL中的microserviceName=`springmvc`，请求sayhi时的path=`springmvchello/sayhi`，所以示例代码中请求sayhi的URL是`cse://springmvc/springmvchello/sayhi?name=Java
Chassis`。具体代码示例如下 ：
+> *
URL格式为：`servicecomb://microserviceName/path?querystring`。以[用SpringMVC开发微服务](../build-provider/springmvc.md)中定义的服务提供者为例，其微服务名称是`springmvc`，basePath是`/springmvchello`，那么URL中的microserviceName=`springmvc`，请求sayhi时的path=`springmvchello/sayhi`，所以示例代码中请求sayhi的URL是`servicecomb://springmvc/springmvchello/sayhi?name=Java
Chassis`。具体代码示例如下 ：
```java
@@ -82,30 +66,3 @@ public class SpringmvcHelloImpl implements Hello {
}
}
```
-> 下述代码是示例项目 [ SpringMVC
](https://github.com/apache/servicecomb-samples/tree/master/java-chassis-samples/springmvc-sample)的
springmvc-provider 模块 中 resources 目录下 microservice.yaml
-
-```yaml
-servicecomb:
- service:
- application: springmvc-sample
- name: springmvc
- version: 0.0.1
-
- registry:
- # Default using local service center
- address: http://localhost:30100
- # address: https://cse.cn-south-1.myhuaweicloud.com
- instance:
- watch: false
- kie:
- serverUri: http://localhost:30110
-
- rest:
- address: 0.0.0.0:8080
-
-```
-
-
-
-
-> * 使用上述这种URL格式，ServiceComb框架会在内部进行服务发现、熔断容错等处理并最终将请求发送到服务提供者。
diff --git a/java-chassis-reference/zh_CN/docs/build-consumer/with-contract.md
b/java-chassis-reference/zh_CN/docs/build-consumer/with-contract.md
deleted file mode 100644
index a0069db..0000000
--- a/java-chassis-reference/zh_CN/docs/build-consumer/with-contract.md
+++ /dev/null
@@ -1,52 +0,0 @@
-# 使用服务契约
-
-## 场景描述
-
-当服务消费者调用服务提供者的服务时，需要获取服务契约。消费者有两种方式获取提供者的服务契约，一种是从服务的提供方离线获取契约文件，手工配置到项目中；另一种是从服务中心自动下载契约。
-
-## 配置说明
-
-> 说明：服务契约的获取方式与服务消费者的开发方式是无关的，用户可以任意组合使用。
-
-### 配置依赖服务
-
-服务消费者需要在microservice.yaml文件中配置依赖的provider，示例配置如下：
-
-```yaml
-servicecomb:
- # other configurations omitted
- references:
- springmvc:
- version-rule: 0.0.1
-```
-
-> version-rule是版本匹配规则，有四种格式：
->
-> * 精确版本匹配：例如`version-rule: 0.0.1`，表示只匹配版本号为0.0.1的服务提供者
-> * 后续版本匹配：例如`version-rule: 1.0.0+`，表示匹配版本号大于或等于1.0.0的服务提供者
-> * 最新版本：`version-rule: latest`，表示匹配最新版本的服务提供者
-> * 版本范围：例如`1.0.0-2.0.2`，表示匹配版本号在1.0.0至2.0.2之间的服务提供者，包含1.0.0和2.0.2
->
-> 此配置项默认为`latest`
-
-### 手工配置服务契约
-
-服务消费者的开发者在线下拿到服务提供者的契约，配置到消费者工程的特定目录下。服务契约在项目中的存放目录与[定义服务契约](../build-provider/define-contract.md)的配置说明部分相同。
-
-microservice目录下的每一个目录代表一个微服务，微服务目录下的每一个yaml文件代表一个schema契约，文件名就是schemaId。applications目录下存放需要指明appId的服务契约，用于跨app调用等场景。目录结构如下所示：
-
-```
-resources
- - microservices
- - serviceName # 微服务名
- - schemaId.yaml # schema接口的契约
- - applications
- - appId # 应用ID
- - serviceName # 微服务名
- - schemaId.yaml # schema接口的契约
-```
-
-### 从服务中心自动下载契约
-
-服务消费者也可以不用显式地将契约存放在项目目录中，当程序启动时，ServiceComb框架会自动根据microservice.yaml文件中配置的服务提供者的微服务名称和版本号，从服务中心自动下载契约信息。
-
diff --git a/java-chassis-reference/zh_CN/docs/featured-topics/features.md
b/java-chassis-reference/zh_CN/docs/featured-topics/features.md
index fbfce09..15a6e0a 100644
--- a/java-chassis-reference/zh_CN/docs/featured-topics/features.md
+++ b/java-chassis-reference/zh_CN/docs/featured-topics/features.md
@@ -1,5 +1,4 @@
# 特性介绍
* [特性介绍： date和date-time](features/date-time.md)
-* [特性介绍： 泛化调用](features/invoker.md)
* [特性介绍： Edge Service 通用的 HTTP 转发器
CommonHttpEdgeDispatcher](features/http-dispatcher.md)
diff --git a/java-chassis-reference/zh_CN/mkdocs.yml
b/java-chassis-reference/zh_CN/mkdocs.yml
index aef7eba..e864400 100644
--- a/java-chassis-reference/zh_CN/mkdocs.yml
+++ b/java-chassis-reference/zh_CN/mkdocs.yml
@@ -35,11 +35,10 @@ nav:
- IPV6配置和使用: build-provider/ipv6-configuration.md
- Access Log配置: build-provider/access-log-configuration.md
- 开发服务消费者:
- - 消费者通用配置项: build-consumer/common-configuration.md
- - 使用RestTemplate开发服务消费者: build-consumer/using-resttemplate.md
- - 使用RPC方式开发服务消费者: build-consumer/develop-consumer-using-rpc.md
- - 泛化调用: featured-topics/features/invoker.md
- - 使用服务契约: build-consumer/with-contract.md
+ - 基础概念: build-consumer/basics.md
+ - Restful风格 - 使用 RestOperations: build-consumer/using-resttemplate.md
+ - RPC风格: build-consumer/develop-consumer-using-rpc.md
+ - 泛化调用: build-consumer/invoker.md
- 调用第三方REST服务: build-consumer/3rd-party-service-invoke.md
- 定制请求处理流程:
- 处理链介绍: references-handlers/intruduction.md
@@ -66,10 +65,10 @@ nav:
- 配置日志: general-development/config-logs.md
- 多样化的通信协议功能:
- 多协议介绍: transports/introduction.md
- - REST over HTTP(Vert.x: transports/rest-over-vertx.md
- - REST over HTTP2(Vert.x: transports/http2.md
- - REST over Servlet(Spring Boot Embedded:
transports/rest-over-servlet-embedded.md
- - REST over Servlet(WAR: transports/rest-over-servlet.md
+ - REST over HTTP(Vert.x): transports/rest-over-vertx.md
+ - REST over HTTP2(Vert.x): transports/http2.md
+ - REST over Servlet(Spring Boot Embedded):
transports/rest-over-servlet-embedded.md
+ - REST over Servlet(WAR): transports/rest-over-servlet.md
- Highway: transports/highway-rpc.md
- 多样化的服务注册与发现功能:
- 注册发现介绍: registry/introduction.md
