plugins {    
    id 'org.springframework.boot' version '3.2.0' apply false
    id 'io.spring.dependency-management' version '1.1.4' apply false
}

Execution failed for task ':batch:compileJava'.
> java.lang.NoClassDefFoundError: javax/persistence/Entity

Sử dụng migration tool của IDEA, chúng ta có thể nhanh chóng convert namespace cũ sang namespace mới.

Chúng tôi đã thực hiện migrate các package của Java Persistence và đạt được kết quả như sau:

- import javax.persistence.Entity;
- import javax.persistence.Id;
- import javax.persistence.Table;
+ import jakarta.persistence.Entity;
+ import jakarta.persistence.Id;
+ import jakarta.persistence.Table;

@ConstructorBinding annotation 

Loại bỏ annotation @ConfigurationBinding: Ở phiên bản Spring Boot 3, những ConfigurationProperties class sẽ không cần được thêm annotation này.

- @ConstructorBinding
@ConfigurationProperties(prefix = "obs.callback")
data class ObsCallbackProperties(
    val authToken: String,
)

MySQL JDBC Driver và Spring Data JPA

Sử dụng dependency com.mysql:mysql-connector-j thay thế cho mysql:mysql-connector-java.

Ngoài việc thay thế tên thư viện, chúng ta không cần cập nhật gì thêm trong codebase.

- dependency "mysql:mysql-connector-java:$mysqlVersion"
+ dependency "com.mysql:mysql-connector-j:$mysqlVersion"

Sử dụng config CamelCaseUnderscoresNamingStrategy thay cho SpringPhysicalNamingStategy do phiên bản mới của Hibernate sẽ không còn hỗ trợ config.

spring:
  jpa:
    hibernate:
-      naming.physical-strategy: org.springframework.boot.orm.jpa.hibernate.SpringPhysicalNamingStrategy
+      naming.physical-strategy: org.hibernate.boot.model.naming.CamelCaseToUnderscoresNamingStrategy

Spring Kafka

Ở phiên bản mới, KafkaTemplate sẽ trả về CompletableFuture thay vì ListenableFuture như trước đây.

Vì vậy, chúng tôi thực hiện migrate từ phương thức addCallback() sang phương thức whenComplete() để xử lý kết quả của KafkaTemplate:

• Phiên bản trước

kafkaTemplate.send(record)
             .addCallback(successCallback(), failureCallback());

• Phiên bản mới

kafkaTemplate.send(record).whenComplete((result, ex) -> {
    // handle accordingly
});

Spring Redis

Ở phiên bản mới, config của Spring Redis sẽ được chuyển từ spring.redis.* vào spring.data.redis.* trong application config:

• Phiên bản trước

application.yml

spring:
    redis:
        # Redis configurations

• Phiên bản mới

application.yml

spring:
    data:
        redis:
            # Redis configurations

Thay đổi Spring Cloud Sleuth sang Micrometer Tracing

Thư viện Spring Cloud Sleuth sẽ hoàn toàn được thay thế bởi Micrometer Tracing. Các config liên quan sẽ được chuyển sang thư viện Spring Boot Actuator.

Với Disease Common, chúng tôi loại bỏ thư viện này và sử dụng Micrometer / Spring Boot Actuator cho việc monitor các metrics.

Apache HTTP Client

Từ phiên bản Spring Framework 6, Apache HttpClient sẽ được thay thế hoàn toàn bởi Apache HttpClient 5.

Chúng tôi thực hiện loại bỏ thư viện cũ và thay thế bằng thư viện mới.

- dependency "org.apache.httpcomponents:httpclient"
+ dependency "org.apache.httpcomponents.client5:httpclient5"

Spring Batch

Disease Common sử dụng Spring Batch để triển khai hai service Disease Batch và Postman Batch.

Spring Boot 3 đã nâng cấp gói Spring Batch lên phiên bản 5 bao gồm nhiều thay đổi lớn nhỏ. Trong số đó, hai thay đổi lớn nhất của phiên bản này là việc loại bỏ annotation @EnableBatchProcessing và cách triển khai mới cho JobBuilderFactory và StepBuilderFactory.

• Với @EnableBatchProcessing: thực hiện loại bỏ @EnableBatchProcessing khỏi Application 

- @EnableBatchProcessing
@SpringBootApplication
public class BatchApplication {
    public static void main(String[] args) {
        System.exit(SpringApplication.exit(new SpringApplicationBuilder().sources(BatchApplication.class).run(args)));
    }
}

• Với JobBuilderFactory và StepBuilderFactory: sử dụng JobRepository và PlatformTransactionManager để thay thế cách triển khai cũ

• • Phiên bản trước

// Phiên bản Spring Batch 4
@Configuration
@RequiredArgsConstructor
public class SendingReservationConfig {
    private final JobBuilderFactory jobBuilderFactory;
    private final StepBuilderFactory stepBuilderFactory;
 
    @Bean
    public Job sendingReservationJob(Step sendingReservationStep) {
        return jobBuilderFactory.get(SENDING_RESERVATION_JOB)
                                .start(sendingReservationStep)
                                .build();
    }
 
    @Bean
    @JobScope
    public Step sendingReservationStep(SendingReservationTasklet tasklet) {
        return stepBuilderFactory.get(SENDING_RESERVATION_STEP)
                                 .tasklet(tasklet)
                                 .build();
    }
}

• • Phiên bản mới

// Phiên bản Spring Batch 5
@Configuration
@RequiredArgsConstructor
public class SendingReservationConfig {
    private final JobRepository jobRepository;
    private final PlatformTransactionManager platformTransactionManager;
 
