Praktik terbaik yang diuraikan di sini berfungsi sebagai panduan untuk mengembangkan antarmuka AIDL secara efektif dan dengan memperhatikan fleksibilitas antarmuka, terutama saat AIDL digunakan untuk menentukan API yang stabil dan kompatibel dengan versi lama.
AIDL dapat digunakan untuk menentukan API saat aplikasi perlu saling berinteraksi dalam proses latar belakang atau perlu berinteraksi dengan sistem.
AIDL stabil dengan @VintfStability digunakan untuk antarmuka HAL dan memungkinkan klien
dan server diupdate secara independen. Hal ini memerlukan kompatibilitas mundur dan data terstruktur.
Untuk informasi selengkapnya tentang cara mengembangkan antarmuka pemrograman di aplikasi dengan AIDL, lihat Bahasa Definisi Antarmuka Android (AIDL). Untuk contoh AIDL dalam praktiknya, lihat AIDL untuk HAL dan AIDL Stabil.
Pembuatan Versi
Setiap snapshot API AIDL yang kompatibel dengan versi lama sesuai dengan versi.
Untuk mengambil snapshot, jalankan m <module-name>-freeze-api. Setiap kali klien atau
server API dirilis (misalnya, di Mainline train), Anda perlu
mengambil snapshot dan membuat versi baru. Untuk API sistem ke vendor, hal ini akan
terjadi dengan revisi platform tahunan.
Saat dibekukan (disimpan dalam direktori aidl_api berversi), antarmuka
tidak boleh diubah. Anda hanya dapat mengedit direktori current. Anda dapat
dengan aman menambahkan metode ke akhir antarmuka, kolom ke akhir
parcelable, enumerator ke enum, dan anggota ke union.
Klien yang memanggil metode baru di server lama akan menerima error UNKNOWN_TRANSACTION, yang harus ditangani dengan baik oleh klien.
Untuk mengetahui detail dan informasi selengkapnya tentang jenis perubahan yang diizinkan, lihat Antarmuka pembuatan versi.
Membuat dependensi
Modul Android tidak dapat bergantung pada beberapa versi library yang berbeda yang dihasilkan dari aidl_interface. Versi library yang berbeda
menentukan jenis yang sama dalam namespace yang sama. Sistem build aidl Android
mengidentifikasi masalah ini dan menampilkan error dengan setiap grafik dependensi
yang berakhir pada versi library yang tidak cocok.
Hal ini dapat menyulitkan pengupdatean satu versi antarmuka umum saat modul berisi banyak dependensi dengan dependensinya sendiri.
Developer dapat menggunakan aidl_interface_defaults untuk mendeklarasikan dependensi antarmuka bersama pada antarmuka lain sehingga tidak semuanya perlu diupdate secara independen.
Sebaiknya gunakan modul *_defaults (seperti rust_defaults,
cc_defaults, java_defaults) untuk mengatur
dependensi pada library yang dihasilkan. Biasanya, ada default untuk antarmuka versi latest serta default untuk versi sebelumnya jika masih digunakan.
Developer dapat menggunakan aidl_interface_defaults untuk mendeklarasikan dependensi antarmuka bersama pada antarmuka lain sehingga tidak semuanya perlu diupdate secara independen.
Panduan desain API
Umum
1. Dokumentasikan semuanya
- Dokumentasikan setiap metode untuk semantik, argumen, penggunaan pengecualian bawaan, pengecualian khusus layanan, dan nilai yang ditampilkan.
- Dokumentasikan setiap antarmuka untuk semantiknya.
- Dokumentasikan makna semantik enum dan konstanta.
- Dokumentasikan apa pun yang mungkin tidak jelas bagi pelaksana.
- Berikan contoh jika relevan.
2. Casing
Gunakan upper camel case untuk jenis dan lower camel case untuk metode, kolom, dan
argumen. Misalnya, MyParcelable untuk jenis parcelable dan anArgument
untuk argumen. Untuk akronim, anggap akronim sebagai kata (NFC -> Nfc).
[-Wconst-name] Nilai dan konstanta enum harus berupa ENUM_VALUE dan
CONSTANT_NAME
3. Menghindari persyaratan pengetahuan global
API tidak boleh mengasumsikan bahwa developer memiliki pengetahuan global tentang seluruh codebase atau keahlian domain tertentu. Saat menangani ID khusus domain (seperti nama perangkat, ID, atau nama sebutan channel):
- Buat dokumentasi yang jelas tentang asal ID ini dan formatnya jika kedua sisi antarmuka perlu mengetahuinya.
- Atau, gunakan ID khusus antarmuka (seperti objek binder atau token kustom) dan minta satu sisi mengelola pemetaan ke nilai yang mendasarinya. Hal ini mengurangi konflik dan menghindari keharusan pengguna untuk memahami detail implementasi di luar area mereka.
4. Semua data terstruktur dan kompatibel dengan versi lama
Data tidak terstruktur seperti string, byte[], dan memori bersama harus memiliki format
yang stabil untuk kontennya, atau tidak terlihat di satu sisi antarmuka.
Misalnya, argumen string yang digunakan sebagai pesan error untuk hasil dapat
diterima dan dicatat ke dalam log untuk proses debug, tetapi tidak boleh diurai dan ditafsirkan
karena format dan kontennya mungkin tidak kompatibel dengan
versi lama. Jika sisi lain antarmuka perlu mengetahui jenis error
pada runtime, gunakan enum, konstanta, atau ServiceSpecificException.
Demikian pula, jangan melakukan serialisasi objek ke dalam byte[] atau memori bersama kecuali jika objek tersebut
stabil dan kompatibel dengan versi lama. Dalam beberapa kasus, Anda dapat menggunakan anotasi @FixedSize
untuk berbagi parcelable dan union dalam memori bersama dan Fast Message
Queue.
Antarmuka
1. Penamaan
[-Winterface-name] Nama antarmuka harus diawali dengan I seperti IFoo.
2. Menghindari antarmuka besar dengan "objek" berbasis ID
Pilih sub-antarmuka jika ada banyak panggilan yang terkait dengan API tertentu. Hal ini memberikan manfaat sebagai berikut:
- Membuat kode klien atau server lebih mudah dipahami
- Menyederhanakan siklus proses objek
- Memanfaatkan binder yang tidak dapat dipalsukan.
Tidak direkomendasikan: Satu antarmuka besar dengan objek berbasis ID
interface IManager {
int getFooId();
void beginFoo(int id); // clients in other processes can guess an ID
void opFoo(int id);
void recycleFoo(int id); // ownership not handled by type
}
Direkomendasikan: Antarmuka individual
interface IManager {
IFoo getFoo();
}
interface IFoo {
void begin(); // clients in other processes can't guess a binder
void op();
}
3. Jangan mencampur metode satu arah dengan metode dua arah
[-Wmixed-oneway] Jangan mencampur metode satu arah dengan metode non-satu arah, karena akan membuat pemahaman model threading menjadi rumit bagi klien dan server. Secara khusus, saat membaca kode klien antarmuka tertentu, Anda perlu mencari setiap metode apakah metode tersebut akan memblokir atau tidak.
4. Menghindari menampilkan kode status
Metode harus menghindari kode status sebagai nilai yang ditampilkan, karena semua metode AIDL memiliki
kode status yang ditampilkan secara implisit. Lihat ServiceSpecificException atau
EX_SERVICE_SPECIFIC. Berdasarkan konvensi, nilai ini didefinisikan sebagai konstanta dalam
antarmuka AIDL. Jika penundaan kustom atau data error unik diperlukan bersama dengan error, itulah satu-satunya saat objek respons kustom harus merepresentasikan error. Untuk mengetahui informasi yang lebih mendetail, lihat
Penanganan error.
5. Array sebagai parameter output dianggap berbahaya
[-Wout-array] Metode yang memiliki parameter output array, seperti
void foo(out String[] ret) biasanya buruk karena ukuran array output harus
dideklarasikan dan dialokasikan oleh klien di Java, sehingga ukuran output
array tidak dapat dipilih oleh server. Perilaku yang tidak diinginkan ini terjadi karena
cara kerja array di Java (array tidak dapat dialokasikan ulang). Sebagai gantinya, pilih API
seperti String[] foo().
6. Menghindari parameter inout
[-Winout-parameter] Hal ini dapat membingungkan klien karena parameter in pun terlihat seperti parameter out.
7. Menghindari parameter non-array @nullable out dan inout
[-Wout-nullable] Karena backend Java tidak menangani anotasi @nullable
sementara backend lain menanganinya, out/inout @nullable T dapat menyebabkan perilaku yang tidak konsisten
di seluruh backend. Misalnya, backend non-Java dapat menetapkan parameter @nullable
out ke null (di C++, menetapkannya sebagai std::nullopt), tetapi klien Java
tidak dapat membacanya sebagai null.
8. Menggunakan permintaan dan respons yang unik
Kelompokkan semua parameter yang diperlukan ke dalam satu input parcelable.
Buat parcelable permintaan dan respons khusus untuk setiap metode antarmuka,
bukan meneruskan primitif (misalnya, gunakan
ComputeResponse compute(in ComputeRequest request), bukan meneruskan variabel
terpisah). Hal ini memungkinkan argumen baru ditambahkan nanti tanpa mengubah tanda tangan fungsi. Pola ini sangat disarankan jika diperkirakan
lebih banyak parameter mungkin ditambahkan di masa mendatang, atau jika metode sudah memiliki lebih
dari empat parameter.
Metode yang tidak memerlukan input atau output tambahan tidak akan mendapatkan manfaat dari saran ini. Memikirkan setiap kasus secara eksplisit dan tetap fleksibel untuk perubahan di masa mendatang dapat mengurangi metode yang tidak digunakan lagi dan mengurangi kompleksitas untuk kode yang kompatibel dengan versi lama.
Jika metode tidak dibuat menggunakan pola ini, Anda dapat beralih ke pola ini dengan membuat metode baru dengan parcelable permintaan dan respons serta menghentikan penggunaan metode lama. Contoh:
void foo(int a, int b, int c); // original version, but deprecated in favor of the next version
void fooV2(in MyArg arg); // new version having int a, b, c, and d.
Parcelable terstruktur
1. Kapan digunakan
Gunakan parcelable terstruktur jika Anda memiliki beberapa jenis data untuk dikirim.
Atau, saat Anda memiliki satu jenis data, tetapi Anda memperkirakan bahwa Anda perlu
memperluasnya di masa mendatang. Misalnya, jangan gunakan String username. Gunakan
parcelable yang dapat diperluas, seperti berikut:
parcelable User {
String username;
}
Sehingga, pada masa mendatang, Anda dapat memperluasnya, sebagai berikut:
parcelable User {
String username;
int id;
}
2. Menyediakan nilai default secara eksplisit
[-Wexplicit-default, -Wenum-explicit-default] Memberikan nilai default eksplisit untuk kolom. Saat kolom baru ditambahkan ke parcelable, klien dan server lama akan menghapusnya, tetapi nilai default akan otomatis diisi untuk klien dan server baru.
3. Menggunakan ParcelableHolder untuk ekstensi vendor
Jika Anda menentukan parcelable AOSP yang perlu diperluas oleh produsen perangkat,
sematkan instance ParcelableHolder di objek Anda. Hal ini berfungsi sebagai
titik ekstensi tanpa menimbulkan konflik penggabungan. Hal ini mirip dengan
ekstensi antarmuka terlampir,
tetapi memungkinkan implementer menyertakan parcelable eksklusif mereka bersama
parcelable yang ada tanpa membuat antarmuka dan jenisnya sendiri.
4. Struktur data
- Gunakan array atau
Listparcelable untuk merepresentasikan peta, karena AIDL tidak mendukung jenisMapsecara native yang diterjemahkan dengan aman di semua backend native (misalnya,FeatureToScoreEntry[]). - Gunakan array objek
parcelableuntuk kolom berulang, bukan array primitif, untuk mencegah kebutuhan akan array paralel di masa mendatang. - Gunakan objek
parcelableyang diketik dengan kuat, bukan string yang diserialisasi atau JSON melalui IPC. - Gunakan enum, bukan boolean, untuk status agar memungkinkan perluasan di masa mendatang. Untuk bitmask, gunakan jenis
const int, bukanenum, untuk menghindari transmisi yang rumit di beberapa backend.
Parcelable tidak terstruktur
1. Kapan digunakan
Parcelable tidak terstruktur tersedia di Java dengan
@JavaOnlyStableParcelable dan di backend NDK dengan
@NdkOnlyStableParcelable. Biasanya, ini adalah parcelable lama dan yang sudah ada
yang tidak dapat disusun.
Konstanta dan enum
1. Bitfield harus menggunakan kolom konstanta
Bitfield harus menggunakan kolom konstan (misalnya, const int FOO = 3; di antarmuka).
2. Enum harus berupa set tertutup.
Enum harus berupa set tertutup. Catatan: hanya pemilik antarmuka yang dapat menambahkan elemen enum. Jika vendor atau OEM perlu memperluas kolom ini, diperlukan mekanisme alternatif. Jika memungkinkan, sebaiknya prioritaskan fungsi vendor upstream. Namun, dalam beberapa kasus, nilai vendor kustom mungkin diizinkan (meskipun, vendor harus memiliki mekanisme untuk membuat versi ini, mungkin AIDL itu sendiri, nilai tersebut tidak boleh bertentangan satu sama lain, dan nilai ini tidak boleh diekspos ke aplikasi pihak ketiga).
3. Hindari nilai seperti "NUM_ELEMENTS"
Karena enum memiliki versi, nilai yang menunjukkan jumlah nilai yang ada
harus dihindari. Di C++, hal ini dapat diatasi dengan enum_range<>. Untuk
Rust, gunakan enum_values(). Di Java, belum ada solusi.
Tidak direkomendasikan: Menggunakan nilai bernomor
@Backing(type="int")
enum FruitType {
APPLE = 0,
BANANA = 1,
MANGO = 2,
NUM_TYPES, // BAD
}
4. Hindari awalan dan akhiran yang berlebihan
[-Wredundant-name] Hindari awalan dan akhiran yang redundan atau berulang dalam konstanta dan enumerator.
Tidak direkomendasikan: Menggunakan awalan yang redundan
enum MyStatus {
STATUS_GOOD,
STATUS_BAD // BAD
}
Direkomendasikan: Memberi nama enum secara langsung
enum MyStatus {
GOOD,
BAD
}
FileDescriptor
[-Wfile-descriptor] Penggunaan FileDescriptor sebagai argumen atau nilai
yang ditampilkan dari metode antarmuka AIDL sangat tidak dianjurkan. Terutama, saat
AIDL diimplementasikan di Java, hal ini dapat menyebabkan kebocoran deskriptor file kecuali jika
ditangani dengan hati-hati. Pada dasarnya, jika Anda menerima FileDescriptor, Anda harus
menutupnya secara manual jika tidak lagi digunakan.
Untuk backend native, Anda aman karena FileDescriptor dipetakan ke unique_fd
yang dapat ditutup secara otomatis. Namun, terlepas dari bahasa backend yang akan Anda gunakan,
sebaiknya TIDAK menggunakan FileDescriptor sama sekali karena hal ini akan membatasi
kebebasan Anda untuk mengubah bahasa backend di masa mendatang.
Sebagai gantinya, gunakan ParcelFileDescriptor, yang dapat ditutup secara otomatis.
Unit variabel
Pastikan unit variabel disertakan dalam nama sehingga unitnya ditentukan dan dipahami dengan baik tanpa perlu merujuk dokumentasi referensi
Contoh
long duration; // Bad
long durationNsec; // Good
long durationNanos; // Also good
double energy; // Bad
double energyMilliJoules; // Good
int frequency; // Bad
int frequencyHz; // Good
Stempel waktu harus menunjukkan referensinya
Stempel waktu (bahkan, semua unit) harus menunjukkan unit dan titik referensinya dengan jelas.
Contoh
/**
* Time since device boot in milliseconds
*/
long timestampMs;
/**
* UTC time received from the NTP server in units of milliseconds
* since January 1, 1970
*/
long utcTimeMs;
Konkurensi dan operasi asinkron
Tangani operasi yang berjalan lama dengan antarmuka asinkron (oneway)
untuk menghindari pemblokiran.
Jika layanan tidak memercayai kliennya, callback apa pun yang diterima dari
klien harus berupa antarmuka oneway. Tindakan ini mencegah klien memblokir layanan tanpa batas waktu.
Menyusun API asinkron yang terdiri dari panggilan maju, argumen input, dan antarmuka callback untuk mendapatkan hasil. Lihat Menggunakan permintaan dan respons unik untuk rekomendasi argumen.