Khắc phục lỗi 'Serializer for class is not found' trong Kotlinx Serialization

Lỗi Crash Gây Khó ChịuBạn đã xây dựng các mô hình dữ liệu và tích hợp kotlinx.serialization để xử lý các phản hồi API. Mọi thứ trông có vẻ hoàn hảo cho đến khi bạn chạy lệnh Json.decodeFromString<User>(jsonString). Thay vì nhận được một đối tượng chứa dữ liệu, ứng dụng của bạn gặp lỗi với ngoại lệ sau:

kotlinx.serialization.SerializationException: Serializer for class 'User' is not found. 
Mark the class as @Serializable or provide the serializer explicitly.

Lỗi này thường xuất hiện khi chạy ứng dụng (runtime) khi thư viện tìm kiếm đối tượng companion $serializer được tạo tự động nhưng không thấy. Nó cũng có thể xảy ra trong quá trình biên dịch (compile-time) nếu môi trường build của bạn không tương tác đúng với trình biên dịch Kotlin.

Tại sao Kotlinx Serialization lại khác biệtCác thư viện cũ như Gson hoặc Jackson sử dụng reflection để kiểm tra bên trong các class khi ứng dụng đang chạy. Kotlinx Serialization đi theo một hướng khác. Nó là một công cụ dựa trên trình biên dịch. Nó dựa vào một plugin trình biên dịch Kotlin cụ thể để tạo ra logic tuần tự hóa (serialization) trong khi bạn build APK. Nếu plugin đó không hoạt động, annotation @Serializable chỉ là một chú thích trang trí mà thư viện sẽ bỏ qua.

Hầu hết các nhà phát triển gặp phải lỗi này vì một trong bốn lý do sau:

• Thiếu plugin trình biên dịch kotlinx-serialization trong Gradle.- Bạn quên annotation @Serializable trên một data class lồng nhau.- R8 (ProGuard) đã loại bỏ mã nguồn được tạo ra trong bản build release của bạn.- Có sự không tương thích phiên bản giữa Kotlin (ví dụ: 1.9.20) và thư viện serialization (ví dụ: 1.6.0).## Cách Khắc Phục Từng Bước### 1. Áp dụng Plugin Trình biên dịchChỉ thêm dependency runtime (dòng implementation) là không đủ. Bạn phải yêu cầu trình biên dịch Kotlin tạo thêm mã bổ trợ. Hãy mở file build.gradle cấp app và đảm bảo plugin đã được đăng ký. Đối với Groovy (build.gradle):

plugins {
    id 'com.android.application'
    id 'org.jetbrains.kotlin.android'
    // Thành phần quan trọng còn thiếu:
    id 'org.jetbrains.kotlin.plugin.serialization' version '1.9.22' 
}

Đối với Kotlin DSL (build.gradle.kts):

plugins {
    id("com.android.application")
    id("org.jetbrains.kotlin.android")
    // Đảm bảo phiên bản này khớp với phiên bản Kotlin của dự án
    kotlin("plugin.serialization") version "1.9.22"
}

2. Kiểm tra lại các AnnotationMỗi class tham gia vào chuỗi tuần tự hóa đều cần có annotation. Nếu class User của bạn chứa class Address, cả hai đều cần được đánh dấu. Đây là một sai sót phổ biến khi xử lý các cấu trúc JSON phức tạp và lồng nhau.

import kotlinx.serialization.Serializable

@Serializable
data class User(
    val id: Int,
    val name: String,
    val location: Address // Address cũng phải có @Serializable!
)

3. Cấu hình R8 cho bản Build ReleaseỨng dụng của bạn hoạt động ở chế độ Debug nhưng bị crash ở bản Release? Đó là vấn đề điển hình của R8. Công cụ rút gọn mã (shrinker) coi các class $serializer được tạo ra là "không sử dụng" và xóa chúng để tiết kiệm dung lượng. Bạn cần giữ nguyên các class này.

Thêm các quy tắc sau vào file proguard-rules.pro của bạn:

# Giữ lại logic Serializer cho các class có annotation
-keepclassmembernames class * {
    @kotlinx.serialization.Serializable *;
}

# Ngăn R8 xóa các $serializer được tạo ra
-keepclassnames class kotlinx.serialization.internal.** { *; }
-keepclassmembers class * extends kotlinx.serialization.KSerializer {
    public static ** INSTANCE;
}

Mẹo Chuyên Sâu để DebugLuôn xác minh nguồn JSON của bạn trước khi đi sâu vào thay đổi mã nguồn. Chỉ một dấu phẩy bị thiếu hoặc một giá trị null trong một trường non-nullable cũng có thể gây ra các lỗi gây hiểu lầm. Tôi thường sử dụng JSON Formatter & Validator trên ToolCraft để kiểm tra các chuỗi API thô. Nó nhanh chóng làm nổi bật các sai lệch cấu trúc có thể đang ẩn sau thông báo 'Serializer not found'.

Nếu bạn đang làm việc trong một dự án đa module (multi-module), hãy nhớ rằng plugin kotlin-serialization không được kế thừa tự động. Bạn phải áp dụng nó cho từng module có chứa class @Serializable. Nếu Module A sử dụng một data class từ Module B, và Module B không có plugin này, ứng dụng của bạn sẽ bị crash khi chạy.

Xác Minh Cuối CùngThực hiện ba bước sau để đảm bảo lỗi đã được khắc phục hoàn toàn:

• Chạy Clean Project sau đó là Rebuild Project. Việc này bắt buộc plugin trình biên dịch phải chạy lại.- Kiểm tra lệnh gọi Json.decodeFromString ở chế độ Debug trước.- Build một bản Release APK và kiểm tra trên thiết bị vật lý. Điều này xác nhận rằng các quy tắc ProGuard của bạn thực sự hoạt động.