Skip to content

2.8.x 升级 3.0.0 指导

3.0.0版本的重要更新：

  • 最小支持 JDK 17
  • 采用Spring Boot 3作为开发底座，底层实现依赖Spring Boot 3，不再提供Spring启动方式。
  • 支持 OpenAPI 3.0 规范

本文档提供2.8.x升级到3.0.0的指导。

说明：由于Spring Boot 3不再兼容 javax.servlet， javax.ws 等组件，并且 swagger 1.x 没有提供 jakarta.servlet支持，3.0.0 版本使用 swagger 2.x 支持 Open API 3.0。 因此，3.0.0 版本不能保证与 2.x.x 版本之间的正常通信。 在升级 3.0.0 的时候，需要注意对现有服务进行全量升级，不支持独立升级客户端或者服务端微服务。

依赖配置和启动类

Java Chassis原生Transport

Java Chassis原生提供了 Rest Over Vert.x, Highway等原生Transport。Edge Service也使用原生Transport运行。

TODO

Spring Boot Servlet Transport

Java Chassis支持运行与Servlet容器，自身作为一个Servlet启动。

TODO

独立WEB容器 Servlet Transport

Java Chassis支持运行与Servlet容器，自身作为一个Servlet启动。

TODO

SPI 修改为 Bean

BootListener

MetricsInitializer

DiscoveryFilter

配置项不再支持 cse 前缀

Java Chassis 的所有配置项全部使用 servicecomb 作为前缀，比如：

servicecomb:
  service:
    application: my-application
    name: my-service

早期版本，也支持下面的配置：

cse:
  service:
    application: my-application
    name: my-service

3.0.0 版本不再提供 cse 前缀支持，需要将 cse 前缀修改为 servicecomb。

版本管理

3.0.0 简化了注册发现的依赖和实现，以支持更多的注册中心实现。 3.0.0 不再支持版本的管理。具体表现为几个常用的场景：

  • 客户端指定 version-rule，指明只调用服务端的某些版本；
  • 客户端根据每个版本的 Open API 定义，能够区分某个 operation 是否存在于一个实例，避免将请求发送到不存在该 operation 的实例。
  • Edge Service不再支持版本配置。 即只能配置 /microservice/path， 不能配置 /microservice/version-rule/path。 类似的场景可以采用灰度发布来解决。

契约加载流程变化

  • 作为提供者的契约加载

    3.0.0版本提供者不再加载本地契约，而是根据代码生成契约，并将生成的契约注册到注册中心。做这个变化的目的，主要是因为手写契约和代码本身生成契约不一致的情况，会导致代码语义阅读困难，带来很多隐藏不易发现的错误。而语义一致的情况，这种使用方式没有实际意义，使用代码生成契约得到一样的结果。

  • 作为消费者的契约加载

    3.0.0版本消费者契约加载流程不变。优先加载本地契约。

1.x 兼容性删除

参数位置匹配

1.x 和 2.x 版本， Java代码生成契约后，契约的参数个数和顺序可以保持Java代码的Method一致。Java Chassis 2.x 基于契约，默认根据参数名称从契约中查找是否存在该参数。 但是1.x版本，不是基于名称查找的，而是基于参数位置查找的。 所以在部分参数名称不匹配的情况下，2.x做了一些兼容性处理，利用了Open API 2.0可以保证（最大限度，非确定性算法）顺序的机制，可以通过位置匹配到参数。Open API 3.0.0的参数基于名称，并且不在保证和Java的Method参数位置一致，因此3.0.0版本不在支持这个参数位置匹配的查找场景。 在定义参数的时候，需要保证Java的Method参数名称（或者通过annotation声明的参数名称）与契约的名称一致。（Parameter使用name属性；RequestBody使用扩展属性x-name，如果是form格式，则使用Property的key作为名称。）

REST 和 Open API常见不兼容问题

collectionFormat

collectionFormat 在 2.0 用来表示 Query 参数的形式。 在 3.0 后， 不再支持 tsv 和 jason 格式。 而是指定 style 和 explode。 详细参考： https://swagger.io/docs/specification/serialization/

SpringMVC　变更项

@RequestAttribute 和 @RequestParam 标签

在 servicecomb 的开发指南里面， @RequestAttribute 标签描述为不支持。 但是实际用户使用并不会报错，而且将这个映射为HTTP的form参数。 3.0.0 采用 @RequestAttribute 表示 form 参数， @RequestParam 表示 query参数。

在使用上需要注意与spring web原生行为的差异。

不在支持 AsyncRestTemplate

Spring 6 删除了 AsyncRestTemplate 支持， Java Chassis 3.0.0 也删除了支持。 相关代码需要使用 CompletableFuture 异步代码替换。

移除 log4j , logback 的封装

Java Chassis 系统内部全部采用 slf4j 记录日志， 不再提供 log4j 的封装功能， 删除了 Log4jUtils 等类。 如果使用了 Log4jUtils 类来初始化日志， 可以参考 配置日志 来设置系统日志。

移除 bizkeeper 处理链

Java Chassis 早期版本基于 Hystrix 提供了基于方法的服务治理能力，由于社区已经停止 Hystrix 维护，并且 bizkeeper 设计上不能很好的满足场景的故障模式保护， 3.0.0 版本删除了这个模块。 服务治理可以使用流量特征治理来实现，过载保护的最佳处理方案是配置客户端隔离仓。

移除实例隔离功能

Java Chassis 3.0.0 不再支持下面的配置项：

servicecomb:
  loadbalance:
    isolation:
      enabled: false
      errorThresholdPercentage: 0
      enableRequestThreshold: 5
      singleTestTime: 60000
      continuousFailureThreshold: 5
      maxSingleTestWindow: 60000 # 为了保证在并发情况下只有一个实例放通，会锁定放通实例。这个时间表示最大锁定时间。
      minIsolationTime: 3000 # 最短隔离时间。并发情况下，实例隔离后进行中的请求可能快速刷新隔离状态，增加最短隔离时间。
      recoverImmediatelyWhenSuccess: true # 放通实例，如果调用成功，立即清除统计状态，保证后续请求能够使用该实例。 2.1.3 新增。

单实例故障防护可以使用流量特征治理来实现，启用客户端熔断和客户端隔离仓。

移除 archaius

Java Chassis 早期版本基于archaius实现动态配置， 由于这个软件已经停止维护， 3.0.0移除了这个依赖，完成集成和使用 Spring Boot配置机制。 意味着业务 使用 DynamicPropertyFactory 等 archaius API读取配置的地方，需要使用 Spring Boot 的 Environment API。 Java Chassis仍然保留了 DynamicProperties 接口， @InjectProperty的配置使用方式， 能够更加方便的使用动态配置。

多种序列化支持

3.0.0版本支持REST风格多种序列化支持，在application/json基础之上，支持text/plain, application/protobuf支持。

提供新的 archetypes 插件

TODO