Codeüberprüfung mit Anmerkungen verbessern

Mit Code-Inspektionstools wie lint können Sie und Ihren Code verbessern können, aber Inspektions-Tools können nicht viel daraus ableiten. Android-Ressourcen-IDs Verwenden Sie beispielsweise ein int, um Strings, Grafiken, Farben und andere Ressourcentypen anzugeben. sodass Inspektionstools nicht erkennen können, ob Sie eine String-Ressource angegeben haben, eine Farbe angegeben hat. Das bedeutet, dass Ihre App möglicherweise falsch gerendert oder gar nicht ausgeführt wird. auch wenn Sie Code-Inspektion verwenden.

Mit Anmerkungen können Sie Hinweise für Codeinspektionstools wie Lint angeben, um diese zu erkennen kleinere Codeprobleme zu lösen. Anmerkungen werden als Metadaten-Tags hinzugefügt, die Sie an Variablen anhängen. und Rückgabewerte zur Prüfung von Rückgabewerten, übergebenen Parametern, lokalen Variablen, und Felder. In Verbindung mit Code-Inspektionstools können Anmerkungen dabei helfen, Probleme zu erkennen, z. B. Null-Zeigerausnahmen und Ressourcentypkonflikte.

Android unterstützt eine Vielzahl von Anmerkungen über die Jetpack-Anmerkungsbibliothek Der Zugriff auf die Bibliothek erfolgt über die androidx.annotation Paket.

Hinweis:Wenn ein Modul von einem Annotationsprozessor abhängig ist, Sie müssen entweder die Abhängigkeitskonfiguration kapt oder ksp für Kotlin verwenden oder die annotationProcessor-Abhängigkeitskonfiguration für Java, um Abhängigkeit.

Anmerkungen zum Projekt hinzufügen

Fügen Sie den androidx.annotation:annotation hinzu, um Anmerkungen in Ihrem Projekt zu aktivieren. -Abhängigkeit zu Ihrer Bibliothek oder App. Alle hinzugefügten Annotationen werden beim Ausführen eines Codes geprüft Inspektions- oder lint-Aufgabe.

Abhängigkeit der Jetpack-Annotations-Bibliothek hinzufügen

Die Jetpack-Annotationsbibliothek wurde veröffentlicht auf Maven-Repository von Google. Um Ihrem Projekt die Jetpack Anotations-Bibliothek hinzuzufügen, fügen Sie Folgendes hinzu: im Block dependencies von build.gradle oder build.gradle.kts-Datei:

Kotlin

dependencies {
    implementation("androidx.annotation:annotation:1.8.1")
}

Cool

dependencies {
    implementation 'androidx.annotation:annotation:1.8.1'
}

Klicken Sie dann in der Symbolleiste oder in der angezeigten Synchronisierungsbenachrichtigung auf Jetzt synchronisieren.

Falls Sie Annotationen in Ihrem eigenen Bibliotheksmodul verwenden, sind die Annotationen Teil des Android Archive-Artefakt (AAR) im XML-Format in der Datei annotations.zip. Hinzufügen des Die androidx.annotation-Abhängigkeit bringt keine Abhängigkeit für nachgelagerte Nutzer mit sich. Ihrer Mediathek.

Hinweis:Wenn Sie andere Jetpack-Bibliotheken verwenden, ist es möglicherweise nicht erforderlich, die androidx.annotation-Abhängigkeit hinzuzufügen. Weil viele andere Jetpack-Bibliotheken hängen von der Annotationsbibliothek ab. Möglicherweise haben Sie bereits Zugriff auf die Anmerkungen.

Eine vollständige Liste der im Jetpack-Repository enthaltenen Annotationen finden Sie in der Jetpack-Anmerkungsbibliothek oder nutzen Sie die Funktion zur automatischen Vervollständigung, um die verfügbaren Optionen für die import androidx.annotation.-Anweisung.

Codeprüfungen ausführen

