Mit Code-Inspektionstools wie lint können Sie Probleme finden und Ihren Code verbessern, aber Inspektionstools können nur einen bestimmten Teil davon ableiten. Android-Ressourcen-IDs verwenden beispielsweise ein int, um Strings, Grafiken, Farben und andere Ressourcentypen zu identifizieren. Prüftools können daher nicht erkennen, ob Sie anstelle einer Farbe eine Stringressource angegeben haben. In diesem Fall wird Ihre App möglicherweise falsch gerendert oder kann gar nicht ausgeführt werden, auch wenn Sie die Codeprüfung verwenden.
Mit Anmerkungen können Sie Code-Prüftools wie Lint Hinweise geben, um diese subtileren Codeprobleme zu erkennen. Annotationen werden als Metadaten-Tags hinzugefügt, die Sie an Variablen, Parameter und Rückgabewerte anhängen, um Methodenrückgabewerte, übergebene Parameter, lokale Variablen und Felder zu prüfen. In Kombination mit Code-Prüftools können Anmerkungen Ihnen helfen, Probleme wie Nullzeigerausnahmen und Konflikte mit Ressourcentypen zu erkennen.
Android unterstützt eine Vielzahl von Annotationen über die Jetpack-Annotationsbibliothek.
Der Zugriff auf die Bibliothek erfolgt über das Paket androidx.annotation.
Hinweis:Wenn ein Modul eine Abhängigkeit von einem Annotationsprozessor hat, müssen Sie entweder die Abhängigkeitskonfiguration kapt oder ksp für Kotlin oder die annotationProcessor-Abhängigkeitskonfiguration für Java verwenden, um diese Abhängigkeit hinzuzufügen.
Ihrem Projekt Anmerkungen hinzufügen
Wenn Sie Anmerkungen in Ihrem Projekt aktivieren möchten, fügen Sie Ihrer Bibliothek oder App die Abhängigkeit androidx.annotation:annotation hinzu. Alle hinzugefügten Anmerkungen werden geprüft, wenn Sie eine Codeüberprüfung oder lint-Aufgabe ausführen.
Abhängigkeit von der Jetpack-Anmerkungsbibliothek hinzufügen
Die Jetpack Annotations-Bibliothek wird im Maven-Repository von Google veröffentlicht.
Wenn Sie Ihrem Projekt die Jetpack-Anmerkungsbibliothek hinzufügen möchten, fügen Sie in der Datei build.gradle oder build.gradle.kts im Block dependencies die folgende Zeile ein:
dependencies { implementation("androidx.annotation:annotation:1.9.1") }
dependencies { implementation 'androidx.annotation:annotation:1.9.1' }
Wenn du Anmerkungen in deinem eigenen Bibliotheksmodul verwendest, sind diese in der Datei annotations.zip als Teil des Android Archive-Artefakts (AAR) im XML-Format enthalten. Durch das Hinzufügen der androidx.annotation-Abhängigkeit wird keine Abhängigkeit für Downstream-Nutzer Ihrer Bibliothek eingeführt.
Hinweis: Wenn Sie andere Jetpack-Bibliotheken verwenden, müssen Sie die Abhängigkeit androidx.annotation möglicherweise nicht hinzufügen. Da viele andere Jetpack-Bibliotheken von der Annotationsbibliothek abhängen, haben Sie möglicherweise bereits Zugriff auf die Annotationen.
Eine vollständige Liste der Anmerkungen im Jetpack-Repository finden Sie in der Referenz zur Jetpack-Anmerkungsbibliothek. Alternativ können Sie die automatische Vervollständigung verwenden, um die verfügbaren Optionen für die import androidx.annotation.-Anweisung aufzurufen.
Codeprüfungen ausführen
Wenn Sie eine Codeprüfung in Android Studio starten möchten, die die Validierung von Anmerkungen und die automatische Lint-Prüfung umfasst, wählen Sie im Menü Analysieren > Code prüfen aus. Android Studio zeigt Konfliktmeldungen an, um potenzielle Probleme zu melden, bei denen Ihr Code mit Anmerkungen in Konflikt steht, und um mögliche Lösungen vorzuschlagen.
Sie können Anmerkungen auch erzwingen, indem Sie die Aufgabe lint über die Befehlszeile ausführen. Das kann zwar nützlich sein, um Probleme mit einem Continuous Integration-Server zu melden, aber die lint-Aufgabe erzwingt keine Anmerkungen zur Nullwertprüfung (im nächsten Abschnitt beschrieben). Das geschieht nur in Android Studio. Weitere Informationen zum Aktivieren und Ausführen von Lint-Prüfungen finden Sie unter Code mit Lint-Prüfungen verbessern.
Auch wenn Annotationskonflikte Warnungen generieren, verhindern diese Warnungen nicht, dass Ihre Anwendung kompiliert wird.
Anmerkungen zur Nullwertigkeit
Anmerkungen zur Nullwertigkeit können in Java-Code hilfreich sein, um festzulegen, ob Werte null sein dürfen. Sie sind im Kotlin-Code weniger nützlich, da Kotlin Regeln zur Null-Zulässigkeit eingebaut hat, die beim Kompilieren erzwungen werden.Fügen Sie @Nullable- und @NonNull-Anmerkungen hinzu, um zu prüfen, ob eine bestimmte Variable, ein bestimmter Parameter oder ein bestimmter Rückgabewert null ist. Die Anmerkung @Nullable gibt eine Variable, einen Parameter oder einen Rückgabewert an, der null sein kann.
@NonNull gibt eine Variable, einen Parameter oder einen Rückgabewert an, der nicht null sein darf.
Wenn beispielsweise eine lokale Variable mit einem Nullwert als Parameter an eine Methode übergeben wird, die mit der Anmerkung @NonNull versehen ist, wird beim Erstellen des Codes eine Warnung ausgegeben, die auf einen Konflikt mit einem nicht nullwertigen Wert hinweist. Wenn Sie versuchen, auf das Ergebnis einer mit @Nullable gekennzeichneten Methode zu verweisen, ohne vorher zu prüfen, ob das Ergebnis null ist, wird eine Null-Warnung ausgegeben. Verwenden Sie @Nullable nur für den Rückgabewert einer Methode, wenn jede Verwendung der Methode explizit auf Null geprüft werden muss.
Das folgende Beispiel zeigt die Nullbarkeit in der Praxis. Im Kotlin-Beispielcode wird die @NonNull-Anmerkung nicht verwendet, da sie dem generierten Bytecode automatisch hinzugefügt wird, wenn ein nicht nullwertiger Typ angegeben wird. Im Java-Beispiel wird die Annotation @NonNull für die Parameter context und attrs verwendet, um zu prüfen, ob die übergebenen Parameterwerte nicht Null sind. Außerdem wird geprüft, ob die Methode onCreateView() selbst nicht null zurückgibt:
... /** Annotation not used because of the safe-call operator(?)**/ override fun onCreateView( name: String?, context: Context, attrs: AttributeSet ): View? { ... } ...
import androidx.annotation.NonNull; ... /** Add support for inflating the <fragment> tag. **/ @NonNull @Override public View onCreateView(String name, @NonNull Context context, @NonNull AttributeSet attrs) { ... } ...
Analyse der Null-Zulässigkeit
Android Studio unterstützt die Ausführung einer Nullbarkeitsanalyse, um Null-Anmerkungen automatisch abzuleiten und in Ihren Code einzufügen. Bei einer Analyse der Nullbarkeit werden die Verträge in den Methodenhierarchien in Ihrem Code geprüft, um Folgendes zu erkennen:
- Aufrufen von Methoden, die null zurückgeben können.
- Methoden, die nicht null zurückgeben sollten.
- Variablen wie Felder, lokale Variablen und Parameter, die null sein können.
- Variablen wie Felder, lokale Variablen und Parameter, die keinen Nullwert enthalten können.
Die entsprechenden Null-Anmerkungen werden dann automatisch an den erkannten Stellen eingefügt.
Wenn Sie in Android Studio eine Analyse der Nullbarkeit ausführen möchten, wählen Sie Analysieren > Nulle inferieren aus. Android Studio fügt die Android-Anmerkungen @Nullable und @NonNull an den erkannten Stellen in Ihrem Code ein. Nachdem Sie eine Null-Analyse ausgeführt haben, sollten Sie die eingefügten Annotationen überprüfen.
Hinweis:Wenn Sie Annotationen zu Nullwerten hinzufügen, schlägt die automatische Vervollständigung möglicherweise die IntelliJ-Annotationen
@Nullable und @NotNull anstelle der Android-Null-Annotationen vor. Die entsprechende Bibliothek kann dann automatisch importiert werden. Der Lint-Checker von Android Studio sucht jedoch nur nach den Null-Anmerkungen von Android. Achten Sie beim Überprüfen Ihrer Annotationen darauf, dass Ihr Projekt die Android-Null-Annotationen verwendet, damit Sie während der Codeprüfung von der Lint-Prüfung ordnungsgemäß benachrichtigt werden.
Ressourcenanmerkungen
Die Validierung von Ressourcentypen kann nützlich sein, da Android-Referenzen auf Ressourcen wie drawable- und string-Ressourcen als Ganzzahlen übergeben werden.
Code, der erwartet, dass ein Parameter auf einen bestimmten Ressourcentyp wie etwa String verweist, kann an den erwarteten Referenztyp von int übergeben werden, tatsächlich aber auf einen anderen Ressourcentyp wie etwa eine R.string-Ressource verweisen.
Fügen Sie beispielsweise @StringRes-Anmerkungen hinzu, um zu prüfen, ob ein Ressourcenparameter eine R.string-Referenz enthält, wie hier gezeigt:
abstract fun setTitle(@StringRes resId: Int)
public abstract void setTitle(@StringRes int resId)
Bei der Codeprüfung wird durch die Anmerkung eine Warnung generiert, wenn im Parameter keine R.string-Referenz übergeben wird.
Anmerkungen für andere Ressourcentypen wie @DrawableRes, @DimenRes, @ColorRes und @InterpolatorRes können mit demselben Anmerkungsformat hinzugefügt und während der Codeprüfung ausgeführt werden.
Wenn Ihr Parameter mehrere Ressourcentypen unterstützt, können Sie für einen bestimmten Parameter mehrere Anmerkungen zu Ressourcentypen hinzufügen. Verwenden Sie @AnyRes, um anzugeben, dass der kommentierte Parameter beliebiger Art sein kann.R
Sie können zwar mit @ColorRes angeben, dass ein Parameter eine Farbressource sein soll, eine Farbzahl im Format RRGGBB oder AARRGGBB wird jedoch nicht als Farbressource erkannt. Verwenden Sie stattdessen die Anmerkung @ColorInt, um anzugeben, dass ein Parameter eine Farbganzzahl sein muss. Die Build-Tools melden falschen Code, der eine Farbressourcen-ID wie android.R.color.black anstelle einer Farbganzzahl an Methoden mit Anmerkungen übergibt.
Anmerkungen zu Threads
Mit Thread-Anmerkungen wird geprüft, ob eine Methode von einem bestimmten Thread aufgerufen wird. Die folgenden Thread-Hinweise werden unterstützt:
Die Build-Tools behandeln die Annotationen @MainThread und @UiThread als austauschbar, sodass Sie @UiThread-Methoden von @MainThread-Methoden aufrufen können und umgekehrt. Bei System-Apps mit mehreren Ansichten in verschiedenen Threads kann sich ein UI-Thread jedoch vom Hauptthread unterscheiden. Daher sollten Sie Methoden, die mit der Ansichtshierarchie einer App verknüpft sind, mit @UiThread und nur Methoden, die mit dem Lebenszyklus einer App verknüpft sind, mit @MainThread annotieren.
Wenn alle Methoden in einer Klasse dieselbe Threadanforderung haben, können Sie der Klasse eine einzelne Threadanmerkung hinzufügen, um sicherzustellen, dass alle Methoden in der Klasse von demselben Threadtyp aufgerufen werden.
Thread-Annotationen werden häufig verwendet, um zu validieren, dass mit @WorkerThread annotierte Methoden oder Klassen nur aus einem entsprechenden Hintergrundthread aufgerufen werden.
Anmerkungen zu Wertbeschränkungen
Verwenden Sie die Anmerkungen @IntRange, @FloatRange und @Size, um die Werte der übergebenen Parameter zu validieren. Sowohl @IntRange als auch @FloatRange sind am nützlichsten, wenn sie auf Parameter angewendet werden, bei denen Nutzer wahrscheinlich einen falschen Bereich erhalten.
Mit der Anmerkung @IntRange wird geprüft, ob ein Ganzzahl- oder Long-Parameterwert innerhalb eines bestimmten Bereichs liegt. Im folgenden Beispiel wird angegeben, dass der Parameter alpha einen Ganzzahlwert zwischen 0 und 255 enthalten muss:
fun setAlpha(@IntRange(from = 0, to = 255) alpha: Int) { ... }
public void setAlpha(@IntRange(from=0,to=255) int alpha) { ... }
Mit der Anmerkung @FloatRange wird geprüft, ob ein Float- oder Double-Parameterwert innerhalb eines bestimmten Bereichs von Gleitkommawerten liegt. Im folgenden Beispiel wird angegeben, dass der Parameter alpha einen Gleitkommawert zwischen 0,0 und 1,0 enthalten muss:
fun setAlpha(@FloatRange(from = 0.0, to = 1.0) alpha: Float) {...}
public void setAlpha(@FloatRange(from=0.0, to=1.0) float alpha) {...}
Mit der Anmerkung @Size wird die Größe einer Sammlung oder eines Arrays oder die Länge eines Strings geprüft. Mit der Anmerkung @Size können Sie die folgenden Qualitäten überprüfen:
- Mindestgröße, z. B.
@Size(min=2) - Maximale Größe, z. B.
@Size(max=2) - Genaue Größe, z. B.
@Size(2) - Eine Zahl, ein Vielfaches der Größe, z. B.
@Size(multiple=2)
Mit @Size(min=1) wird beispielsweise geprüft, ob eine Sammlung nicht leer ist, und mit @Size(3) wird überprüft, ob ein Array genau drei Werte enthält.
Im folgenden Beispiel ist zu sehen, dass das Array location mindestens ein Element enthalten muss:
fun getLocation(button: View, @Size(min=1) location: IntArray) { button.getLocationOnScreen(location) }
void getLocation(View button, @Size(min=1) int[] location) { button.getLocationOnScreen(location); }
Berechtigungshinweise
Verwenden Sie die Anmerkung @RequiresPermission, um die Berechtigungen des Aufrufers einer Methode zu prüfen. Wenn Sie prüfen möchten, ob eine einzelne Berechtigung aus einer Liste gültiger Berechtigungen vorhanden ist, verwenden Sie das Attribut anyOf. Verwenden Sie das Attribut allOf, um eine Reihe von Berechtigungen zu prüfen. Im folgenden Beispiel wird die Methode setWallpaper() mit einer Anmerkung versehen, die angibt, dass der Aufrufer der Methode die Berechtigung permission.SET_WALLPAPERS haben muss:
@RequiresPermission(Manifest.permission.SET_WALLPAPER) @Throws(IOException::class) abstract fun setWallpaper(bitmap: Bitmap)
@RequiresPermission(Manifest.permission.SET_WALLPAPER) public abstract void setWallpaper(Bitmap bitmap) throws IOException;
Im folgenden Beispiel muss der Aufrufer der copyImageFile()-Methode sowohl Lesezugriff auf den externen Speicher als auch Lesezugriff auf die Standortmetadaten im kopierten Bild haben:
@RequiresPermission(allOf = [ Manifest.permission.READ_EXTERNAL_STORAGE, Manifest.permission.ACCESS_MEDIA_LOCATION ]) fun copyImageFile(dest: String, source: String) { ... }
@RequiresPermission(allOf = { Manifest.permission.READ_EXTERNAL_STORAGE, Manifest.permission.ACCESS_MEDIA_LOCATION}) public static final void copyImageFile(String dest, String source) { //... }
Legen Sie die Berechtigungsanforderung für Berechtigungen für Intents in das Stringfeld fest, das den Namen der Intent-Aktion definiert:
@RequiresPermission(android.Manifest.permission.BLUETOOTH) const val ACTION_REQUEST_DISCOVERABLE = "android.bluetooth.adapter.action.REQUEST_DISCOVERABLE"
@RequiresPermission(android.Manifest.permission.BLUETOOTH) public static final String ACTION_REQUEST_DISCOVERABLE = "android.bluetooth.adapter.action.REQUEST_DISCOVERABLE";
Wenn für Inhaltsanbieter separate Berechtigungen für Lese- und Schreibzugriff erforderlich sind, setzen Sie jede Berechtigungsanforderung in eine Anmerkung vom Typ @RequiresPermission.Read oder @RequiresPermission.Write:
@RequiresPermission.Read(RequiresPermission(READ_HISTORY_BOOKMARKS)) @RequiresPermission.Write(RequiresPermission(WRITE_HISTORY_BOOKMARKS)) val BOOKMARKS_URI = Uri.parse("content://browser/bookmarks")
@RequiresPermission.Read(@RequiresPermission(READ_HISTORY_BOOKMARKS)) @RequiresPermission.Write(@RequiresPermission(WRITE_HISTORY_BOOKMARKS)) public static final Uri BOOKMARKS_URI = Uri.parse("content://browser/bookmarks");
Indirekte Berechtigungen
Wenn eine Berechtigung vom Wert abhängt, der für den Parameter einer Methode angegeben wurde, verwenden Sie @RequiresPermission für den Parameter selbst, ohne die Berechtigungen aufzulisten.
Die Methode startActivity(Intent) verwendet beispielsweise eine indirekte Berechtigung für die Intent-Instanz, die an die Methode übergeben wird:
abstract fun startActivity(@RequiresPermission intent: Intent, bundle: Bundle?)
public abstract void startActivity(@RequiresPermission Intent intent, @Nullable Bundle)
Wenn Sie indirekte Berechtigungen verwenden, führen die Build-Tools eine Datenflussanalyse durch, um zu prüfen, ob das an die Methode übergebene Argument @RequiresPermission-Anmerkungen enthält. Anschließend werden alle vorhandenen Annotationen aus dem Parameter für die Methode selbst erzwungen. Im Beispiel für startActivity(Intent) führen Anmerkungen in der Klasse Intent zu Warnungen bei ungültiger Verwendung von startActivity(Intent), wenn ein Intent ohne die entsprechenden Berechtigungen an die Methode übergeben wird, wie in Abbildung 1 dargestellt.
Abbildung 1. Die Warnung wurde durch eine indirekte Berechtigungsannotation für die startActivity(Intent)-Methode generiert.
Die Build-Tools generieren die Warnung für startActivity(Intent) aus der Anmerkung zum entsprechenden Intent-Aktionsnamen in der Intent-Klasse:
@RequiresPermission(Manifest.permission.CALL_PHONE) const val ACTION_CALL = "android.intent.action.CALL"
@RequiresPermission(Manifest.permission.CALL_PHONE) public static final String ACTION_CALL = "android.intent.action.CALL";
Bei Bedarf können Sie @RequiresPermission anstelle von @RequiresPermission.Read oder @RequiresPermission.Write verwenden, wenn Sie den Parameter einer Methode annotieren. Bei indirekten Berechtigungen sollte @RequiresPermission jedoch nicht in Verbindung mit den Anmerkungen für Lese- oder Schreibberechtigungen verwendet werden.
Anmerkungen zu Rückgabewerten
Mit der Anmerkung @CheckResult können Sie prüfen, ob das Ergebnis oder der Rückgabewert einer Methode tatsächlich verwendet wird. Anstatt jede nicht-void-Methode mit @CheckResult zu annotieren, fügen Sie die Anmerkung hinzu, um die Ergebnisse potenziell verwirrender Methoden zu verdeutlichen.
Neue Java-Entwickler glauben beispielsweise oft, dass durch <String>.trim() Leerzeichen aus dem ursprünglichen String entfernt werden. Wenn Sie die Methode mit @CheckResult-Flags annotieren, wird <String>.trim() verwendet, wenn der Aufrufer nichts mit dem Rückgabewert der Methode macht.
Im folgenden Beispiel wird die Methode checkPermissions() annotiert, um zu prüfen, ob auf den Rückgabewert der Methode tatsächlich verwiesen wird. Außerdem wird die Methode enforcePermission() als Ersatzmethode für den Entwickler vorgeschlagen:
@CheckResult(suggest = "#enforcePermission(String,int,int,String)") abstract fun checkPermission(permission: String, pid: Int, uid: Int): Int
@CheckResult(suggest="#enforcePermission(String,int,int,String)") public abstract int checkPermission(@NonNull String permission, int pid, int uid);
CallSuper-Anmerkungen
Mit der @CallSuper-Anmerkung können Sie prüfen, ob eine überschreibende Methode die Superimplementierung der Methode aufruft.
Im folgenden Beispiel wird die Methode onCreate() annotiert, damit alle überschreibenden Methodenimplementierungen super.onCreate() aufrufen:
@CallSuper override fun onCreate(savedInstanceState: Bundle?) { }
@CallSuper protected void onCreate(Bundle savedInstanceState) { }
Typdef-Anmerkungen
Mit Typedef-Annotationen wird geprüft, ob ein bestimmter Parameter, Rückgabewert oder Feld auf einen bestimmten Satz von Konstanten verweist. Außerdem wird die Codevervollständigung aktiviert, um automatisch die zulässigen Konstanten anzubieten.
Mit den Annotationen @IntDef und @StringDef können Sie Aufzählungsannotationen von Ganzzahl- und Stringsätzen erstellen, um andere Arten von Codeverweisen zu validieren.
Typedef-Annotationen verwenden @interface, um den neuen Enum-Annotationstyp zu deklarieren.
Die Annotationen @IntDef und @StringDef sowie @Retention annotieren die neue Annotation und sind erforderlich, um den Aufzählungstyp zu definieren. Die @Retention(RetentionPolicy.SOURCE)-Anmerkung weist den Compiler an, die aufgezählten Anmerkungsdaten nicht in der .class-Datei zu speichern.
Das folgende Beispiel zeigt die Schritte zum Erstellen einer Annotation, die prüft, ob ein als Methodenparameter übergebener Wert auf eine der definierten Konstanten verweist:
import androidx.annotation.IntDef //... // Define the list of accepted constants and declare the NavigationMode annotation. @Retention(AnnotationRetention.SOURCE) @IntDef(NAVIGATION_MODE_STANDARD, NAVIGATION_MODE_LIST, NAVIGATION_MODE_TABS) annotation class NavigationMode // Declare the constants. const val NAVIGATION_MODE_STANDARD = 0 const val NAVIGATION_MODE_LIST = 1 const val NAVIGATION_MODE_TABS = 2 abstract class ActionBar { // Decorate the target methods with the annotation. // Attach the annotation. @get:NavigationMode @setparam:NavigationMode abstract var navigationMode: Int }
import androidx.annotation.IntDef; //... public abstract class ActionBar { //... // Define the list of accepted constants and declare the NavigationMode annotation. @Retention(RetentionPolicy.SOURCE) @IntDef({NAVIGATION_MODE_STANDARD, NAVIGATION_MODE_LIST, NAVIGATION_MODE_TABS}) public @interface NavigationMode {} // Declare the constants. public static final int NAVIGATION_MODE_STANDARD = 0; public static final int NAVIGATION_MODE_LIST = 1; public static final int NAVIGATION_MODE_TABS = 2; // Decorate the target methods with the annotation. @NavigationMode public abstract int getNavigationMode(); // Attach the annotation. public abstract void setNavigationMode(@NavigationMode int mode); }
Beim Erstellen dieses Codes wird eine Warnung ausgegeben, wenn der Parameter mode nicht auf eine der definierten Konstanten (NAVIGATION_MODE_STANDARD, NAVIGATION_MODE_LIST oder NAVIGATION_MODE_TABS) verweist.
Kombinieren Sie @IntDef und @IntRange, um anzugeben, dass eine Ganzzahl entweder eine bestimmte Gruppe von Konstanten oder ein Wert innerhalb eines Bereichs sein kann.
Kombination von Konstanten mit Flags aktivieren
Wenn Nutzer die zulässigen Konstanten mit einem Flag kombinieren können (z. B. |, &, ^ usw.), können Sie eine Annotation mit einem flag-Attribut definieren, um zu prüfen, ob ein Parameter oder Rückgabewert auf ein gültiges Muster verweist.
Im folgenden Beispiel wird die DisplayOptions-Anmerkung mit einer Liste gültiger DISPLAY_-Konstanten erstellt:
import androidx.annotation.IntDef ... @IntDef(flag = true, value = [ DISPLAY_USE_LOGO, DISPLAY_SHOW_HOME, DISPLAY_HOME_AS_UP, DISPLAY_SHOW_TITLE, DISPLAY_SHOW_CUSTOM ]) @Retention(AnnotationRetention.SOURCE) annotation class DisplayOptions ...
import androidx.annotation.IntDef; ... @IntDef(flag=true, value={ DISPLAY_USE_LOGO, DISPLAY_SHOW_HOME, DISPLAY_HOME_AS_UP, DISPLAY_SHOW_TITLE, DISPLAY_SHOW_CUSTOM }) @Retention(RetentionPolicy.SOURCE) public @interface DisplayOptions {} ...
Wenn Sie Code mit einem Anmerkungs-Flag erstellen, wird eine Warnung generiert, wenn der dekorierte Parameter oder Rückgabewert auf kein gültiges Muster verweist.
Anmerkung beibehalten
Die @Keep-Anmerkung sorgt dafür, dass eine annotierte Klasse oder Methode nicht entfernt wird, wenn der Code zur Buildzeit minimiert wird. Diese Anmerkung wird in der Regel Methoden und Klassen hinzugefügt, auf die über Reflection zugegriffen wird, um zu verhindern, dass der Compiler den Code als nicht verwendet behandelt.
Achtung : Die Klassen und Methoden, die Sie mit @Keep annotieren, werden immer im APK Ihrer App angezeigt, auch wenn Sie in der Logik Ihrer App nie auf diese Klassen und Methoden verweisen.
Um die Größe Ihrer App klein zu halten, sollten Sie überlegen, ob es notwendig ist, jede @Keep-Anmerkung in Ihrer App beizubehalten. Wenn Sie Reflection verwenden, um auf eine annotierte Klasse oder Methode zuzugreifen, verwenden Sie in Ihren ProGuard-Regeln eine
-if-Bedingung, in der Sie die Klasse angeben, die die Reflection-Aufrufe ausführt.
Weitere Informationen zum Minimieren von Code und zum Angeben von Code, der nicht entfernt werden soll, finden Sie unter App verkleinern, verschleieren und optimieren.
Anmerkungen zur Sichtbarkeit von Code
Mit den folgenden Anmerkungen können Sie die Sichtbarkeit bestimmter Codeabschnitte wie Methoden, Klassen, Felder oder Pakete angeben.
Code für Tests sichtbar machen
Die Anmerkung @VisibleForTesting gibt an, dass eine kommentierte Methode auffälliger ist als normalerweise erforderlich, um die Methode testbar zu machen. Diese Anmerkung hat ein optionales Argument otherwise, mit dem Sie angeben können, wie die Sichtbarkeit der Methode wäre, wenn sie nicht für Tests sichtbar gemacht werden müsste. Lint verwendet das Argument otherwise, um die gewünschte Sichtbarkeit zu erzwingen.
Im folgenden Beispiel ist myMethod() normalerweise private, für Tests jedoch package-private. Mit der Kennzeichnung VisibleForTesting.PRIVATE zeigt Lint eine Meldung an, wenn diese Methode außerhalb des Kontexts aufgerufen wird, der für den private-Zugriff zulässig ist, z. B. von einer anderen Kompilierungseinheit.
@VisibleForTesting(otherwise = VisibleForTesting.PRIVATE) fun myMethod() { ... }
@VisibleForTesting(otherwise = VisibleForTesting.PRIVATE) void myMethod() { ... }
Sie können auch @VisibleForTesting(otherwise = VisibleForTesting.NONE) angeben, um anzugeben, dass eine Methode nur zu Testzwecken vorhanden ist. Dieses Formular entspricht der Verwendung von @RestrictTo(TESTS). Beide führen dieselbe Lint-Prüfung durch.
API einschränken
Die Anmerkung @RestrictTo gibt an, dass der Zugriff auf die annotierte API (Paket, Klasse oder Methode) eingeschränkt ist.
Unterklassen
Verwenden Sie das Annotationsform @RestrictTo(RestrictTo.Scope.SUBCLASSES), um den API-Zugriff auf abgeleitete Klassen zu beschränken.
Nur Klassen, die die annotierte Klasse erweitern, können auf diese API zugreifen. Der Java-Modifikator protected ist nicht restriktiv genug, da er den Zugriff von unabhängigen Klassen innerhalb desselben Pakets ermöglicht. Es gibt auch Fälle, in denen Sie eine Methode public für zukünftige Flexibilität beibehalten möchten, da Sie eine zuvor protected und überschriebene Methode public nie wieder protected machen können, aber einen Hinweis darauf geben möchten, dass die Klasse nur für die Verwendung innerhalb der Klasse oder von Unterklassen vorgesehen ist.
Bibliotheken
Verwenden Sie das Anmerkungsformular @RestrictTo(RestrictTo.Scope.LIBRARY_GROUP_PREFIX), um den API-Zugriff auf Ihre Bibliotheken einzuschränken.
Nur Ihr Bibliothekcode kann auf die annotierte API zugreifen. So können Sie Ihren Code nicht nur in einer beliebigen Pakethierarchie organisieren, sondern auch für eine Gruppe ähnlicher Bibliotheken freigeben. Diese Option ist bereits für Jetpack-Bibliotheken verfügbar, die viel Implementierungscode enthalten, der nicht für die externe Verwendung gedacht ist, aber public sein muss, um ihn für die verschiedenen ergänzenden Jetpack-Bibliotheken freizugeben.
Testen
Verwenden Sie das Anmerkungsformular @RestrictTo(RestrictTo.Scope.TESTS), um zu verhindern, dass andere Entwickler auf Ihre Test-APIs zugreifen.
Nur Testcode kann auf die annotierte API zugreifen. So wird verhindert, dass andere Entwickler APIs für die Entwicklung verwenden, die Sie nur zu Testzwecken verwenden möchten.