PAYATHON 2026

如何要求 Java 方法仅接收常量或 string literal 参数?

技术老齐

结论

Java 的方法参数类型和内置注解都无法要求实参必须是字符串字面量或编译期常量。Kotlin 也没有这样的原生参数约束。

Java 可以通过 Error Prone 的 @CompileTimeConstant 在构建时检查,防止调用者把运行时数据拼进错误消息。前提是调用方的构建运行了 Error Prone。检查规则说明

字符串字面量与编译期常量有什么区别?

字符串字面量就是源码中的 "unrecognised potato shape"。编译期常量表达式的范围更广,还包括常量引用和常量之间的拼接:

final String MESSAGE = "unrecognised potato shape";

builder.andFail("unrecognised potato shape");
builder.andFail(MESSAGE);
builder.andFail("unrecognised " + "potato shape");

这些表达式的字符串值都能在编译期确定。方法调用则不属于 Java 的常量表达式,即使调用时用的全是字面量:

"unrecognised %s".formatted("potato shape")

final 本身也不代表编译期常量:

final String message = readMessageFromConfig();

这里的 message 不能重新赋值,但内容要到运行时才能确定。相关定义见 JLS 的常量表达式规则。

把方法声明写成 andFail(final String message),也只能禁止方法体给参数重新赋值,无法限制调用者如何生成字符串。

Java:使用 @CompileTimeConstant

在已有 builder 的 andFail 参数上添加注解即可:

import com.google.errorprone.annotations.CompileTimeConstant;

public interface FailureBuilder {
    RuntimeException andFail(@CompileTimeConstant String message);
}

启用 Error Prone 后,以下调用会分别通过检查或报错:

final String MESSAGE = "unrecognised potato shape";

builder.andFail("unrecognised potato shape"); // 允许
builder.andFail(MESSAGE);                     // 允许

// 以下假设 potatoShape 是运行时数据
builder.andFail("unrecognised shape: " + potatoShape); // 报错
builder.andFail("unrecognised shape: %s"
        .formatted(potatoShape));                    // 报错

原先设计的调用方式可以保留:

throw giveUp()
        .withPotato(potato)
        .with("shape", potatoShape)
        .andFail("unrecognised potato shape");

接入需要以下步骤:

  1. 引入包含该注解的 com.google.errorprone:error_prone_annotations。
  2. 在编译调用方源码时启用 Error Prone,按 Maven、Gradle 等构建环境选择具体配置。
  3. 在 CI 中运行同样的检查,让违规调用导致构建失败。

该规则的默认严重级别是 ERROR,也可以在 Error Prone 配置中显式指定:

-Xep:CompileTimeConstant:ERROR

使用这个检查选项前,仍需接入 Error Prone。JDK 与工具版本的兼容要求应按所选版本核对,参见安装说明和检查选项。

需要注意的边界

只引入注解依赖不会触发检查。API 发布给其他项目后,如果对方没有运行 Error Prone,普通 Java 编译仍会接受动态字符串。

@CompileTimeConstant 接受的表达式也不完全等同于 JLS 的常量表达式。它允许 null,还允许两个分支都满足其常量要求的条件表达式:

builder.andFail(flag ? "potato missing" : "potato shape invalid");

因此,这个注解的约束范围比“只接受直接写在调用处的字符串字面量”更宽。如果 API 不允许 null,需要单独处理。包装方法转发受约束的参数时,也应在入口参数上保留同样的注解。规则接受范围

如果必须只接受字符串字面量

如果连常量引用和常量拼接都要禁止,就需要自定义源码检查。例如,可以编写 Error Prone 规则:

  • 解析调用目标,确认调用的是指定的 andFail 方法。
  • 检查对应实参的语法树是否为字符串字面量。
  • 对其他表达式报告错误,并在 CI 中执行检查。

规则应通过方法所属类型和签名识别目标,避免误伤其他同名方法。对于当前的监控聚合需求,允许使用命名常量通常更方便维护,无须限制到字面量语法。

@MagicConstant 用于约束参数只能从预先列出的值中选择,相当于为 int 或 String 提供枚举式的 IDE 检查。它不能直接表达“允许任意编译期字符串常量”。JetBrains 的说明

Kotlin:const val 不能约束函数实参

Kotlin 的 const val 可以声明编译期常量,但它只能用于属性,不能用于普通函数参数:

const val INVALID_SHAPE = "unrecognised potato shape"

fun andFail(message: String): RuntimeException =
    IllegalStateException(message)

声明常量不会给接收 String 的函数增加约束,上面的函数仍然接受运行时字符串:

andFail(INVALID_SHAPE)
andFail("unrecognised potato shape: $potatoShape")

参见 Kotlin 编译期常量说明。

如果需要检查 Kotlin 调用,可以编写自定义 detekt 规则并接入 CI。规则可以只允许无插值的字符串字面量,也可以进一步允许解析到 const val 的引用。识别目标函数和常量引用时,应使用类型与符号解析。不能假定 Java 方法上的 Error Prone 注解会自动检查 Kotlin 调用。自定义 detekt 规则、类型解析说明

监控聚合还需要固定分组字段

这个 API 可以约定:andFail 的消息只描述错误类别,potato、shape 等具体值保存在结构化属性中。监控查询按稳定的消息字段聚合,排查细节时再查看属性。

常量检查能阻止动态插值,但无法保证不同调用点使用相同的消息。例如,"potato missing" 和 "potato not found" 都是合法常量,按消息分组时仍会分开。需要统一的错误类别应复用同一个常量,并约定消息文字如何修改,无须为此引入数字错误编号。

备注:内容仅供参考。