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/03/19 07:00:50 UTC
[servicecomb-docs] branch master updated: add new features of 2.0.1
and fix upgrading guides
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 a6fd6a6 add new features of 2.0.1 and fix upgrading guides
a6fd6a6 is described below
commit a6fd6a600f710931d07d7a6fb9e0ec359597a1b4
Author: liubao <bi...@qq.com>
AuthorDate: Thu Mar 19 14:29:43 2020 +0800
add new features of 2.0.1 and fix upgrading guides
---
.../zh_CN/docs/featured-topics/features.md | 3 +-
.../docs/featured-topics/features/trace-id.md | 130 +++++++++++++++++++++
.../zh_CN/docs/featured-topics/upgrading.md | 3 +-
.../docs/featured-topics/upgrading/1_3_0T2_0_0.md | 68 ++++++++---
.../docs/featured-topics/upgrading/2_0_0T2_0_1.md | 13 +++
5 files changed, 196 insertions(+), 21 deletions(-)
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 1fcac19..ec5c0f6 100644
--- a/java-chassis-reference/zh_CN/docs/featured-topics/features.md
+++ b/java-chassis-reference/zh_CN/docs/featured-topics/features.md
@@ -2,4 +2,5 @@
* [2.0.0 新特性介绍： 弱类型契约](features/weak-type-contrast.md)
* [2.0.0 新特性介绍： 多配置中心支持](features/configuration-sources.md)
-* [2.0.1 新特性介绍： date和date-time](features/date-time.md)
\ No newline at end of file
+* [2.0.1 新特性介绍： date和date-time](features/date-time.md)
+* [2.0.1 新特性介绍： 在日志中记录trace id](features/trace-id.md)
\ No newline at end of file
diff --git a/java-chassis-reference/zh_CN/docs/featured-topics/features/trace-id.md b/java-chassis-reference/zh_CN/docs/featured-topics/features/trace-id.md
new file mode 100644
index 0000000..feff69e
--- /dev/null
+++ b/java-chassis-reference/zh_CN/docs/featured-topics/features/trace-id.md
@@ -0,0 +1,130 @@
+# 2.0.1 新特性介绍： 在日志中记录trace id
+
+微服务架构下，需要部署大量的微服务实例，调用情况复杂，给问题定位带来了很大的麻烦。 通过调用链系统能够很好的解决日志追踪的问题，
+但是对于日常的开发调试，部署调用链仍然显得复杂。 java-chassis 提供了一种简单的机制，允许业务在记录日志的时候，包含trace id。
+
+## 在日志系统中记录 trace id
+
+java-chassis 使用 MDC 的方式记录 trace id， 可以在 log4j2 或者 logback 中打印 trace id。 java-chassis 记录 trace id 增加
+了 Marker ， 开发者可以方便的将这类日志进行分类输出。
+
+log4j2的配置如下：
+
+```xml
+ <Appenders>
+ <Console name="Console" target="SYSTEM_OUT">
+ <PatternLayout pattern="[%d][%t][%p][%c:%L][%X{SERVICECOMB_TRACE_ID}] %m%n"/>
+ </Console>
+ </Appenders>
+```
+
+结合 Marker， 将日志分类显示：
+
+```xml
+ <Appenders>
+ <Console name="Console" target="SYSTEM_OUT">
+ <MarkerFilter marker="SERVICECOMB_MARKER" onMatch="DENY" onMismatch="ACCEPT"/>
+ <PatternLayout pattern="[%d][%t][%p][%c:%L] %m%n"/>
+ </Console>
+ <Console name="Console-Tracing" target="SYSTEM_OUT">
+ <MarkerFilter marker="SERVICECOMB_MARKER" onMismatch="DENY" onMatch="ACCEPT"/>
+ <PatternLayout pattern="[%d][%t][%p][%c:%L][%X{SERVICECOMB_TRACE_ID}] %m%n"/>
+ </Console>
+ </Appenders>
+```
+
+logback的配置如下:
+
+```xml
+ <appender name="STDOUT" class="ch.qos.logback.core.ConsoleAppender">
+ <encoder>
+ <pattern>%d [%level] [%thread][%X{SERVICECOMB_TRACE_ID}] - %msg (%F:%L\)%n</pattern>
+ </encoder>
+ </appender>
+```
+
+结合 Marker， 可以将日志分类显示:
+
+```xml
+ <appender name="STDOUT-TRACING" class="ch.qos.logback.core.ConsoleAppender">
+ <!-- If applicable, can use ch.qos.logback.classic.filter.MarkerFilter -->
+ <filter class="org.apache.servicecomb.foundation.logback.MarkerFilter">
+ <Marker>SERVICECOMB_MARKER</Marker>
+ <OnMismatch>DENY</OnMismatch>
+ <OnMatch>ACCEPT</OnMatch>
+ </filter>
+
+ <encoder>
+ <pattern>%d [%level] [%thread][%X{SERVICECOMB_TRACE_ID}] - %msg (%F:%L\)%n</pattern>
+ </encoder>
+ </appender>
+```
+
+## 业务日志包含 trace id
+
+* 记录 access log
+
+java-chassis 只有少量的日志包含 trace id，业务可以方便的在自己记录的日志中包含 trace id。 下面开发一个简单的 Handler， 记录服务端的
+access log。
+
+```java
+public class AccessLogHandler implements Handler {
+ private static final Logger LOGGER
+ = LoggerFactory.getLogger(AccessLogHandler.class);
+
+ @Override
+ public void handle(Invocation invocation, AsyncResponse asyncResp) throws Exception {
+ invocation.getTraceIdLogger().info(LOGGER, "request for operation {} begin", invocation.getInvocationQualifiedName());
+ invocation.next((resp) -> {
+ invocation.getTraceIdLogger().info(LOGGER, "request for operation {} end", invocation.getInvocationQualifiedName());
+ asyncResp.complete(resp);
+ });
+ }
+}
+```
+
+配置 Handler
+
+```xml
+<config>
+ <handler id="custom-access-log"
+ class="org.apache.servicecomb.demo.prefix.AccessLogHandler"/>
+</config>
+
+```
+
+启用 Handler
+
+```yaml
+servicecomb:
+ handler:
+ chain:
+ Provider:
+ default: custom-access-log
+```
+
+* 业务日志
+
+可以在业务实现中记录 trace id
+
+```java
+public class RegisterUrlPrefixEndpoint {
+ private static final Logger LOGGER
+ = LoggerFactory.getLogger(RegisterUrlPrefixEndpoint.class);
+
+ @GetMapping(path = "/getName")
+ public String getName(@RequestParam(name = "name") String name) {
+ ((Invocation) ContextUtils.getInvocationContext()).getTraceIdLogger().info(LOGGER, "get name invoked.");
+ return name;
+ }
+}
+```
+
+增加了 access log 和业务日志后的效果如下：
+
+```text
+[5e72e39e55209533-1] - request for operation PRODUCER rest demo-register-url-prefix-server.RegisterUrlPrefixEndpoint.getName begin
+[5e72e39e55209533-1] - get name invoked.
+[5e72e39e55209533-1] - request for operation PRODUCER rest demo-register-url-prefix-server.RegisterUrlPrefixEndpoint.getName end
+```
+
diff --git a/java-chassis-reference/zh_CN/docs/featured-topics/upgrading.md b/java-chassis-reference/zh_CN/docs/featured-topics/upgrading.md
index fbf7b2d..6dd4304 100644
--- a/java-chassis-reference/zh_CN/docs/featured-topics/upgrading.md
+++ b/java-chassis-reference/zh_CN/docs/featured-topics/upgrading.md
@@ -1,3 +1,4 @@
# 升级指导系列文章
-* [1.3.0 升级 2.0.0指导](upgrading/1_3_0T2_0_0.md)
\ No newline at end of file
+* [1.3.0 升级 2.0.0指导](upgrading/1_3_0T2_0_0.md)
+* [2.0.0 升级 2.0.1指导](upgrading/2_0_0T2_0_1.md)
\ No newline at end of file
diff --git a/java-chassis-reference/zh_CN/docs/featured-topics/upgrading/1_3_0T2_0_0.md b/java-chassis-reference/zh_CN/docs/featured-topics/upgrading/1_3_0T2_0_0.md
index 9dce8f9..eaa3f97 100644
--- a/java-chassis-reference/zh_CN/docs/featured-topics/upgrading/1_3_0T2_0_0.md
+++ b/java-chassis-reference/zh_CN/docs/featured-topics/upgrading/1_3_0T2_0_0.md
@@ -40,24 +40,36 @@ Highway通信协议是2.0.0最大的变更点。如果业务采用了Highway通
8. 如果一个属性的名称采用一个小写字母开头，并且只有一个小写字母，即使生成的getter/setter是合法
的， swagger 生成的属性名称还是会出现错误。应该尽可能避免使用这样的属性名称。必须使用的场景，需要
显示的使用 @JsonProperty 声明。
+
+ ```java
+ public class SpecialNameModel {
+ // names starts with only one lower case , although getter/setter generated by IDE is correct,
+ // will cause jackson generate incorrect swagger names.
+ // @JsonProperty must be used to make json work in a predictable way.
+ @JsonProperty("aIntName")
+ private int aIntName;
+
+ public int getaIntName() {
+ return aIntName;
+ }
+
+ public void setaIntName(int aIntName) {
+ this.aIntName = aIntName;
+ }
+ }
+ ```
+
+ 9. 返回多种类型或者通过 ContextUtils 设置状态码 HIGHWAY 不再支持。 尽管 1.3.0 之前用户也不会在 HIGHWAY 模式下
+ 使用类似下面的代码， 但是在 1.3.0 之前的版本， 这些代码部分确实能够工作。
+
+ ```java
+ @PUT
+ public String sayHi(@PathParam("name") String name) {
+ ContextUtils.getInvocationContext().setStatus(202);
+ return name + " sayhi";
+ }
+ ```
-```
-public class SpecialNameModel {
- // names starts with only one lower case , although getter/setter generated by IDE is correct,
- // will cause jackson generate incorrect swagger names.
- // @JsonProperty must be used to make json work in a predictable way.
- @JsonProperty("aIntName")
- private int aIntName;
-
- public int getaIntName() {
- return aIntName;
- }
-
- public void setaIntName(int aIntName) {
- this.aIntName = aIntName;
- }
-}
-```
***优秀实践***:
@@ -113,13 +125,24 @@ List<GenericObjectParam<List<RecursiveObjectParam>>> response = consumers.getSCB
```
HttpEntity<SpringmvcBasicRequestModel> requestEntity = new HttpEntity<>(requestModel, null);
List<SpringmvcBasicResponseModel> responseModelList =
- consumers.getSCBRestTemplate().exchange("/postListObject", HttpMethod.POST, requestEntity,
+ template.exchange("/postListObject", HttpMethod.POST, requestEntity,
new ParameterizedTypeReference<List<SpringmvcBasicResponseModel>>() {
}).getBody();
```
这种方式的语义根据清晰，在使用泛型的时候，建议采用这种用法。
+在1.3.0版本支持如下用法：
+
+```java
+template.postForEntity(url,
+ "{\"time\":3073113710456,\"date\":3073113710456,\"holder\":\"test\"}",
+ DateTimeModel.class)
+```
+
+即通过 JSON String 的方式传递参数给后台的 DateTimeModel 对象。 由于这种用法在解析的时候存在二义性， 2.0.0
+不再支持这种用法。 可以使用 Map 或者 JsonObject 来传递。
+
## AsyncRestTemplate的使用
1.3.0 和 2.0.0 中 AsyncRestTemplate 的使用方式一样，没有变化。但是由于 2.0.0 只支持spring 5版
@@ -271,7 +294,8 @@ Caused by: java.lang.NullPointerException
* io.vertx.ext.web中的 `io.vertx.ext.web.Cookie已过时` ， 修改
为 `io.vertx.core.http.Cookie`
-2.0.0 一些可能被外部使用的内部接口调整
+2.0.0 一些可能被外部使用的内部接口调整：
+
* `Invocation` 类删除了 `getArgs` 接口， 替换为 `getSwaggerArguments` ， 同时新增了 `getInvocationArguments`，
关于这个变更的说明，请参考新特性介绍文章[弱类型契约](../features/weak-type-contrast.md)。
* 删除 `DynamicSchemaLoader` ， 这个类早期版本提供出来是方便注册契约， 最新版本客户端契约发现可以通过服务中心
@@ -281,4 +305,10 @@ Caused by: java.lang.NullPointerException
* 测试代码可能使用 `CseContext.getInstance().getConsumerProviderManager().setTransport(microserviceName, transport)` ， 修改
为 `ArchaiusUtils.setProperty("servicecomb.references.transport." + microserviceName, transport);`
+## 已知缺陷
+ * 2.0.0 版本将 `servicecomb.service.registry.registerUrlPrefix` 弄丢了。 这个配置项是为一个特殊场景服务的的，
+ 默认值为 false。 在使用 WEB 容器（比如 tomcat） java-chassis的场景下， 如果设置了 context-path， 使用 java-chassis
+ 提供的 RestTemplate 访问服务的时候， 不需要指定 context-path，以保证用户不用关注微服务的部署方式，提供了很大的便利。
+ 但是有些用户的代码是历史遗留代码改造过来的，期望 URL 包含完整的 context-path。 使用 2.0.0 版本如果存在这个特殊要
+ 求， 程序会运行错误，访问接口提示 NOT FOUND。这个问题在 2.0.1 修复。
diff --git a/java-chassis-reference/zh_CN/docs/featured-topics/upgrading/2_0_0T2_0_1.md b/java-chassis-reference/zh_CN/docs/featured-topics/upgrading/2_0_0T2_0_1.md
new file mode 100644
index 0000000..49689e7
--- /dev/null
+++ b/java-chassis-reference/zh_CN/docs/featured-topics/upgrading/2_0_0T2_0_1.md
@@ -0,0 +1,13 @@
+# 2.0.0 升级 2.0.1指导
+
+## trace id 记录的变更说明
+
+2.0.0 采用 %marker 记录 trace id， 由于 Marker 被设计为 Filtering 场景， 不适用于记录 trace id， 否则可能导致有些 logger 系统
+产生 OOM。 2.0.1 将 Marker 调整为了 MDC 。 使用指导参考 [2.0.1 新特性介绍： 在日志中记录trace id](../features/trace-id.md)
+
+## 独立 tomcat (或者其他 web container ) 运行的场景
+
+在使用独立 tomcat 运行的场景， RestServletContextListener 在会在 contextInitialized 环节调用 Log4jUtils.init 初始化 log4j ,
+由于 log4j 目前已经被 log4j2 或者 logback 等替换， 从 2.0.1 开始， 不会调用 Log4jUtils 初始化 log4j 。 如果应用系统需要继续
+使用 log4j， 可以自定义 ServletContextListener ，调用 Log4jUtils.init 初始化 log4j。
+