第3章：ProGuard规则文件结构 — 核心指令语法与作用域
3.1 概述
ProGuard 规则文件（通常名为 proguard-rules.pro）是控制代码混淆、压缩、优化的核心配置。本章逐一剖析最常用的四条指令：-keep、-dontwarn、-keepattributes、-keepclassmembers，并阐明其语法结构、作用域及实际影响。
⚠ 学习前置： 理解 Java 字节码结构（类、字段、方法、注解）有助于精准掌握指令作用域。所有指令均可叠加使用，但顺序会影响匹配优先级。
3.2 指令全景与作用域对比
| 指令 | 核心作用 | 作用目标 | 常见误用 |
|---|---|---|---|
-keep | 保留指定类/成员不被混淆、压缩或移除 | 类、字段、方法 | 忘记指定 class 通配符导致匹配失败 |
-dontwarn | 抑制特定缺失引用或警告 | 类、包名、通配符 | 不加限定地全局忽略，可能隐藏错误 |
-keepattributes | 保留字节码元数据（如注解、签名） | 属性名（如 *Annotation*） | 未保留 Signature 导致泛型擦除 |
-keepclassmembers | 仅保留类的成员（字段/方法），不保留类本身 | 类内部的字段、方法 | 误以为会自动保留类名 |
3.3 -keep 语法与作用域
-keep 是最常用的保留指令，格式为：
-keep [修饰符] class 类模式 {
成员过滤器
}关键修饰符：
public/protected/private：筛选访问级别*：匹配任意类或成员（通配符）extends/implements：限定继承或实现关系class中可使用**匹配任意包层级
示例：保留所有实现了 Serializable 的类和其全部成员
-keep class * implements java.io.Serializable {
*;
}
作用域陷阱： 若只写
-keep class com.example.MyClass（无成员过滤器），则仅保留类名本身，其字段和方法仍可能被混淆或删除。必须在花括号内显式声明 { *; } 或具体成员。
3.4 -dontwarn 抑制警告
当 ProGuard/R8 检测到缺失引用（如运行时不易出现的类）时，会输出警告并终止构建。-dontwarn 可跳过这些检查：
-dontwarn com.example.unused.**最佳实践：
- 务必使用包名或通配符限定范围，避免全局
-dontwarn - 仅压制运行时确实不会加载的类（如过时的依赖）
- 对于库中的可选依赖（如 Firebase 某些组件），逐个抑制
3.5 -keepattributes 保留元数据
混淆默认会移除大部分属性，导致反射、序列化、泛型等功能失效。常用属性包括：
| 属性名 | 用途 |
|---|---|
*Annotation* | 保留所有运行时可访问的注解 |
Signature | 保留泛型签名（如 List<String> 不被擦除） |
InnerClasses | 保留内部类与外部的关联 |
EnclosingMethod | 保留匿名类所属方法信息 |
Exceptions | 保留方法声明中的异常列表 |
常用配置组合：
-keepattributes *Annotation*, Signature, InnerClasses, EnclosingMethod
📦 实际案例： 使用 Gson 或 Retrofit 时，必须保留
Signature 属性，否则泛型类型将被擦除，导致反序列化失败。
3.6 -keepclassmembers 保留成员但不保留类
与 -keep 的区别：-keepclassmembers 只保护类内部的字段和方法，不保护类名。若类名被混淆，成员仍保留原名称：
-keepclassmembers class com.example.MyModel {
public <init>();
public void set*(*);
public * get*();
}适用场景：
- 保留数据模型的 getter/setter 以支持反射注入
- 保留 native 方法（配合
-keepclasseswithmembernames更安全） - 保留 Lambda 表达式或回调接口中的方法
3.7 作用域关系可视化（内联 SVG）
3.8 实现流程：编写和验证规则文件
- 定位文件： 在模块
app/proguard-rules.pro或build.gradle中通过proguardFiles引用。 - 逐指令编写： 先添加
-keep保护主线逻辑，再补充-keepattributes支持反射/序列化，最后用-dontwarn消除可靠警告。 - 构建并检查： 启用混淆后运行
./gradlew assembleRelease，查看build/outputs/mapping/release/mapping.txt确认类/成员是否被混淆。 - 调试常见错误： 若运行时报
ClassNotFoundException或NoSuchMethodException，说明-keep未覆盖到位。
🔧 性能提示： 过度使用
-keep 会导致 APK 体积增大，仅保留必需类。使用 -whyareyoukeeping 指令可分析某类为何被保留，帮助优化规则。
3.9 常见错误与规避
| 错误模式 | 现象 | 解决方案 |
|---|---|---|
| 漏写成员过滤器 | 类名保留但字段/方法被混淆 | 添加 { *; } 或列出具体方法 |
全局 -dontwarn | 构建通过但运行时 NoClassDefFoundError | 改为精确抑制 com.dependency.unused.** |
未保留 Signature | Gson/Retrofit 反序列化异常 | 加入 -keepattributes Signature |
| 混淆内部类导致资源 ID 错误 | R.class 内部类被混淆 | 使用 -keep class **.R$* { *; } |
| 混淆枚举类 | 枚举 values() 方法消失 | 通常 R8 自动处理，但可显式 -keepclassmembers enum * { *; } |