@IntDef 替代 enum：Android 官方推荐的轻量常量方案

用 int 常量的零对象开销，换掉 enum 的"贵"------并在编译期保留一层类型安全检查。本文梳理 @IntDef 的核心价值、Java/Kotlin 双版本用法、一个可运行 Demo，以及几个容易踩的坑。
本篇为独立 Android 开发 Tips，与「十年车机性能优化系列」并列，可单独阅读。

一、为什么要在 Android 上慎用 enum

在 Android 里，每个 enum 常量都是一个对象实例 ：它不仅占堆内存，还会在 DEX 里生成额外的类结构、values() / valueOf() 等方法，直接推高包体积。

举个例子，一个只有 3 个值的 enum：

public enum WeekDay { SUNDAY, MONDAY, TUESDAY }

编译后等价于一个继承了 java.lang.Enum 的类，附带静态初始化块、数组和若干方法。在服务器/桌面端这微不足道，但在车载座舱、低端机这种内存和存储都紧张的场景，大量使用 enum 会积少成多。

也正因如此，Android 官方的 API 设计指南明确要求：在平台 API 中应优先使用 IntDef 而非 enum。

一句话：enum 提供强类型，但"贵"；@IntDef 几乎免费，只牺牲一点类型强度。

二、@IntDef 是什么 & 核心优势

@IntDef 来自 androidx.annotation，它不改变底层类型 ------变量本质还是 int 基本类型，只是用注解把"允许取哪些值"标注出来，让 Android Studio / Lint 在编译期给你标黄警告。

特性	@IntDef + static final int	enum
内存占用	小，本质是 int 常量	大，每个常量都是对象，有额外内存开销
DEX 文件大小	小，仅增加常量定义	大，会生成 Enum 相关的方法和对象
类型安全	编译时 IDE 警告，非强约束	强类型，编译时直接报错，完全安全
代码可读性	中等，需查看注解定义	高，枚举自带清晰的命名空间和语义
功能扩展	弱，仅能表示整数值	极强，可实现接口、包含方法、定义属性等

三、Java 版完整用法（三步）

1. 定义常量 + 创建注解

import androidx.annotation.IntDef;
import java.lang.annotation.Retention;
import java.lang.annotation.RetentionPolicy;

public class WeekDay {
    // 1. 定义常量（编译期常量）
    public static final int SUNDAY = 0;
    public static final int MONDAY = 1;
    public static final int TUESDAY = 2;

    // 2. 用 @IntDef 把常量集合起来，并声明为 SOURCE 保留
    @IntDef({SUNDAY, MONDAY, TUESDAY})
    @Retention(RetentionPolicy.SOURCE) // 仅源码期保留，不进字节码
    public @interface WeekDays {
    }
}

2. 用注解限制字段 / 参数 / 返回值

public class Demo {
    // 限制字段
    @WeekDays
    private int today = WeekDay.SUNDAY;

    // 限制方法参数
    public void setToday(@WeekDays int day) {
        this.today = day;
    }

    // 限制返回值
    @WeekDays
    public int getToday() {
        return today;
    }
}

这样，当你传入 WeekDay.WEDNESDAY（未定义常量）或随便写一个数字 setToday(99)，Android Studio 会标黄警告，实现编译期类型安全检查。

定义 static final int 常量

用 @IntDef 包成注解

标注到 参数/字段/返回值

IDE/Lint 编译期标黄警告

四、Kotlin 版完整用法

Kotlin 里常量要用 const val（编译期常量），否则无法写进 @IntDef 的 value。

import androidx.annotation.IntDef
import androidx.annotation.Retention
import androidx.annotation.RetentionPolicy

object WeekDay {
    const val SUNDAY = 0
    const val MONDAY = 1
    const val TUESDAY = 2
}

@Retention(RetentionPolicy.SOURCE)
@IntDef(WeekDay.SUNDAY, WeekDay.MONDAY, WeekDay.TUESDAY)
annotation class WeekDays

class Demo {
    @WeekDays
    private var today: Int = WeekDay.SUNDAY

    fun setToday(@WeekDays day: Int) {
        this.today = day
    }

    @WeekDays
    fun getToday(): Int = today
}

Kotlin 也有自己的 enum class，用法和 Java enum 一样"贵"。若只是为了限定取值集合，Kotlin + @IntDef 同样适用。

五、进阶：flag = true 支持位运算

