Phát hành nhiều thư viện Android dưới dạng một thư viện bằng Thư viện hợp nhất

Trong các dự án có nhiều mô-đun, việc phân phối Thư viện Android cho người dùng có thể gặp khó khăn khi bạn cố gắng duy trì cấu trúc dự án rõ ràng. Trong nhiều trường hợp, số lượng thư viện cần phát hành nhiều hơn dự kiến.

Trình bổ trợ Thư viện hợp nhất đi kèm với Trình bổ trợ Android cho Gradle hỗ trợ đóng gói nhiều mô-đun Thư viện Android thành một Thư viện Android có thể xuất bản. Điều này cho phép bạn mô-đun hoá mã nguồn và tài nguyên của thư viện trong bản dựng sao cho phù hợp, đồng thời tránh làm lộ cấu trúc của dự án sau khi phân phối.

Mẹo: Hãy xem Công thức Gradle của trình bổ trợ thư viện hợp nhất, trong đó có các bước định cấu hình thư viện hợp nhất và hướng dẫn thực tế hơn.

Việc phân phối dưới dạng một thư viện duy nhất có thể mang lại những lợi ích sau:

• Phần phụ thuộc đơn giản hoá: thay thế nhiều phần phụ thuộc thư viện bằng một tệp AAR duy nhất, giúp người dùng của bạn đơn giản hoá việc thiết lập dự án và quản lý phiên bản
• Giảm kích thước thư viện: có thể cải thiện khả năng rút gọn mã, giúp giảm kích thước AAR
• Cải thiện tính bảo mật: có thể giúp kiểm soát tốt hơn các thông tin triển khai nội bộ của thư viện đã xuất bản

Tạo thư viện hợp nhất

Để tạo một thư viện hợp nhất, bạn phải tạo một mô-đun Android mới, thêm các phần phụ thuộc, sau đó xuất bản thư viện hợp nhất.

Điều kiện tiên quyết

Để sử dụng trình bổ trợ Thư viện hợp nhất, hãy dùng AGP 9.0 trở lên. Các phiên bản trước của trình bổ trợ Thư viện hợp nhất có hành vi và vấn đề khác nhau, đã được khắc phục trong AGP 9.0.

Thêm mô-đun thư viện hợp nhất mới

Để sử dụng trình bổ trợ này, bạn phải thêm một mô-đun Android mới vào dự án:

Trong ví dụ này, mô-đun thư viện hợp nhất sẽ được gọi là myFusedLibrary.

1. Thêm include(":myFusedLibrary") vào tệp settings.gradle.kts.
2. Thêm android-fusedlibrary = { id = "com.android.fused-library", version.ref = "agp" } vào phần [plugins] trong tệp gradle/libs.versions.toml.
3. Thêm alias(libs.plugins.android.fusedlibrary) apply false vào khối trình bổ trợ trong tệp build.gradle.kts cấp cao nhất.
4. Để tạo mô-đun myFusedLibrary, hãy tạo một thư mục mới có tên là myFusedLibrary (nhấp chuột phải vào "My Application" (Ứng dụng của tôi) > New (Mới) > Directory (Thư mục)).
5. Tạo tệp build.gradle.kts trong mô-đun myFusedLibrary (nhấp chuột phải vào mô-đun myFusedLibrary > New > File (Mới > Tệp)).
6. Dán nội dung sau vào tệp myFusedLibrary/build.gradle.kts:

Kotlin

plugins {
    alias(libs.plugins.android.fusedlibrary)
    `maven-publish`
}

androidFusedLibrary {
    namespace = "com.example.myFusedLibrary"
    minSdk = 21
}

dependencies { }

Groovy

plugins {
    id 'com.android.fused-library'
}

androidFusedLibrary {
    namespace 'com.example.myFusedLibrary'
    minSdk 21
}

dependencies {

}

Thêm phần phụ thuộc

Chức năng cốt lõi của thư viện hợp nhất là đóng gói các phần phụ thuộc. Trình bổ trợ này hỗ trợ việc thêm các phần phụ thuộc của dự án cục bộ và thư viện bên ngoài. Để chỉ định các phần phụ thuộc cần đóng gói, hãy sử dụng cấu hình include. Các phần phụ thuộc bắc cầu không được đóng gói.