Um eine Codeinspektion aus Android Studio zu starten, die das Validieren von Anmerkungen und automatische Lint-Prüfung, wählen Sie Analysieren > Überprüfen Sie den Code auf der . Android Studio zeigt Konfliktmeldungen an, um potenzielle Probleme zu melden, bei denen Ihr Code Anmerkungen und mögliche Lösungen vorzuschlagen.

Sie können Annotationen auch erzwingen, indem Sie das Tag lint-Aufgabe über die Befehlszeile aus. Auch wenn dies beim Melden von Problemen hilfreich sein kann, mit einem Continuous Integration-Server, erzwingt die Aufgabe lint keine Nullstufe Anmerkungen (im folgenden Abschnitt beschrieben); nur in Android Studio. Weitere Informationen Informationen zum Aktivieren und Ausführen von Lint Inspektionen finden Sie unter Code mit Lint verbessern Überprüfungen.

Anmerkungskonflikte generieren zwar Warnungen, aber diese Warnungen verhindern nicht, dass Ihre App von der Kompilierung.

Annotationen von Null-Werten

Annotationen von Null-Werten können in Java-Code hilfreich sein, um zu erzwingen, ob Werte null sein können. Sie sind im Kotlin-Code weniger nützlich, da Kotlin-Regeln für die Null-Zulässigkeit eingebaut sind, die an folgenden Stellen erzwungen werden: der Kompilierungszeit.

@Nullable und @NonNull-Anmerkungen um den Nullwert einer Variablen, eines Parameters oder eines Rückgabewerts zu überprüfen. Das @Nullable Annotation 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, die einen Nullwert enthält, als Parameter an eine Methode übergeben wird, mit der Annotation @NonNull, die an diesen Parameter angehängt ist, wird beim Erstellen des Codes ein Warnung, die auf einen Konflikt ungleich null hinweist. Der Versuch, auf das Ergebnis eines durch @Nullable markierte Methode, ohne zuerst zu prüfen, ob das Ergebnis null ist, generiert eine Warnung vor NULL-Werten. @Nullable nur für den Rückgabewert einer Methode verwenden wenn jede Verwendung der Methode explizit auf Null überprüft werden muss.

Das folgende Beispiel zeigt die Null-Zulässigkeit in der Praxis. Der Kotlin-Beispielcode nutzt Die Annotation @NonNull, da sie dem generierten Bytecode automatisch hinzugefügt wird wenn ein Typ angegeben wird, der keine Nullwerte zulässt. Im Java-Beispiel wird die Annotation @NonNull verwendet. bei den Parametern context und attrs, 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:

Kotlin

...
    /** Annotation not used because of the safe-call operator(?)**/
    override fun onCreateView(
            name: String?,
            context: Context,
            attrs: AttributeSet
    ): View? {
        ...
    }
...

Java

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 Analyse zur Null-Zulässigkeit, um automatisch abzuleiten. und fügen Sie NULL-Wert-Annotationen in Ihren Code ein. Scans für die Null-Zulässigkeitsanalyse die Verträge in allen Methodenhierarchien in Ihrem Code, 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 von null.
• Variablen wie Felder, lokale Variablen und Parameter, die nicht einen Nullwert enthalten.

Die Analyse fügt dann automatisch die entsprechenden Null-Anmerkungen in die erkannten Standorte.

Um eine Analyse der Null-Zulässigkeit in Android Studio auszuführen, wählen Sie Analysieren > Nullität ableiten. Android Studio fügt die Android-Anmerkungen @Nullable und @NonNull erkannten Standorte in Ihrem Code. Nachdem Sie eine Null-Analyse durchgeführt haben, sollten Sie überprüfen, eingefügten Annotationen.