当常量需要组合使用 （如 FLAG_READ | FLAG_WRITE），开启 flag = true：

@IntDef(flag = true, value = {FLAG_READ, FLAG_WRITE, FLAG_EXECUTE})
@Retention(RetentionPolicy.SOURCE)
public @interface FlagMode {}

// 使用
@FlagMode
private int mode = FLAG_READ | FLAG_WRITE;

public boolean hasFlag(@FlagMode int mode, int flag) {
    return (mode & flag) == flag; // 用位与判断是否包含某标志
}

开启 flag = true 后，Lint 允许"这些位任意组合"的值通过，只要每一位都来自定义集合即可。

六、完整可运行 Demo

下面是一份纯 Java、可直接 javac 运行 的 Demo。为保证脱离 Android 也能跑，我们把 @IntDef 在本地定义了一个同形状注解（生产环境直接换成 androidx.annotation.IntDef，用法完全一致）。

import java.lang.annotation.Retention;
import java.lang.annotation.RetentionPolicy;
import java.lang.annotation.Target;
import java.lang.annotation.ElementType;

// ------ 本地版 @IntDef（形状与 androidx.annotation.IntDef 一致，仅用于无 Android 依赖演示）------
@Retention(RetentionPolicy.SOURCE)
@Target({ElementType.FIELD, ElementType.METHOD, ElementType.PARAMETER})
@interface IntDef {
    int[] value() default {};
    boolean flag() default false;
}

public class IntDefDemo {

    // 1. 常量
    public static final int SUNDAY = 0;
    public static final int MONDAY = 1;
    public static final int TUESDAY = 2;

    // 2. 注解
    @IntDef({SUNDAY, MONDAY, TUESDAY})
    @Retention(RetentionPolicy.SOURCE)
    @interface WeekDays {}

    // 3. 使用
    @WeekDays
    private int today = SUNDAY;

    public void setToday(@WeekDays int day) {
        this.today = day;
    }

    @WeekDays
    public int getToday() {
        return today;
    }

    public static void main(String[] args) {
        IntDefDemo d = new IntDefDemo();
        d.setToday(IntDefDemo.MONDAY);
        System.out.println("今天是：" + d.getToday()); // 输出 1

        // 下面这行若取消注释，Android Studio / Lint 会标黄警告（编译仍能通过）：
        // d.setToday(99); // ⚠ 不在 {0,1,2} 集合内
    }
}

编译运行：

javac IntDefDemo.java
java IntDefDemo
# 输出：今天是：1

在真实 Android 项目中，把 IntDefDemo 里的本地 @IntDef 删掉，改为 import androidx.annotation.IntDef; 即可------其余代码一行都不用改。

七、踩坑注意

1. SOURCE 保留，运行时拿不到 ：@Retention(SOURCE) 意味着注解在编译后就被丢弃，不能靠反射读取它做运行时校验。这既是省开销的优点，也是"无法运行时兜底"的限制。
2. IDE 警告 ≠ 编译报错 ：@IntDef 是 Lint/IDE 的软约束 ，编译能通过。如果你的 CI 不跑 lint，错误的 int 值照样进包。要强制拦截，需在 CI 跑 ./gradlew lint 或写自定义 Lint 规则。
3. Kotlin 必须用 const val ：写在 companion object 里的普通 val 不是编译期常量，塞不进 @IntDef({...})，会直接编译报错。只有顶层的 const val 或 object 内的 const val 才行。
4. 漏写常量 = 漏检 ：@IntDef 的 value 数组里若漏了某个常量，那个常量就不在受检集合内，调用方传它不会报警告。增删常量时务必同步更新 value。
5. flag 组合仍可能越界 ：flag = true 只保证"每一位都来自集合"，不保证"组合后的值合法"。若某些组合业务上不允许，需要自己在代码里校验。
6. 别为了像 enum 而过度设计 ：@IntDef 只能表达整数值，无法携带数据或行为。当常量需要关联颜色、文案，或要实现抽象方法时，enum 才是更合适的选择------性能不是唯一维度。

小结

@IntDef 是 Android 上"用最小代价换类型安全"的标准做法：底层是 int、零对象开销、不增大 DEX，还能在写代码时拦下非法取值。绝大多数常量集合场景优先用它 ；只有当常量需要携带数据或有行为逻辑时，才值得为 enum 的"贵"买单。