9A4.升迁3.0.3.300手册

build升级到300，有以下重点不兼容影响。

• java 17 取代 11
• EE更名，以jakarta取代 javax
• boot以3.0取代2.7，Release Notes
• 检查wings notable changelog

9A4.1.修改pom.xml

version变为3.0.3.300-SNAPSHOT

<parent>
    <groupId>pro.fessional</groupId>
    <artifactId>wings</artifactId>
    <version>3.0.3.300-SNAPSHOT</version>
</parent>

9A4.2.依赖变更

git-commit-id-plugin

<plugin>
    <groupId>pl.project13.maven</groupId>
    <artifactId>git-commit-id-plugin</artifactId>
</plugin>
<!-- ↑↑变更前↑↑，↓↓变更后↓↓ -->
<plugin>
    <groupId>io.github.git-commit-id</groupId>
    <artifactId>git-commit-id-maven-plugin</artifactId>
</plugin>

springdoc

<dependency>
    <groupId>org.springdoc</groupId>
    <artifactId>springdoc-openapi-ui</artifactId>
</dependency>
<dependency>
    <groupId>org.springdoc</groupId>
    <artifactId>springdoc-openapi-javadoc</artifactId>
</dependency>
<!-- ↑↑变更前↑↑，↓↓变更后↓↓ -->
<dependency>
    <groupId>org.springdoc</groupId>
    <artifactId>springdoc-openapi-starter-webmvc-ui</artifactId>
</dependency>

// import org.springdoc.api.annotations.ParameterObject;
import org.springdoc.core.annotations.ParameterObject;
// import org.springdoc.core.SpringDocConfiguration;
import org.springdoc.core.configuration.SpringDocConfiguration;
// import org.springdoc.core.SpringDocUtils;
import org.springdoc.core.utils.SpringDocUtils;
// import org.springdoc.core.customizers.OpenApiCustomiser;
import org.springdoc.core.customizers.OpenApiCustomizer;

9A4.3.javax to jakarta namespace

springboot3生态下，已完成了namespace的变更。wings主要涉及以下

jakarta.annotation.PostConstruct;
jakarta.mail.*
jakarta.servlet.*
jakarta.validation.*
jakarta.xml.bind.*

需要注意的，可能并非全部替换，需要区分对待和排除，

• 并非所有的javax名词空间下都需要替换
• 因为间接依赖，可能同时存在javax和jakarta包
• 多数第三方lib，分别提供了javax和jakarta版
• IDEA提供了迁移工具

9A4.4.重做Autogen

参考277.220升级手册。

因已关闭JPA注解，现涉及的javax注解如下

• javax.annotation.processing.Generated (JDK 9+ )
• javax.annotation.Generated (JDK 8- )

9A4.5.add-modules及add-opens

java17中--illegal-access=deny，未add-opens会运行时错误。 wings的starter.sh，pom.xml，进行了正确设定，可以直接使用。

已知IDEA中，执行Whole project测试时，未引用surefire的argLine。 其结果是，部分使用反射个功能的测试用例失败。解决办法如下，

• 以模块为单位执行，会正确设置argLine
• 全工程时，需要自行指定add-opens，内容参考argLine。

9A4.6.java17的语法特征调整

java17提供了比较舒服的语法特征，建议调整

• PatternVariable替换类型强转 instanceof final G g
• 加强版的switch，以箭头表示 case gg -> ;
• text block 替换字符串拼接 """ """

以下特征不建议调整

• record - 出小类外，尽量用lombok，拥有更多特性和扩展性

9A4.7.重要的直接依赖

• mirana 2.4.0-SNAPSHOT → 2.4.4-SNAPSHOT
• springdoc 1.6.14 → 2.0.2
  • org.springdoc:springdoc-openapi-starter-webmvc-ui
• boot-admin 2.7.10 → 3.0.0
• sentry 6.12.1 → 6.13.0
  • sentry-spring-boot-starter-jakarta
• flatten-maven-plugin 1.2.7 → 1.3.0

9A4.8.Wingsboot使用者

本小节适用于以maven的parent形式使用wingsboot的IDEA工程的升级。 建议从2.7.7.220开始升级，否则重新生成jooq代码时，需要临时引入lib。

开始升级之前，必须注意以下事项，并在一个新的git分支上进行

• 一步只进行一个操作，成功后再进行下一步
• 每一步成功时，及时提交工作区，以便轻松fallback
• 首先保证编译正常，然后再进行运行时的测试

可使用spring-boot-migrator做自动升级。

8a.修改parent/version

参考 第一小节，使用3.0.3.300-SNAPSHOT

注意，不要修改非必须的dependency版本号，仅修改wings及spring有关的。 凡是不影响编译的业务lib，都不要变动，避免一次修改太多内容，无法划清边界。

8b.设定工程JDK17

使用Eclipse Temurin™打包的OpenJDK17， 可以通过asdf 直接安装 asdf install java temurin-17.0.9+9

重新导入maven工程，或在IDEA的菜单中设置，

File | Project Structure (⌘;) | Project

• SDK - temurin-17
• Language level - SDK default

8c.升级名词空间jakarta

使用IDEA的重构功能，做jakarta的名词空间迁移，建议先排除jooq自动生成的代码。

Refactor | Migrate Packages and Classes | JavaEE to JakartaEE

若包括jooq代码，javax.annotation.processing.Generated 不要替换。

迁移结束后，编译错误，应该主要集中在Jooq生成的代码上，解决办法参考下一节。

若有其他第三方依赖，如sentry，一般需要使用带-jakarta的artifactId，

<dependency>
  <groupId>io.sentry</groupId>
  <artifactId>sentry-spring-boot-starter</artifactId>
</dependency>
<!-- ↑↑变更前↑↑，↓↓变更后↓↓ -->
<dependency>
  <groupId>io.sentry</groupId>
  <artifactId>sentry-spring-boot-starter-jakarta</artifactId>
</dependency>

8d.重新生成Jooq代码

若不是从2.7.7.220开始的升迁，需要临时引入以下lib，重置jooq代码后移除。

<!-- javax.persistence -->
<dependency>
    <groupId>jakarta.persistence</groupId>
    <artifactId>jakarta.persistence-api</artifactId>
</dependency>
<!-- javax.validation.constraints -->
<dependency>
    <groupId>jakarta.validation</groupId>
    <artifactId>jakarta.validation-api</artifactId>
</dependency>

会存在jakarta.annotation.processing.Generated编译错误， 需要替换回javax.annotation.processing.Generated。

8e.升级其他lib版本

• 升级过程中，不引起编译错误的lib
• 影响编译，但可快速修复或隐藏的

以上lib之外，建议在上述大变更完成后，逐一升级。

8f.官方检查Spring migrator

wings升级后，遵循spring官方的升级手册，并使用自动工具检查。

• Release Notes 检查各项依赖
• 3.0-Migration-Guide 升级事项
• spring-boot-migrator 自动升级工具

因wings的层叠properties无法被spring识别，需要人工设定以下属性，

• logging.pattern.dateformat
• management.endpoints.jmx.exposure.include

8g.NoSuchBeanDefinitionException

org.springframework.beans.factory.NoSuchBeanDefinitionException: No qualifying bean of type '.JiayuincFedexProp' available: expected at least 1 bean which qualifies as autowire candidate.

若是采用spring.factories的AutoConfiguration自动加载Bean，必须变更为以下格式， org.springframework.boot.autoconfigure.AutoConfiguration.imports