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

2026/7/30 13:17:47

用 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;即可——其余代码一行都不用改。

七、踩坑注意

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