Ví dụ:

Kotlin

dependencies {
    include(project(":image-rendering"))
    include("mycoolfonts:font-wingdings:5.0")
}

Groovy

dependencies {
    include project(':image-rendering')
    include 'mycoolfonts:font-wingdings:5.0'
}

Lưu ý: Nếu một phần phụ thuộc được chỉ định bằng câu lệnh include phụ thuộc vào một dự án thư viện Android cục bộ, thì bạn phải phát hành dự án thư viện Android cục bộ đó lên một kho lưu trữ cục bộ đã định cấu hình. Để biết thêm thông tin, hãy xem bài viết Phát hành thư viện

Xuất bản thư viện đã hợp nhất

Bạn nên làm quen với việc phát hành thư viện Android trước khi phát hành thư viện hợp nhất. Việc phát hành thư viện hợp nhất cũng tương tự như phát hành Thư viện Android, tuy nhiên, có một số điểm khác biệt chính mà bạn phải cân nhắc để phát hành thư viện hợp nhất một cách chính xác:

• Bạn cũng phải áp dụng Trình bổ trợ phát hành của Maven cho mọi mô-đun đã áp dụng trình bổ trợ Thư viện hợp nhất.
• Ấn bản phải kế thừa từ fusedLibraryComponent vì ấn bản này cung cấp các phần phụ thuộc cần thiết để biên dịch cấu phần phần mềm thư viện hợp nhất.

Dưới đây là ví dụ về cấu hình ấn bản:

Kotlin

plugins {
    alias(libs.plugins.android.fusedlibrary)
    `maven-publish`
}

androidFusedLibrary { … }

dependencies { … }

publishing {
    publications {
        register<MavenPublication>("release") {
             groupId = "my-company"
             artifactId = "my-fused-library"
             version = "1.0"
             from(components["fusedLibraryComponent"])
        }
    }
}

Groovy

plugins {
    id 'com.android.fused-library'
    id 'maven-publish'
}

androidFusedLibrary { … }

dependencies { … }

