Guida di stile per AIDL

Le best practice descritte qui servono da guida per lo sviluppo di interfacce AIDL in modo efficace e prestando attenzione alla flessibilità dell'interfaccia, in particolare quando AIDL viene utilizzato per definire un'API o interagire con le API.

AIDL può essere utilizzato per definire un'API quando le app devono interagire tra loro in un processo in background o devono interagire con il sistema. Per ulteriori informazioni sullo sviluppo di interfacce di programmazione nelle app con AIDL, consulta Android Interface Definition Language (AIDL). Per esempi di AIDL in pratica, consulta AIDL per HAL e AIDL stabile.

Controllo delle versioni

Ogni snapshot compatibile con le versioni precedenti di un'API AIDL corrisponde a una versione. Per acquisire uno snapshot, esegui m <module-name>-freeze-api. Ogni volta che viene rilasciato un client o un server dell'API (ad esempio in un treno Mainline), devi acquisire uno snapshot e creare una nuova versione. Per le API system-to-vendor, questo dovrebbe accadere con la revisione annuale della piattaforma.

Per ulteriori dettagli e informazioni sul tipo di modifiche consentite, consulta Interfacce di gestione delle versioni.

Linee guida per la progettazione delle API

Generali

1. Documenta tutto

  • Documenta ogni metodo per la sua semantica, gli argomenti, l'utilizzo di eccezioni predefinite, eccezioni specifiche del servizio e il valore restituito.
  • Documenta ogni interfaccia per la relativa semantica.
  • Documenta il significato semantico di enum e costanti.
  • Documenta tutto ciò che potrebbe non essere chiaro a un implementatore.
  • Fornisci esempi, se pertinenti.

2. Telaio

Utilizza lettere maiuscole per i tipi e lettere minuscole per metodi, campi e argomenti. Ad esempio, MyParcelable per un tipo di parcelable e anArgument per un argomento. Per gli acronimi, considera l'acronimo come una parola (NFC -> Nfc).

[-Wconst-name] I valori e le costanti enum devono essere ENUM_VALUE e CONSTANT_NAME

Interfacce

1. Nome

[-Wnome-interfaccia] Il nome di un'interfaccia deve iniziare con I, ad esempio IFoo.

2. Evitare un'interfaccia di grandi dimensioni con "oggetti" basati su ID

Preferisci le sottointerfacce quando ci sono molte chiamate relative a un'API specifica. Ciò offre i seguenti vantaggi:

  • Semplifica la comprensione del codice client o server
  • Semplifica il ciclo di vita degli oggetti
  • Sfrutta il fatto che i binder non possono essere contraffatti.

Sconsigliato: un'unica interfaccia di grandi dimensioni con oggetti basati su 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
}

Consigliato:interfacce individuali

interface IManager {
    IFoo getFoo();
}

interface IFoo {
    void begin(); // clients in other processes can't guess a binder
    void op();
}

3. Non combinare i metodi a senso unico con quelli a doppio senso

[-Wmixed-oneway] Non combinare metodi one-way con metodi non one-way, perché complica la comprensione del modello di threading per client e server. Nello specifico, quando leggi il codice client di una determinata interfaccia, devi controllare se ogni metodo bloccherà o meno.

4. Evita di restituire codici di stato

I metodi devono evitare i codici di stato come valori restituiti, poiché tutti i metodi AIDL hanno un codice di ritorno dello stato implicito. Consulta ServiceSpecificException o EX_SERVICE_SPECIFIC. Per convenzione, questi valori sono definiti come costanti in un'interfaccia AIDL. Per informazioni più dettagliate, consulta la sezione Gestione degli errori dei backend AIDL.

5. Array come parametri di output considerati dannosi

[-Wout-array] I metodi con parametri di output di array, comevoid foo(out String[] ret), in genere non sono validi perché le dimensioni dell'array di output devono essere dichiarate e allocate dal client in Java, pertanto le dimensioni dell'array di output non possono essere scelte dal server. Questo comportamento indesiderato si verifica a causa del funzionamento degli array in Java (non possono essere riallocati). Preferisci invece API come String[] foo().

6. Evita i parametri inout

[-Winout-parameter] Questo può confondere i client perché anche i parametri in sembrano parametri out.

7. Evita i parametri non array out e inout @nullable

