编程中的魔法 —— 它是什么，为什么魔法数字危险及替代

编程中的魔法是什么？

魔法（magic）—— 是源代码中任何没有领域额外知识其含义就不明显的值。这个术语在社区中已经确立：如果开发者看到一个数字却不明白它从何而来 —— 这就是魔法。

魔法有几种类型：数字型（magic numbers）、字符串型（magic strings）、布尔型（magic flags）和配置型（本应在设置中的硬编码参数）。所有四种类型都有一个共同的问题：当需求发生变化时，开发者必须找到所有使用该值的地方并手动替换它们。哪怕错过一个出现位置也会导致错误。

根据 JetBrains Code Quality Survey (2025) 的报告，73% 的开发者认为魔法数字是低质量代码的指标，而 41% 承认他们自己偶尔也会留下魔法数字。主要原因 —— 匆忙：“我稍后再放常量” —— 但稍后永远不会到来，一个月后数字 0.85 仍然留在方法体内没有解释。

关键规则：每个字面量值（除了 0、1、true、false 和空字符串）都应该被提取到命名常量中。例外情况：计数器递增（i + 1）、数学零（检查是否为 0）和累加器的初始值。所有其他值 —— 都是命名的候选。

Magic numbers 及其危险性

Magic number —— 是一个数字字面量，其值从上下文中不明显。经典例子：负责超时的代码中的 86400。开发者看到这个数字，必须猜出这是一天中的秒数。如果他弄错了，写了 84600 —— 这个错误将很难发现，因为超时会提前 18 分钟触发。

为什么魔法数字危险：首先，它们损害可读性。数字 1024 可能表示千字节的大小、分页阈值或元素的最大数量。没有上下文 —— 它只是一个数字。其次，它们造成重复：如果 1024 在五个地方被使用，当阈值改为 2048 时，开发者必须找到全部五个并替换。如果漏掉一个地方 —— 系统运行不正确，但没有明显错误。

魔法数字示例：之前和之后

// 之前 —— 纯粹形式的魔法
fun calculateTimeout(base: Int): Int {
    return base * 3 + 5000
}

// 之后 —— 值被常量替换
private const val RETRY_MULTIPLIER = 3
private const val BASE_TIMEOUT_MS = 5000

fun calculateTimeout(base: Int): Int {
    return base * RETRY_MULTIPLIER + BASE_TIMEOUT_MS
}

第三个危险 —— 无法测试。如果阈值作为字面量嵌入在代码中，测试无法覆盖它来检查边界条件。提取到 companion object 或配置文件中的常量使代码可测试：测试使用另一个值并检查系统在边界处的行为。

养成习惯：每次写入不是 0、1、100 或 2 的数字时 —— 停下来想想是否值得将其提取到常量中。如果数字与业务逻辑相关（限制、阈值、超时、大小） —— 务必提取。如果数字是数学常量（pi、e） —— 使用标准库（Math.PI、Math.E）。

魔法字符串和路径

Magic strings —— 嵌入代码中而未提取到常量或资源的字符串字面量。典型例子：端点的 URL、SharedPreferences 键的名称、Intent Actions、bundle keys、文件名和 SQL 查询。

魔法字符串的危险在于编译阶段缺少检查。字符串 “user_prefs” 中的拼写错误直到运行时才会被发现。如果该字符串在十个地方被使用，而开发者在其中一个地方写了 “user_pref”（少了 s）—— 应用程序不会崩溃，但数据不会保存。这样的错误可能在生产环境中存在数月，因为它不会导致崩溃。

对于 Android 项目，魔法字符串应该被提取到资源（strings.xml、arrays.xml）或 companion object 中的常量。对于 iOS —— 提取到字符串资源（Localizable.strings）或枚举常量。对于后端 —— 提取到配置文件（.env、application.properties）。任何密钥、URL 或路径都不应以字符串字面量的形式出现在代码中。

// 之前 —— 整个类中的魔法字符串
let prefs = UserDefaults.standard
prefs.set(token, forKey: "auth_token")
prefs.set(userId, forKey: "current_user_id")

// 之后 —— 字符串被提取到枚举
enum PrefKeys: String {
    case authToken = "auth_token"
    case currentUserId = "current_user_id"
}

