Описанные здесь лучшие практики служат руководством по эффективной разработке интерфейсов AIDL с учетом гибкости интерфейса, особенно когда AIDL используется для определения API или взаимодействия с поверхностями API.
AIDL можно использовать для определения API, когда приложениям необходимо взаимодействовать друг с другом в фоновом процессе или взаимодействовать с системой. Для получения дополнительной информации о разработке интерфейсов программирования в приложениях с помощью AIDL см. Android Interface Definition Language (AIDL) . Примеры AIDL на практике см. AIDL для HAL и Stable AIDL .
Версионирование
Каждый обратно совместимый снимок API AIDL соответствует версии. Чтобы сделать снимок, запустите m <module-name>-freeze-api . Всякий раз, когда клиент или сервер API выпускается (например, в поезде Mainline), вам нужно сделать снимок и создать новую версию. Для API-интерфейсов system-to-vendor это должно происходить с ежегодной ревизией платформы.
Более подробную информацию о типах разрешенных изменений см. в разделе Интерфейсы управления версиями .
Руководство по проектированию API
Общий
1. Документируйте все
- Документируйте каждый метод с точки зрения его семантики, аргументов, использования встроенных исключений, исключений, специфичных для сервиса, и возвращаемого значения.
- Документируйте семантику каждого интерфейса.
- Документируйте семантическое значение перечислений и констант.
- Задокументируйте все, что может быть непонятно исполнителю.
- Приведите примеры, где это уместно.
2. Корпус
Используйте верхний camel case для типов и нижний camel case для методов, полей и аргументов. Например, MyParcelable для parcelable типа и anArgument для аргумента. Для сокращений рассмотрите сокращение a word ( NFC -> Nfc ).
[-Wconst-name] Значения перечисления и константы должны быть ENUM_VALUE и CONSTANT_NAME
Интерфейсы
1. Наименование
[-Winterface-name] Имя интерфейса должно начинаться с I like IFoo .
2. Избегайте больших интерфейсов с «объектами» на основе идентификаторов.
Предпочитайте подинтерфейсы, когда есть много вызовов, связанных с определенным API. Это дает следующие преимущества:
- Облегчает понимание клиентского или серверного кода
- Упрощает жизненный цикл объектов
- Использует преимущество, заключающееся в том, что переплеты невозможно подделать.
Не рекомендуется: один большой интерфейс с объектами на основе идентификаторов.
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
}
Рекомендуется: индивидуальные интерфейсы
interface IManager {
IFoo getFoo();
}
interface IFoo {
void begin(); // clients in other processes can't guess a binder
void op();
}
3. Не смешивайте односторонние и двусторонние методы.
[-Wmixed-oneway] Не смешивайте односторонние методы с неодносторонними, поскольку это усложняет понимание потоковой модели для клиентов и серверов. В частности, при чтении клиентского кода определенного интерфейса вам нужно искать для каждого метода, будет ли этот метод блокироваться или нет.
4. Избегайте возврата кодов статуса
Методы должны избегать кодов состояния в качестве возвращаемых значений, поскольку все методы AIDL имеют неявный код возврата состояния. См. ServiceSpecificException или EX_SERVICE_SPECIFIC . По соглашению эти значения определяются как константы в интерфейсе AIDL. Более подробная информация находится в разделе Обработка ошибок бэкэндов AIDL .
5. Массивы как выходные параметры считаются вредными
[-Wout-array] Методы с выходными параметрами массива, например void foo(out String[] ret) обычно плохи, поскольку размер выходного массива должен быть объявлен и выделен клиентом в Java, и поэтому размер выходного массива не может быть выбран сервером. Это нежелательное поведение происходит из-за того, как работают массивы в Java (их нельзя перераспределять). Вместо этого предпочитайте API, например String[] foo() .
6. Избегайте входных и выходных параметров
[-Winout-parameter] Это может сбить с толку клиентов, поскольку даже in параметры выглядят как out параметры.
7. Избегайте параметров out и inout @nullable, не являющихся массивами
[-Wout-nullable] Поскольку бэкенд Java не обрабатывает аннотацию @nullable , в то время как другие бэкенды обрабатывают, out/inout @nullable T может привести к непоследовательному поведению между бэкендами. Например, бэкенды, не относящиеся к Java, могут установить параметр out @nullable в значение null (в C++, установив его как std::nullopt ), но клиент Java не сможет прочитать его как null.
Структурированные посылки
1. Когда использовать
Используйте структурированные посылки, если вам нужно отправить несколько типов данных.
Или, когда у вас есть один тип данных, но вы ожидаете, что вам понадобится расширить его в будущем. Например, не используйте String username . Используйте расширяемый parcelable, например, следующий:
parcelable User {
String username;
}
Чтобы в будущем вы могли расширить его следующим образом:
parcelable User {
String username;
int id;
}
2. Явно укажите значения по умолчанию
[-Wexplicit-default, -Wenum-explicit-default] Укажите явные значения по умолчанию для полей.
Неструктурированные парцелляты
1. Когда использовать
Неструктурированные parcelables доступны в Java с @JavaOnlyStableParcelable и в бэкэнде NDK с @NdkOnlyStableParcelable . Обычно это старые и существующие parcelables, которые не могут быть структурированы.
Константы и перечисления
1. Битовые поля должны использовать константные поля.
Битовые поля должны использовать константные поля (например, const int FOO = 3; в интерфейсе).
2. Перечисления должны быть замкнутыми множествами.
Перечисления должны быть закрытыми наборами. Примечание: добавлять элементы перечисления может только владелец интерфейса. Если поставщикам или OEM-производителям необходимо расширить эти поля, необходим альтернативный механизм. По возможности следует отдавать предпочтение функциональности поставщика вышестоящего уровня. Однако в некоторых случаях можно разрешить использование пользовательских значений поставщика (хотя у поставщиков должен быть механизм для версионирования этого, возможно, сам AIDL, они не должны конфликтовать друг с другом, и эти значения не должны быть доступны сторонним приложениям).
3. Избегайте значений типа «NUM_ELEMENTS»
Поскольку перечисления версионны, следует избегать значений, указывающих, сколько значений присутствует. В C++ это можно обойти с помощью enum_range<> . Для Rust используйте enum_values() . В Java пока нет решения.
Не рекомендуется: использовать числовые значения.
@Backing(type="int")
enum FruitType {
APPLE = 0,
BANANA = 1,
MANGO = 2,
NUM_TYPES, // BAD
}
4. Избегайте лишних префиксов и суффиксов.
[-Wredundant-name] Избегайте избыточных или повторяющихся префиксов и суффиксов в константах и перечислителях.
Не рекомендуется: использовать избыточный префикс.
enum MyStatus {
STATUS_GOOD,
STATUS_BAD // BAD
}
Рекомендуется: прямое указание имени перечисления
enum MyStatus {
GOOD,
BAD
}
ФайлДескриптор
[-Wfile-descriptor] Использование FileDescriptor в качестве аргумента или возвращаемого значения метода интерфейса AIDL крайне не рекомендуется. Особенно, когда AIDL реализован в Java, это может привести к утечке файлового дескриптора, если не обращаться с этим осторожно. По сути, если вы принимаете FileDescriptor , вам нужно вручную закрыть его, когда он больше не используется.
Для собственных бэкендов вы в безопасности, потому что FileDescriptor сопоставляется с unique_fd , который является автоматически закрываемым. Но независимо от того, какой язык бэкенда вы будете использовать, разумно вообще НЕ использовать FileDescriptor , потому что это ограничит вашу свободу менять язык бэкенда в будущем.
Вместо этого используйте ParcelFileDescriptor , который автоматически закрывается.
Переменные единицы
Убедитесь, что в название включены переменные единицы измерения, чтобы их единицы измерения были четко определены и понятны без необходимости ссылаться на документацию.
Примеры
long duration; // Bad
long durationNsec; // Good
long durationNanos; // Also good
double energy; // Bad
double energyMilliJoules; // Good
int frequency; // Bad
int frequencyHz; // Good
Временные метки должны указывать ссылку.
Временные метки (фактически, все единицы!) должны четко указывать единицы измерения и точки отсчета.
Примеры
/**
* 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;