[-Wout-nullable] Poiché il backend Java non gestisce l'annotazione @nullable, mentre altri backend lo fanno, out/inout @nullable T potrebbe comportare un comportamento incoerente tra i backend. Ad esempio, i backend non Java possono impostare un parametro out @nullable su null (in C++, impostandolo come std::nullopt), ma il client Java non può leggerlo come null.

Parcellable strutturati

1. Quando usare la funzionalità

Utilizza parcelable strutturati se devi inviare più tipi di dati.

In alternativa, se hai un singolo tipo di dati, ma prevedi di doverli estendere in futuro. Ad esempio, non usare String username. Utilizza un oggetto Parcelable espandibile, come il seguente:

parcelable User {
    String username;
}

In modo da poterlo estendere in futuro, come segue:

parcelable User {
    String username;
    int id;
}

2. Fornisci i valori predefiniti in modo esplicito

[-Wexplicit-default, -Wenum-explicit-default] Fornisci valori predefiniti espliciti per i campi.

Parcelli non strutturate

1. Quando usare la funzionalità

I parcelable non strutturati sono disponibili in Java con @JavaOnlyStableParcelable e nel backend NDK con @NdkOnlyStableParcelable. In genere si tratta di elementi parcelable vecchi ed esistenti che non possono essere strutturati.

Costanti ed enum

1. I campi di bit devono utilizzare campi costanti

I campi di bit devono utilizzare campi costanti (ad esempio const int FOO = 3; in un'interfaccia).

2. Gli enum devono essere insiemi chiusi.

Gli enum devono essere insiemi chiusi. Nota: solo il proprietario dell'interfaccia può aggiungere elementi enumerati. Se i fornitori o gli OEM devono estendere questi campi, è necessario un meccanismo alternativo. Ove possibile, è preferibile eseguire l'upstreaming delle funzionalità del fornitore. Tuttavia, in alcuni casi, i valori dei fornitori personalizzati potrebbero essere consentiti (anche se i fornitori dovrebbero avere un meccanismo per eseguire la versione, forse l'AIDL stesso, non dovrebbero essere in grado di entrare in conflitto tra loro e questi valori non devono essere esposti ad app di terze parti).

3. Evita valori come "NUM_ELEMENTS"

Poiché gli enum sono versionati, è consigliabile evitare i valori che indicano quanti valori sono presenti. In C++, questo problema può essere risolto con enum_range<>. Per Rust, utilizza enum_values(). In Java non esiste ancora una soluzione.

Sconsigliato:utilizzo di valori numerati

@Backing(type="int")
enum FruitType {
    APPLE = 0,
    BANANA = 1,
    MANGO = 2,
    NUM_TYPES, // BAD
}

4. Evita prefissi e suffissi ridondanti

[-Wredundant-name] Evita prefissi e suffissi ridondanti o ripetitivi in costanti ed enumeratori.

Non consigliato:utilizzo di un prefisso ridondante

enum MyStatus {
    STATUS_GOOD,
    STATUS_BAD // BAD
}

Consigliato:assegnare un nome direttamente all'enum

enum MyStatus {
    GOOD,
    BAD
}

FileDescriptor

[-Wfile-descriptor] L'utilizzo di FileDescriptor come argomento o come valore di ritorno di un metodo dell'interfaccia AIDL è sconsigliato. In particolare, quando l'AIDL è implementato in Java, questo potrebbe causare una perdita di descrittori file, a meno che non venga gestito con attenzione. In sostanza, se accetti un FileDescriptor, devi chiuderlo manualmente quando non è più in uso.

Per i backend nativi, non c'è problema perché FileDescriptor viene mappato a unique_fd che può essere chiuso automaticamente. Tuttavia, indipendentemente dal linguaggio di backend che intendi utilizzare, è consigliabile NON utilizzare FileDescriptor, in quanto ciò limiterà la tua libertà di modificare il linguaggio di backend in futuro.

Utilizza invece ParcelFileDescriptor, che è chiudibile automaticamente.

Unità variabili

Assicurati che le unità di misura delle variabili siano incluse nel nome in modo che siano ben definite e comprensibili senza dover fare riferimento alla documentazione

Esempi

long duration; // Bad
long durationNsec; // Good
long durationNanos; // Also good

double energy; // Bad
double energyMilliJoules; // Good

int frequency; // Bad
int frequencyHz; // Good

I timestamp devono indicare il relativo riferimento

I timestamp (in effetti, tutte le unità) devono indicare chiaramente le unità e i punti di riferimento.

Esempi

/**
 * 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;