prefs.set(token, forKey: PrefKeys.authToken.rawValue)
prefs.set(userId, forKey: PrefKeys.currentUserId.rawValue)

特别注意重复的字符串。如果同一个密钥 “user_settings” 出现在三个文件中 —— 99% 的可能性迟早会在其中一个中出现拼写错误。提取到枚举或常量可确保所有引用使用相同的值。

Magic flags 和布尔参数

Magic flags —— 布尔参数，其值从调用上下文中不明显。经典反模式：向方法传递 true 或 false，而不解释这个标志具体启用或禁用什么。

示例：userDao.fetch(includeDeleted = false)。开发者看到 false，不明白这是 “不包括已删除” 还是 “不包括活动的”。一个月后，false 变成了 true，结果中开始出现已删除的记录。这个错误只会在生产环境中被发现。

解决方案 —— 用枚举或密封类替换布尔标志。使用 UserFilter.includeDeleted 或 UserFilter.activeOnly 代替 Boolean 参数。这样代码自己文档化意图，IDE 在自动完成时提示可用选项。

如果布尔标志通过多个层传递 —— 这是抽象错误的另一个信号。不要将标志拖过三个调用层级，而是考虑筛选器的选择是否应该在上层做出并作为准备好的配置传递。代码中的布尔标志越少 —— 魔法就越少。

引入一条规则：没有布尔参数可以在没有命名参数的情况下传递给方法（如果语言支持命名参数）。在 Kotlin 和 Swift 中，这个要求自动满足。在 Java 中，使用 Builder 或枚举常量代替 true/false。

魔法检测工具

魔法值的搜索由配置为在意外位置识别字面量的静态分析器自动化。每种语言都提供自己的工具，带有可配置的例外。

配置例外至关重要 —— 没有它，分析器会在每次递增（-1、+1）和数学零时发出警告。对于 SonarQube，允许的数字列表：0、1、-1、2（用于加倍）、100（百分比）、60 和 24（时间）。对于所有其他值 —— 要求带有 public static final（Java）或 const val（Kotlin）修饰符的命名常量。

在 CI 级别进行分析时，添加一个将魔法检查作为警告的步骤，但不阻止构建。首次运行将在遗留代码中显示数百个警告。逐步地，逐个任务地将代码迁移到常量，并提高质量阈值。当魔法数字的数量少于 10 时 —— 将该规则作为构建错误启用。

重构：用常量替代魔法

魔法的重构 —— 最安全的操作之一：用常量替换字面量不会改变代码的行为。尽管如此，方法必须是系统性的，以免遗漏隐藏的依赖关系（例如，如果同一个魔法数字在不相关的上下文中使用，但巧合地具有相同的值）。

逐步过程：找到魔法值的所有出现位置，理解每个的上下文，分配到不同的常量（即使值相同 —— 上下文不同，常量的名称也应该不同），用常量替换字面量，通过测试验证。第 2 步的错误 —— 最常见：两个不同的概念（以毫秒为单位的超时和以字节为单位的阈值）可能在数值上相同（例如 5000），但在语义上是不同的量，不能合并到一个常量中。

// 之前 —— 不同上下文中的相同数字
public class Config {
    public void setupCache() {
        cache.setMaxSize(5000); // 5 MB
    }
    public void setupTimeout() {
        client.setReadTimeout(5000); // 5 秒
    }
}

// 之后 —— 不同上下文的——不同常量
public class Config {
    private static final int CACHE_MAX_SIZE_MB = 5;
    private static final int READ_TIMEOUT_SECONDS = 5;

    public void setupCache() {
        cache.setMaxSize(CACHE_MAX_SIZE_MB * 1024 * 1024);
    }
    public void setupTimeout() {
        client.setReadTimeout(
            READ_TIMEOUT_SECONDS * 1000
        );
    }
}

对于新代码，规则很简单：每个字面量（除了 0、1、-1、true、false、null 和空字符串）都被提取到常量中。例外情况：数学常量（始终通过标准库）、测试数据（字面量可以留在测试中，但要有解释性变量名）和用于递增的边界值（循环中的 i + 1 —— 正常）。