publishing {
    publications {
        release(MavenPublication) {
            groupId = "my-company"
            artifactId = "my-fused-library"
            version = "1.0"
            afterEvaluate {
            from components.fusedLibraryComponent
        }
    }
}

Xuất bản thư viện hợp nhất để thử nghiệm

Bạn nên kiểm thử dựa trên một thư viện hợp nhất đã xuất bản từ một ứng dụng Android hoặc thư viện Android. Bạn nên phát hành thư viện hợp nhất và các phần phụ thuộc của dự án vào một kho lưu trữ Maven cục bộ.

Để phát hành cấu phần phần mềm thư viện hợp nhất lên kho lưu trữ cục bộ, hãy xác định một cấu hình tương tự như sau:

Kotlin

plugins {
    alias(libs.plugins.android.fusedlibrary)
    `maven-publish`
}

repositories {
    maven {
        name = "myLocalRepo"
        url = uri(layout.buildDirectory.dir("myLocalRepo"))
    }
}

Groovy

plugins {
    id 'com.android.fused-library'
    id 'maven-publish'
}

repositories {
    maven {
        name 'myLocalRepo'
        url layout.buildDirectory.dir('myLocalRepo')
    }
}

Tải thư viện đã hợp nhất lên

Để phân phối thư viện hợp nhất, hãy xem phần Tải thư viện lên.

Hành vi và biện pháp bảo vệ

Việc kết hợp các thư viện Android có những điểm phức tạp có thể khiến trình bổ trợ gặp khó khăn trong việc xác định mức độ ưu tiên. Ví dụ: hai thư viện có cùng classpath sẽ gây ra lỗi bản dựng khi hợp nhất thư viện. Quá trình hợp nhất tài nguyên sẽ xem xét thứ tự của các phần phụ thuộc được chỉ định khi chọn một tài nguyên có cùng tên trong các thư viện khác nhau.

• Bạn chỉ có thể phát hành thư viện hợp nhất dưới dạng cấu phần phần mềm thư viện Android AAR để thêm dưới dạng phần phụ thuộc.
• Không hỗ trợ việc hợp nhất các thư viện sử dụng tính năng liên kết dữ liệu.
• Bạn không thể hợp nhất nhiều loại bản dựng và phiên bản sản phẩm trong một thư viện hợp nhất. Tạo các thư viện hợp nhất riêng biệt cho các biến thể khác nhau.

Để cân bằng giữa mức độ cấu hình cần thiết và tính dễ sử dụng, trình bổ trợ sẽ không tạo bản dựng khi có xung đột không rõ ràng hoặc sử dụng phương pháp phỏng đoán khi hợp nhất cấu phần phần mềm. Thông tin chi tiết về cách hợp nhất các cấu phần phần mềm có trong bảng sau:

Loại	Hành vi
Lớp	Các thư viện có cùng classpath sẽ gây ra lỗi bản dựng khi hợp nhất thư viện.
Tài nguyên Android	Quá trình hợp nhất tài nguyên sẽ xem xét thứ tự của các phần phụ thuộc được chỉ định khi chọn một tài nguyên có cùng tên trong các phần phụ thuộc khác nhau.
Siêu dữ liệu AAR	Các phiên bản siêu dữ liệu AAR được hợp nhất bằng cách ưu tiên giá trị cao nhất từ mỗi thư viện phần phụ thuộc. Có một DSL được cung cấp để ghi đè các giá trị này. Kotlin androidFusedLibrary { aarMetadata { minCompileSdk = 21 minCompileSdkExtension = 1 } }
Tài nguyên Java	Không cho phép các tệp tài nguyên Java trong nhiều thư viện có đường dẫn giống hệt nhau và sẽ dẫn đến lỗi bản dựng.

Vấn đề đã biết

Thư viện hợp nhất là một trình bổ trợ mới và có một số vấn đề đã biết đang được xử lý để đáp ứng mọi trường hợp sử dụng. Bạn có thể báo cáo lỗi cho mọi vấn đề bạn gặp phải.

• Vấn đề #454305444: Thư viện chứa các quy tắc proguard của người dùng không được gọi là "proguard.txt" sẽ dẫn đến lỗi bản dựng. Đã khắc phục trong AGP 9.1 trở lên.
• Vấn đề #374982739: Thêm phần phụ thuộc tệp vào các tệp .aar khác
• Vấn đề #231433225: Không hỗ trợ hợp nhất cấu phần phần mềm RenderScript và Prefab

Thử nghiệm: Mô-đun thư viện hợp nhất chỉ được xuất bản dưới dạng thư viện bên ngoài. Bạn không thể thêm một dự án thư viện hợp nhất cục bộ làm phần phụ thuộc của dự án vào một mô-đun khác, trong ứng dụng Android hoặc mô-đun thư viện Android. Trình bổ trợ này chỉ cho phép xuất bản các mô-đun thư viện hợp nhất. Studio không hỗ trợ đầy đủ việc sử dụng dự án trực tiếp. Bạn có thể tắt quy định hạn chế chỉ xuất bản bằng cách thêm android.experimental.fusedLibrarySupport.publicationOnly=false vào tệp gradle.properties.

Tìm hiểu các phần phụ thuộc của thư viện hợp nhất

Thư viện hợp nhất không có nguồn và sử dụng hiệu quả các thư viện Android làm nguồn duy nhất, điều quan trọng là bạn phải hiểu rõ nguồn gốc của từng thành phần. Để liệt kê các phần phụ thuộc được hợp nhất vào cấu phần phần mềm kết quả và các phần phụ thuộc cần thiết để tạo cấu phần phần mềm, hãy chạy tác vụ gradle :report trên thư viện hợp nhất. Tác vụ này tạo một báo cáo JSON được lưu trong thư mục build/reports của thư viện hợp nhất.

Để biết thêm thông tin liên quan đến các phần phụ thuộc của trình bổ trợ nội bộ, hãy chạy tác vụ gradle :dependencies để xem trạng thái của cấu hình trình bổ trợ.