Hinweis:Beim Hinzufügen von Annotationen zu Nullwerten kann die automatische Vervollständigung IntelliJ vorschlagen @Nullable und @NotNull-Anmerkungen anstelle der Android-Null-Anmerkungen und die entsprechende Bibliothek möglicherweise automatisch importieren. Die Android Studio- Die Lint-Prüfung sucht nur nach den Android-Null-Annotationen. Bei der Bestätigung Ihrer -Annotationen an, vergewissern Sie sich, dass Ihr Projekt die Android-Null-Annotationen verwendet, damit das Lint Checker kann Sie während der Codeprüfung ordnungsgemäß benachrichtigen.

Ressourcenanmerkungen

Die Validierung von Ressourcentypen kann nützlich sein, da Android-Verweise auf Ressourcen wie drawable- und string-Ressourcen als Ganzzahlen übergeben werden.

Code, der erwartet, dass ein Parameter auf einen bestimmten Ressourcentyp wie String verweist, an den erwarteten Referenztyp int übergeben werden kann, aber auf einen anderen Ressourcentyp, z. B. R.string-Ressource.

Fügen Sie beispielsweise @StringRes-Annotationen zu Prüfen Sie, ob ein Ressourcenparameter einen Verweis auf R.string enthält, wie hier gezeigt:

Kotlin

abstract fun setTitle(@StringRes resId: Int)

Java

public abstract void setTitle(@StringRes int resId)

Während der Codeprüfung generiert die Annotation eine Warnung, wenn ein R.string-Verweis nicht im Parameter übergeben wird.

Annotationen für andere Ressourcentypen wie @DrawableRes, @DimenRes, @ColorRes und @InterpolatorRes können mit demselben Annotationsformat hinzugefügt und während der Codeprüfung ausgeführt werden.

Wenn Ihr Parameter mehrere Ressourcentypen unterstützt, können Sie einer bestimmten . @AnyRes verwenden , um anzugeben, dass der annotierte Parameter ein beliebiger Typ von R-Ressource sein kann.

Sie können mit @ColorRes zwar angeben, Parameter muss eine Farbressource, eine Farbzahl im Feld RRGGBB oder AARRGGBB-Format) wird nicht als Farbressource erkannt. Verwenden Sie stattdessen die Anmerkung @ColorInt, um geben an, dass ein Parameter eine Farb-Ganzzahl sein muss. Die Build-Tools melden falschen Code, übergibt statt einer Farbganzzahl eine Farbressourcen-ID wie android.R.color.black. Methoden annotiert.

Thread-Annotationen

Thread-Annotationen prüfen, ob eine Methode von einem bestimmten Typ von thread sein. Der folgende Thread -Annotationen werden unterstützt:

• @MainThread
• @UiThread
• @WorkerThread
• @BinderThread
• @AnyThread

Die Build-Tools verarbeiten @MainThread und @UiThread-Anmerkungen als austauschbar, sodass Sie @UiThread aufrufen können von @MainThread-Methoden und umgekehrt. Es ist jedoch möglich, dass eine Benutzeroberfläche im Fall von System-Apps mit mehreren Ansichten vom Hauptthread abweichen. in verschiedenen Threads beschäftigt. Daher sollten Sie Methoden annotieren, die mit der Ansichtshierarchie einer App verknüpft sind. mit @UiThread und annotieren nur Methoden, die dem Lebenszyklus einer App mit @MainThread.

Wenn für alle Methoden in einer Klasse die gleichen Threading-Anforderungen gelten, können Sie einen einzelnen Thread hinzufügen. an die Klasse übergeben, um zu überprüfen, ob alle Methoden in der Klasse vom gleichen Diskussions-Thread.

Thread-Annotationen werden häufig verwendet, um zu validieren, dass Methoden oder Klassen mit Annotationen @WorkerThread werden nur aus einem entsprechenden Hintergrundthread aufgerufen.

Anmerkungen zur Wertbeschränkung

Verwenden Sie die @IntRange, @FloatRange und @Size-Anmerkungen für die Werte übergebener Parameter validieren. @IntRange und @FloatRange sind besonders nützlich, wenn sie auf Parameter angewendet werden, bei denen Nutzer wahrscheinlich einen falschen Bereich sehen.

