Aufbewahrungsregeln

Wenn Sie die App-Optimierung aktivieren mit den Standardeinstellungen, führt R8 umfangreiche Optimierungen durch, um die Leistungssteigerung zu maximieren. R8 nimmt erhebliche Änderungen am Code vor, einschließlich des Umbenennens, Verschiebens und Entfernens von Klassen, Feldern und Methoden. Wenn Sie feststellen, dass diese Änderungen Fehler verursachen, müssen Sie angeben, welche Teile des Codes von R8 nicht geändert werden sollen. Dazu deklarieren Sie diese in Keep-Regeln.

Häufige Szenarien, in denen Keep-Regeln erforderlich sind

R8 identifiziert und behält alle direkten Aufrufe in Ihrem Code bei. R8 kann jedoch keine indirekten Codeverwendungen erkennen. Dadurch kann es vorkommen, dass Code entfernt wird, den Ihre App benötigt, was zu Abstürzen führt. Mit Keep-Regeln können Sie R8 anweisen, solchen indirekt verwendeten Code beizubehalten. Im Folgenden sind einige häufige Situationen aufgeführt, in denen Sie wahrscheinlich Keep-Regeln benötigen:

• Code, auf den per Reflektion zugegriffen wird: R8 kann nicht erkennen, wann auf Klassen, Felder oder Methoden per Reflektion zugegriffen wird. R8 kann beispielsweise keine Methode identifizieren, die mit Class.getDeclaredMethod() nach ihrem Namen gesucht wird, oder eine Annotation, die mit Class.getAnnotation() abgerufen wird. In diesen Fällen kann R8 diese Methoden und Annotationen umbenennen oder vollständig entfernen, was zu einer ClassNotFoundException oder einer NoSuchMethodException zur Laufzeit führt.
• Code, der über die Java Native Interface (JNI) aufgerufen wird: Wenn nativer Code (C oder C++) eine Java- oder Kotlin-Methode aufruft oder Java- oder Kotlin-Code C++-Code mit JNI aufruft, basiert der Aufruf auf einer dynamischen Stringsuche nach dem Namen der Methode. R8 kann den dynamischen String-basierten Methodenaufruf nicht erkennen. Daher können die Optimierungen den Code beschädigen.

Dies ist keine vollständige Liste der Szenarien, in denen Keep-Regeln erforderlich sind. Diese Szenarien decken jedoch die meisten Fälle ab, in denen Sie Keep-Regeln benötigen.

Keep-Regeln zur App hinzufügen

Die Konfiguration der Keep-Regeln hängt von der verwendeten AGP-Version ab.

Größere Apps haben in der Regel Code in mehreren Bibliotheksmodulen. In solchen Fällen ist es oft besser, die Keep-Regeln neben dem Code zu platzieren, auf den sie angewendet werden, und zwar im jeweiligen Bibliotheksmodul. Der entscheidende Unterschied bei der Verwaltung von Keep-Regeln für Bibliotheken besteht darin, wie Sie diese Regeln in der Datei des Bibliotheksmoduls build.gradle.kts (oder build.gradle) deklarieren. Weitere Informationen finden Sie unter Optimierung für Bibliotheks autoren.

Für AGP-Versionen 9.3 und höher

Fügen Sie die Regeln in einer Datei mit dem Suffix .keep im src/<variant>/keepRules Verzeichnis hinzu. Beispiel: src/main/keepRules/custom-rules.keep. Wenn Sie die aktualisierte DSL für AGP 9.3 und höher verwenden, werden sowohl Code als auch Ressourcen optimiert. Sie müssen die Standard-Android-Keep-Regeldatei (proguard-android-optimize.txt) nicht explizit definieren, da sie standardmäßig enthalten ist, es sei denn, sie wird explizit ausgelassen.

android {
    buildTypes {
        release {
            optimization {
                enable = true // Enables code and resource optimizations.
            }
        }
    }
}

android {
    buildTypes {
        release {
            optimization {
                enable = true // Enables code and resource optimizations.
            }
        }
    }
}

Standard-Keep-Regeln für die Android-Plattform auslassen (erweitert)

AGP bietet eine Reihe von Standardregeln für die Android-Plattform. Wenn Sie diese Regeln aus der Konfiguration Ihres Projekts auslassen und alle Keep-Regeln selbst verwalten möchten, setzen Sie optimization.keepRules.includeDefault auf false.

android {
    buildTypes {
        release {
            optimization {
                enable = true // Enables code and resource optimizations.
                keepRules {
                    includeDefault = false // The file with optimization
                    // rules for the Android platform is included by
                    // default. To omit this file, set this option to false.
                }
            }
        }
    }
}

android {
    buildTypes {
        release {
            optimization {
                enable = true // Enables code and resource optimizations.
                keepRules {
                    includeDefault = false // The file with optimization
                    // rules for the Android platform is included by
                    // default. To omit this file, set this option to false.
                }
            }
        }
    }
}

Legacy-DSL für AGP-Versionen unter 9.3

Fügen Sie die Regeln in einer Datei proguard-rules.pro im Stammverzeichnis des App-Moduls hinzu. Die Datei ist möglicherweise bereits vorhanden. Wenn nicht, erstellen Sie sie. Damit die Regeln in der Datei angewendet werden, müssen Sie die Datei in der Datei auf Modulebene build.gradle.kts (oder build.gradle) deklarieren.

Standardmäßig enthält die Build-Datei auch die Datei proguard-android-optimize.txt. Diese Datei enthält Regeln, die für die meisten Android-Projekte erforderlich sind. Sie sollte daher in der Build-Datei bleiben. Diese Datei basiert auf der Datei proguard-common.txt und enthält dieselben Inhalte.

android {
    buildTypes {
        release {
            isMinifyEnabled = true
            isShrinkResources = true

            proguardFiles(
                // Default file with default optimization rules.
                getDefaultProguardFile("proguard-android-optimize.txt"),
                ...
            )
        }
    }
}

android {
    buildTypes {
        release {
            minifyEnabled = true
            shrinkResources = true

            // Default file with default optimization rules.
            proguardFiles getDefaultProguardFile('proguard-android-optimize.txt')
            ...
        }
    }
}

Keep-Regel hinzufügen

Wenn Sie Keep-Regeln hinzufügen, können Sie globale Optionen einbeziehen und eigene Keep-Regeln definieren.

• Globale Optionen: Globale Optionen sind allgemeine Anweisungen, die sich auf die Funktionsweise von R8 für die gesamte Codebasis auswirken. Weitere Informationen finden Sie unter Globale Optionen.

• Keep-Regeln: Keep-Regeln müssen sorgfältig entworfen werden, damit Sie das richtige Gleichgewicht zwischen maximaler Codeoptimierung und dem Vermeiden unbeabsichtigter Fehler in Ihrer App finden. Informationen zum Schreiben von Keep-Regeln finden Sie unter Keep-Regeln hinzufügen.

Keep-Regeln für Bibliotheksautoren

Nachdem Sie sich mit den globalen Optionen und der Syntax für Keep-Regeln vertraut gemacht haben, finden Sie unter Optimierung für Bibliotheksautoren weitere Informationen.