魔术数字是指未解释、无来源、突然出现且反复复用的字面量，如if (status == 3)，导致修改困难、易出错、理解成本高；应按语义位置、上下文命名、类型安全（优先枚举）三原则替换为常量，并聚焦http码、业务规则值、协议字符串等高风险项。
什么是魔术数字，为什么它让后续修改变痛苦
魔术数字不是指真在代码里写42这种玄学值，而是指那些没解释、没来源、突然出现又反复复用的字面量。比如if (status == 3)、Thread.sleep(5000)、new BigDecimal("1.25")——没人知道3代表什么状态，5000是超时还是重试间隔，"1.25"是不是税率。
这类写法最直接的后果是：改一个地方，得全局搜3，但不敢全替，怕把别的3（比如循环次数）也改了；加个新状态？得翻文档、问老同事、甚至看日志猜。
怎么替换成常量：位置、命名和作用域要一起考虑
替换不是简单地“找个地方定义public static final int STATUS_PAID = 3”就完事。关键在三点：
-
STATUS_PAID必须定义在语义归属清晰的位置：如果是订单状态，就该在OrderStatus类里，而不是塞进Constants工具类里堆一堆 unrelated 常量 - 命名必须带上下文：
PAYED不如STATUS_PAID，TAX_RATE不如DEFAULT_VAT_RATE_PERCENTAGE（哪怕长点，IDE能自动补全） - 类型优先选枚举或专用类，而非
int/String：状态用enum OrderStatus { PAID, PENDING, CANCELLED }，比一堆int常量更安全，还能自带方法和文档
别把所有常量都扔进一个GlobalConstants里——那只是把魔术数字从代码里挪到了另一个文件，没解决理解成本问题。
哪些值必须立刻抽成常量，哪些可以暂时保留
不是所有字面量都要改，重点盯住三类高风险值：
立即学习“Java免费学习笔记（深入）”；
-
HTTP状态码、数据库返回码、第三方接口约定值：比如response.getStatus() == 401→ 必须换成HttpServletResponse.SC_UNAUTHORIZED或自定义AuthErrorCode.UNAUTHORIZED - 业务规则强相关的数值：税率
0.13、默认分页大小20、重试次数3——这些一旦变，大概率要改多处，且容易漏 - 字符串字面量中带协议/路径/格式的：如
"application/json"、"yyyy-MM-dd HH:mm:ss"、"user:id:{0}"——它们散落在日志、注解、配置拼接里，搜起来费劲，还容易拼错
像for (int i = 0; i 里的<code>10，或者Math.max(a, 5)里的5（明显是临时阈值），只要没被复用、没业务含义，不用硬套常量。
IDE能帮上忙，但别依赖它自动替换
IntelliJ 的「Replace Magic Number with Constant」功能确实能一键生成private static final int XXX = 123，但它不判断：
- 这个
123是否真的该是int？比如BigDecimal构造用"123"字符串才安全，用123整数会丢失精度 - 它生成的常量默认是
private，但可能需要被其他类读取——得手动调访问修饰符，或移到合适类里 - 它不会帮你合并语义相同的值：比如
timeout = 3000和Thread.sleep(3000)都用了3000，但一个是毫秒超时，一个是线程休眠，不能共用一个TIMEOUT_MS常量
真正省时间的做法是：写代码时，**看到第二个相同字面量出现，就停一下，把它提成常量**。不是等代码写完再批量扫——那时你已经忘了当初为啥写这个7了。
有些团队会强制要求 PR 里禁止新增未命名的数字/字符串字面量，靠 CI 检查。这招有效，但前提是大家清楚“为什么不能有”，而不是只当一条死规矩应付。