Mit der Annotation @IntRange wird validiert, ob der Parameter „Ganzzahl“ oder „long“ angegeben ist. Wert liegt innerhalb eines angegebenen Bereichs. Im folgenden Beispiel wird angegeben, dass die alpha Parameter muss einen ganzzahligen Wert zwischen 0 und 255 enthalten:

Kotlin

fun setAlpha(@IntRange(from = 0, to = 255) alpha: Int) { ... }

Java

public void setAlpha(@IntRange(from=0,to=255) int alpha) { ... }

Die Anmerkung @FloatRange prüft, ob ein Gleitkomma- oder Double-Parameter vorhanden ist Wert liegt innerhalb eines angegebenen Bereichs von Gleitkommawerten. Im folgenden Beispiel sehen Sie, Der Parameter alpha muss eine Gleitkommazahl zwischen 0,0 und 1,0 enthalten:

Kotlin

fun setAlpha(@FloatRange(from = 0.0, to = 1.0) alpha: Float) {...}

Java

public void setAlpha(@FloatRange(from=0.0, to=1.0) float alpha) {...}

Die Anmerkung @Size prüft die Größe einer Sammlung oder Array oder die Länge einer Zeichenfolge. Mit der Annotation @Size lässt sich prüfen, die folgenden Eigenschaften bieten:

• Mindestgröße, z. B. @Size(min=2)
• Maximale Größe, z. B. @Size(max=2)
• Genaue Größe, z. B. @Size(2)
• Eine Zahl, deren Größe ein Vielfaches sein muss, z. B. @Size(multiple=2)

Beispiel: @Size(min=1) prüft, ob eine Sammlung nicht leer ist, und @Size(3) bestätigt, dass ein Array genau drei Werte enthält.

Im folgenden Beispiel sehen Sie, Das Array location muss mindestens ein Element enthalten:

Kotlin

fun getLocation(button: View, @Size(min=1) location: IntArray) {
    button.getLocationOnScreen(location)
}

Java

void getLocation(View button, @Size(min=1) int[] location) {
    button.getLocationOnScreen(location);
}

Berechtigungsanmerkungen

@RequiresPermission verwenden Annotation, um die Berechtigungen des Aufrufers einer Methode zu validieren. Um nach einer einzelnen Berechtigung zu suchen aus einer Liste gültiger Berechtigungen mit dem Attribut anyOf. Um nach einer Reihe von verwenden Sie das Attribut allOf. Im folgenden Beispiel wird die setWallpaper(), um anzugeben, dass der Aufrufer der Methode permission.SET_WALLPAPERS-Berechtigung:

Kotlin

@RequiresPermission(Manifest.permission.SET_WALLPAPER)
@Throws(IOException::class)
abstract fun setWallpaper(bitmap: Bitmap)

Java

@RequiresPermission(Manifest.permission.SET_WALLPAPER)
public abstract void setWallpaper(Bitmap bitmap) throws IOException;

Im folgenden Beispiel muss die Methode copyImageFile() aufgerufen werden für Lesezugriff auf externen Speicher und Lesezugriff auf den Standort Metadaten im kopierten Bild:

Kotlin

@RequiresPermission(allOf = [
    Manifest.permission.READ_EXTERNAL_STORAGE,
    Manifest.permission.ACCESS_MEDIA_LOCATION
])
fun copyImageFile(dest: String, source: String) {
    ...
}

Java

@RequiresPermission(allOf = {
    Manifest.permission.READ_EXTERNAL_STORAGE,
    Manifest.permission.ACCESS_MEDIA_LOCATION})
public static final void copyImageFile(String dest, String source) {
    //...
}

Legen Sie für Berechtigungen für Intents die Berechtigungsanforderung in das Stringfeld, das die Name der Intent-Aktion:

Kotlin