    @Bean
    public Job sendingReservationJob(Step sendingReservationStep) {
        return new JobBuilder(SENDING_RESERVATION_JOB, jobRepository)
                       .start(sendingReservationStep)
                       .build();
    }
 
    @Bean
    @JobScope
    public Step sendingReservationStep(SendingReservationTasklet tasklet) {
        return new StepBuilder(SENDING_RESERVATION_STEP, jobRepository)
                       .tasklet(tasklet, platformTransactionManager)
                       .build();
    }
}

• Với deprecated API khác: chúng tôi cũng thực hiện các cập nhật liên quan đến các deprecated API được mô tả tại documentation của Spring Batch 5.

Thay đổi các thư viện khác

Song song với việc nâng cấp các thư viện thuộc hệ sinh thái của Spring, đội ngũ phát triển đã tiến hành nâng cấp các thư viện khác được sử dụng trong codebase.

• LINE Internal Service: nâng cấp nClavis (thư viện hỗ trợ mã hoá), L-station (thư viện tương tác với in-house service), etc.
• Thư viện common: nâng cấp Swagger 2 lên SpringDoc OpenAPI, lombok, logback, etc.

Với mỗi thư viện, chúng ta cần lưu ý cách triển khai mới và cách thiết lập config mới. Ví dụ, thư viện SpringDoc đã có sự thay đổi về config so với phiên bản Swagger trước đó:

application-apidoc.yml

- springfox.documentation.enabled: false
+ springdoc.api-docs.enabled: false
+ springdoc.swagger-ui.enabled: false

Vấn đề phát sinh

Trong quá trình nâng cấp, do code hiện tại không tương thích với phiên bản mới của Spring Data JPA, một vài @Bean trong ApplicationContext tạo ra một vòng kín. Điều này khiến codebase compile không thành công:

   authenticationController defined in file [/disease/microservice/authentication/auth/controller/AuthenticationController.class]
      ↓
   authenticationService defined in file [/disease/microservice/authentication/auth/service/AuthenticationService.class]
      ↓
   profileService defined in file [/disease/microservice/authentication/profile/common/service/ProfileService.class]
┌─────┐
|  diseaseProfileItemRepository defined in disease.repository.item.DiseaseProfileItemRepository defined in @EnableJpaRepositories declared on AuthenticationApplication
↑     ↓
|  jpa.DiseaseProfileItemRepository.fragments#0
↑     ↓
|  diseaseProfileRepositoryImplFragment
↑     ↓
|  diseaseProfileRepositoryImpl defined in file [/disease/microservice/authentication/profile/disease/repository/DiseaseProfileRepositoryImpl.class]
└─────┘

Chúng tôi đã thực hiện refactor để sửa lỗi này như sau:

• Thêm @Component annotation cho class DiseaseProfileRepositoryImpl
• Loại bỏ extends DiseaseProfileRepository trong DiseaseProfileItemRepository
• Thay thế diseaseProfileItemRepository.findDiseaseProfileByDiseaseId()  bởi diseaseProfileRepository.findDiseaseProfileByDiseaseId() tại toàn bộ codebase.

Kết quả

Dưới đây bảng tổng hợp những cập nhật mà chúng tôi đã thực hiện trong quá trình nâng cấp này.

Tên	Phiên bản trước	Phiên bản mới
JDK	11	17
Spring Boot	2.7.10	3.2.0
Gradle	7.0.2	8.5.0
Spring Batch	4.x	5.x
Spring Kafka	2.x	3.x
Spring Data Redis	2.x	3.x
Spring Cloud Sleuth	2021.0.5	(removed)
Springdoc OpenAPI	2.x	3.x
Thư viện internal của LINE	2.x	3.x

Tổng kết

Trong bài viết này, chúng tôi đã chia sẻ quá trình nâng cấp hệ thống Disease Common từ Spring Boot 2 lên Spring Boot 3. Có thể thấy được rõ ràng rằng việc nâng cấp này không chỉ dừng lại ở việc cập nhật version của Spring Boot, mà còn cần nhiều xử lý cho các thư viện xung quanh để codebase có thể vận hành được.

Dành cho các kĩ sư và các đội phát triển đang chuẩn bị cho quá trình nâng cấp tương tự, chúng tôi có một số gợi ý như sau:

• Ưu tiên hàng đầu là nắm được những thay đổi giữa hai phiên bản Spring Boot 2.7 và 3.0, do đây là nơi xảy ra nhiều thay đổi lớn nhất. Chúng sẽ rất hữu ích trong việc lên kế hoạch hay điều tra khi xảy ra lỗi.
• Trong quá trình nâng cấp, chúng ta nên đánh giá nguyên nhân vấn đề dựa vào những câu hỏi sau, theo thứ tự:
  • Có phải lỗi này do việc nâng cấp JDK 17 không? Liệu có phải do một feature của Java bị deprecate?
  • Có phải lỗi này do thay đổi của Spring Framework không?
  • Có phải lỗi này do thư viện hay không? Liệu có phải do chưa nâng cấp version mới nhất của thư viện hoặc do thư viện chưa hỗ trợ không?
• Cuối cùng, chúng ta cần có kịch bản rollback cho các trường hợp rủi ro.

Chúng tôi tin rằng với một kế hoạch kèm các bước chi tiết cho quá trình triển khai, chúng ta có thể nâng cấp hệ thống hiện tại một cách an toàn và tiết kiệm nhất.

Từ đó, sản phẩm sẽ trở nên tốt hơn, bảo mật hơn và đem lại những trải nghiệm tốt nhất cho người dùng.