@RequiresPermission(android.Manifest.permission.BLUETOOTH)
const val ACTION_REQUEST_DISCOVERABLE = "android.bluetooth.adapter.action.REQUEST_DISCOVERABLE"

Java

@RequiresPermission(android.Manifest.permission.BLUETOOTH)
public static final String ACTION_REQUEST_DISCOVERABLE =
            "android.bluetooth.adapter.action.REQUEST_DISCOVERABLE";

Für Berechtigungen bei Contentanbietern, die separate Berechtigungen für Lese- und Schreibvorgänge benötigen Zugriff haben, fassen Sie jede Berechtigungsanforderung in einem @RequiresPermission.Read zusammen. oder @RequiresPermission.Write Anmerkung:

Kotlin

@RequiresPermission.Read(RequiresPermission(READ_HISTORY_BOOKMARKS))
@RequiresPermission.Write(RequiresPermission(WRITE_HISTORY_BOOKMARKS))
val BOOKMARKS_URI = Uri.parse("content://browser/bookmarks")

Java

@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 von dem spezifischen Wert abhängt, der für den Parameter einer Methode angegeben wurde, verwenden Sie @RequiresPermission für den Parameter selbst, ohne die spezifischen Berechtigungen aufzulisten. Beispiel: startActivity(Intent) verwendet eine indirekte Berechtigung für den Intent, der an die Methode übergeben wird:

Kotlin

abstract fun startActivity(@RequiresPermission intent: Intent, bundle: Bundle?)

Java

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, -Argument, das an die Methode übergeben wurde, enthält beliebige @RequiresPermission-Annotationen. Anschließend alle vorhandenen Anmerkungen aus dem -Parameter für die Methode selbst zu erzwingen. Im Im Beispiel startActivity(Intent) verursachen Anmerkungen in der Klasse Intent die entsprechenden Warnungen. bei ungültiger Verwendung von startActivity(Intent), wenn ein Intent ohne das Berechtigungen an die Methode übergeben werden, wie in Abbildung 1 dargestellt.

Abbildung 1: Die von einem indirekten Berechtigungsannotation in der Methode startActivity(Intent)

Die Build-Tools generieren die Warnung für startActivity(Intent) aus der Annotation. für den entsprechenden Intent-Aktionsnamen in der Klasse Intent:

Kotlin

@RequiresPermission(Manifest.permission.CALL_PHONE)
const val ACTION_CALL = "android.intent.action.CALL"

Java

@RequiresPermission(Manifest.permission.CALL_PHONE)
public static final String ACTION_CALL = "android.intent.action.CALL";

Bei Bedarf können Sie @RequiresPermission durch @RequiresPermission.Read oder @RequiresPermission.Write beim Annotieren -Parameter einer Methode. Für indirekte Berechtigungen sollte @RequiresPermission jedoch dürfen nicht in Verbindung mit den Lese- oder Schreibberechtigungen verwendet werden.

Anmerkungen zu Rückgabewerten

Mit der Anmerkung @CheckResult können Sie überprüfen, ob das Ergebnis oder der Rückgabewert einer Methode tatsächlich verwendet wird. Anstatt jedes Mal annotieren, nicht-void-Methode mit @CheckResult, fügen Sie die Anmerkung hinzu, um die Ergebnisse der potenziell verwirrenden Methoden.

Neue Java-Entwickler glauben oft fälschlicherweise, <String>.trim() entfernt Leerzeichen aus dem ursprünglichen String. Anmerkungen Die Methode mit den Flags @CheckResult verwendet <String>.trim() bei denen der Aufrufer nichts mit dem Rückgabewert der Methode macht.

Im folgenden Beispiel wird checkPermissions() annotiert , um zu überprüfen, ob der Rückgabewert der Methode bezeichnet wird. Er nennt auch die enforcePermission(). -Methode als Methode, die dem Entwickler als Ersatz vorgeschlagen werden soll:

Kotlin

@CheckResult(suggest = "#enforcePermission(String,int,int,String)")
abstract fun checkPermission(permission: String, pid: Int, uid: Int): Int

Java

@CheckResult(suggest="#enforcePermission(String,int,int,String)")
public abstract int checkPermission(@NonNull String permission, int pid, int uid);

CallSuper-Anmerkungen

Mit der Anmerkung @CallSuper können Sie Validieren, dass eine Überschreibungsmethode die Superimplementierung der Methode aufruft

Die folgenden In diesem Beispiel wird die Methode onCreate() annotiert, damit alle Überschreibungsmethoden Implementierungen rufen super.onCreate() auf:

Kotlin

@CallSuper
override fun onCreate(savedInstanceState: Bundle?) {
}

Java

@CallSuper
protected void onCreate(Bundle savedInstanceState) {
}

Typedef-Anmerkungen

Mit Typedef-Anmerkungen wird überprüft, ob ein bestimmter Parameter, oder -Feld auf einen bestimmten Satz von Konstanten verweist. Sie ermöglichen auch die Codevervollständigung, die zulässigen Konstanten bieten.

Verwenden Sie die @IntDef- und @StringDef Annotationen zum Erstellen von Enum-Annotationen von Ganzzahl- und Stringsätzen zur Validierung anderer die verschiedenen Arten von Codeverweisen.

Typedef-Annotationen verwenden @interface, um den neuen Enum-Annotationstyp zu deklarieren. Die Annotationen @IntDef und @StringDef zusammen mit @Retention, kommentieren die neue Anmerkung und sind zum Definieren des Aufzählungstyp. Die Annotation @Retention(RetentionPolicy.SOURCE) teilt dem Compiler mit die aufgezählten Annotationsdaten nicht in der Datei .class zu speichern.

Das folgende Beispiel zeigt die Schritte zum Erstellen einer Annotation, die prüft, ob ein übergebener Wert als Methodenparameter auf eine der definierten Konstanten verweist:

Kotlin

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

}

Java

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);
}

Wenn Sie diesen Code erstellen, wird eine Warnung generiert, wenn der mode-Parameter die auf eine der definierten Konstanten (NAVIGATION_MODE_STANDARD, NAVIGATION_MODE_LIST oder NAVIGATION_MODE_TABS).

Kombinieren Sie @IntDef und @IntRange, um anzuzeigen, dass ein Ganzzahl kann entweder ein bestimmter Satz von Konstanten oder ein Wert innerhalb eines Bereichs sein.

Kombinieren von Konstanten mit Flags aktivieren

Wenn Nutzer die zulässigen Konstanten mit einem Flag kombinieren können (z. B. |, &, ^ usw.), können Sie eine Anmerkung mit einem flag-Attribut verwenden, um zu prüfen, ob ein Parameter oder Rückgabewert auf ein gültiges Muster verweist.

Im folgenden Beispiel wird die Annotation DisplayOptions mit einer Liste gültiger DISPLAY_-Konstanten:

Kotlin

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
...

Java

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 der Rückgabewert nicht auf ein gültiges Muster verweist.

Anmerkung beibehalten

Das @Keep -Annotation stellt sicher, dass eine annotierte Klasse oder Methode nicht entfernt wird, bei der Build-Erstellung minimiert werden. Diese Anmerkung ist normalerweise zu Methoden und Klassen hinzugefügt werden, auf die durch Reflexion zugegriffen wird, um zu verhindern, dass der Compiler nicht genutzt wird.

Achtung : Die Klassen und Methoden, die Sie annotieren mit @Keep werden immer im APK Ihrer App angezeigt, auch wenn Sie auf diese Klassen und Methoden innerhalb der App-Logik verweisen.

Um die Größe Ihrer App klein zu halten, überlegen Sie, ob es notwendig ist, jede @Keep-Anmerkung in Ihrer App. Wenn Sie Reflexion nutzen, auf eine annotierte Klasse oder Methode zugreifen, -if in Ihren ProGuard-Regeln, wobei die Klasse angegeben wird das die Reflexion auslöst.

Weitere Informationen dazu, wie Sie Ihren Code komprimieren und angeben, welcher Code nicht entfernt werden soll, Siehe App verkleinern, verschleiern und optimieren.

Anmerkungen zur Sichtbarkeit von Code

Verwenden Sie die folgenden Annotationen, um die Sichtbarkeit bestimmter Code-Abschnitte anzugeben, z. B. Methoden, Klassen, Feldern oder Paketen.

Code für Tests sichtbar machen

Die @VisibleForTesting -Anmerkung zeigt an, dass eine annotierte Methode sichtbarer ist als dies normalerweise erforderlich ist, -Methode testbar ist. Diese Annotation hat ein optionales otherwise-Argument, mit dem Sie die Sichtbarkeit der Methode angeben, wenn sie nicht sichtbar wäre. für Tests. Lint verwendet das Argument otherwise, um die gewünschte Sichtbarkeit zu erzwingen.

Im folgenden Beispiel ist myMethod() normalerweise private, ist aber package-private für Tests. Mit der VisibleForTesting.PRIVATE kennzeichen, zeigt Lint eine Meldung an, wenn diese Methode von außerhalb des Kontext, der durch private-Zugriff zulässig ist, z. B. von einer anderen Kompilierungseinheit.

Kotlin

@VisibleForTesting(otherwise = VisibleForTesting.PRIVATE)
fun myMethod() {
    ...
}

Java

@VisibleForTesting(otherwise = VisibleForTesting.PRIVATE)
void myMethod() { ... }

Sie können auch @VisibleForTesting(otherwise = VisibleForTesting.NONE) angeben. um anzuzeigen, dass eine Methode nur zu Testzwecken existiert. Dieses Formular entspricht @RestrictTo(TESTS) Beide führen die gleiche Lint-Prüfung durch.

API einschränken

Das @RestrictTo -Anmerkung zeigt an, dass der Zugriff auf die annotierte API (Paket, Klasse oder Methode) eingeschränkt ist, wie folgt:

Abgeleitete Klassen

Verwenden Sie zum Einschränken das Anmerkungsformat @RestrictTo(RestrictTo.Scope.SUBCLASSES) API-Zugriff nur auf abgeleitete Klassen.

Nur Klassen, die die annotierte Klasse erweitern, können auf diese API zugreifen. Java Der protected-Modifikator ist nicht einschränkend genug, da er Zugriff ermöglicht aus nicht in Beziehung stehenden Klassen im selben Paket. Es gibt auch Fälle, in denen Sie public-Methode für zukünftige Flexibilität, da Sie keine zuvor erstellten Daten protected und die überschriebene Methode public, Sie möchten jedoch weisen darauf hin, dass die Klasse nur für Verwendung innerhalb der Klasse oder nur für abgeleitete Klassen bestimmt ist.

Bibliotheken

Verwenden Sie das Anmerkungsformular @RestrictTo(RestrictTo.Scope.LIBRARY_GROUP_PREFIX), um den API-Zugriff auf Ihre Bibliotheken zu beschränken.

Nur Ihr Bibliothekscode kann auf die annotierte API zugreifen. So können Sie Ihren Code nicht nur Pakethierarchie erstellen, aber auch in einer Gruppe verwandter Bibliotheken. Diese Option ist bereits für das Jetpack verfügbar Bibliotheken mit viel Implementierungscode enthalten, der nicht für die externe Verwendung gedacht ist, muss public sein, um sie für die verschiedenen komplementären Jetpack-Bibliotheken freizugeben.

Testen

Verwenden Sie das Anmerkungsformat @RestrictTo(RestrictTo.Scope.TESTS), um andere Entwickelnden auf Ihre Test-APIs zugreifen können.

Nur Testcode kann auf die annotierte API zugreifen. Das verhindert, dass andere Entwickler APIs nur zu Testzwecken zu Entwicklungszwecken zu verwenden.