跳到主要内容
约 10 分钟3 张卡

Java API 设计

Java API 通过类型和方法约定合法输入、允许的操作,以及成功或失败时的结果。这些约定共同构成 API 的契约。设计清楚后,调用方不用翻看实现,也能知道一个方法该怎样使用。

例如,订单 API 要拒绝负数金额,也要阻止已取消的订单再次支付。如果只靠调用方自行检查,漏掉一处就可能保存非法状态。设计这类 API,关键是把约束放进类型和操作入口,再写清缺失、失败、并发与重试的处理方式。语言和 API 示例以 Java 17、21 为准。

1. 面试核心​

先记住这几条,再读正文
  • 构造器或静态工厂在创建时校验不变量,让创建成功的对象处于合法状态。卡 · 业务不变量
  • Money 这样的领域类型把同一业务概念的解析、校验和相等性判断集中在类型内部。卡 · 领域类型
  • pay、cancel 等业务方法统一检查前置状态再更新字段,每次状态转换都经过业务规则。
  • 参数对象按业务含义组织参数,Builder 则在 build 时统一校验必需参数和参数之间的约束。卡 · 领域类型
  • Optional.empty() 表示正常缺失;orElse 的实参总会先求值,orElseGet 只在结果缺失时才计算默认值。卡 · Optional 的默认值求值

2. 业务不变量​

业务不变量是对象创建成功之后、每次操作结束之后都必须成立的约束。设计订单 API 时,可以先把金额与状态的约束列出来:

  • 币种必须存在。
  • 金额大于等于零。
  • 已支付订单保持原金额。
  • 支付入口只接受待支付状态,所以已取消的订单也会被拒绝。

如果允许先创建空对象、再随意调用 setter,保证字段组合合法的责任就落到了每个调用方身上。下面的代码就让订单持有了空币种和负数金额:

Order order = new Order();
order.setCurrency(null);
order.setAmount(new BigDecimal("-1"));

更稳妥的做法是在对象建立时就验证:

public record Money(BigDecimal amount, Currency currency) {
public Money {
Objects.requireNonNull(amount, "amount");
Objects.requireNonNull(currency, "currency");

if (amount.signum() < 0) {
throw new IllegalArgumentException("amount must be >= 0");
}
}
}

public Money { ... } 是 record 的紧凑构造器,省略了参数列表,可以在字段赋值前检查组件值。这里先检查金额和币种不为 null,再拒绝负数金额。构造成功后,其他方法就可以依赖这些约束。订单能不能支付是另一层约束,由订单的状态转换方法负责(见第 4 节)。

3. 领域类型​

领域类型是专门表示某个业务概念的类型,比如账户标识、金额。先看一个只用字符串和数值的转账签名:

void transfer(String from, String to, BigDecimal amount, String currency);

这个签名能接受任意字符串作为账户,from 和 to 都是 String,传反了编译器也发现不了。BigDecimal 只表示数值,金额用什么币种、怎么舍入,还得另外约定。把这些约束放进领域类型,解析和校验就有了固定的位置:

TransferResult transfer(
AccountId from,
AccountId to,
Money amount,
IdempotencyKey idempotencyKey
);

AccountId 负责账户标识的格式,Money 负责金额与币种,IdempotencyKey 标识一次可以重复提交的请求(第 8 节会讲到它的作用)。同一个业务值怎么解析、怎么校验、怎么判断相等,都归它的类型管。金额的舍入规则也应该在金额类型或金额运算的入口写明。

给参数换上领域类型,并不会自动消除所有误用。这里 from 和 to 都是 AccountId,传反了照样能编译;AccountId 只能校验账户标识本身,无法判断调用方是否选对了转账方向。设计签名时,还要检查同类型参数、布尔标志和可空参数的含义是否足够清楚。

3.1 布尔参数​

布尔参数只有真和假,调用处却看不出它们分别控制什么:

send(message, true, false);

读这一行的人不知道 true 和 false 各代表什么。可以拆成命名方法,或者换成枚举、配置值:

send(message, DeliveryMode.RELIABLE, AuditMode.ENABLED);

4. 状态转换方法​

状态转换方法把前置检查和字段更新放在同一个业务操作里。反过来,如果 setter 允许任意写入状态,调用方就能绕过业务规则:

order.setStatus(OrderStatus.PAID);

这一行把订单直接标成已支付,不管它原来是不是已经取消。更好的做法是用表达业务动作的方法来完成转换:

public PaymentAccepted pay(PaymentId paymentId, Instant paidAt) {
if (status != OrderStatus.PENDING_PAYMENT) {
throw new InvalidOrderState(status, "pay");
}

status = OrderStatus.PAID;
return new PaymentAccepted(id, paymentId, paidAt);
}

pay 先检查订单是不是待支付,通过了才更新 status 并返回 PaymentAccepted。规则集中在订单对象内部,Controller、Service 和消息消费者都只能通过这一个入口支付。

多个线程共享同一个订单对象时,检查和更新还要作为一个整体受同步保护。否则两个线程可能同时通过状态检查,各自执行一次支付。

5. 参数与返回值的所有权​

所有权约定说明一个对象由谁保管、谁可以修改。公共 API 要写清楚三件事:是否保留传入的引用,是否复制,调用过程中会不会修改输入。最省心的约定是输入归调用方所有、方法不改它的内容;确实要修改参数时,用方法名和文档明确说出来。

假设方法直接保存调用方传进来的规则列表,调用方之后往原列表里加一条,对象内部的规则也会变化。用 List.copyOf 保存不可修改的列表后,原列表的增删就不会影响内部列表;不过,两份列表仍共享元素,可变元素还要单独处理。

列表与元素的复制示例见 不可变对象。数组 getter 的处理见该文的输出边界。

6. 缺失与失败​

查询没有结果和命令执行失败是两回事,调用方要做的事完全不同:前者通常补个默认值或换条路走,后者要知道为什么失败、能不能重试。API 要把这两种情况区分开,同一种失败也要始终用同一种方式表达。

6.1 查询无结果​

Optional 是一个要么装着一个结果、要么为空的容器,适合表示方法的可选返回值。查询允许找不到用户时,可以用它表达这种正常缺失:

Optional<User> findById(UserId id);

这个 API 应约定:找不到用户时,findById 返回 Optional.empty();找到时,返回包含用户的 Optional。返回值本身不能是 null,调用方才只需要处理容器为空或有值这两种情况。

6.2 命令失败​

参数本身非法时,可以抛 IllegalArgumentException。参数没问题、但对象当前状态拒绝这个操作时,比如订单已取消,就用业务异常或结果类型说明原因。跨服务的接口还要把这些失败映射成稳定的错误码,客户端按错误码处理,内部类名和堆栈只用于诊断。

6.3 失败表达的一致性​

同一种失败始终用同一种方式表达,调用方才知道该检查返回值还是捕获异常。程序分支要依据异常类型或错误码来判断,异常消息只给人看。这样以后调整诊断文字,调用方的处理逻辑也不会受影响。

7. 接口范围​

接口应该围绕调用方需要的业务能力来设计,而不是暴露实现的全部细节。比如货币换算只需要查汇率,就只依赖下面这个接口:

public interface ExchangeRateProvider {
ExchangeRate rate(Currency from, Currency to, Instant at);
}

汇率可以来自数据库、远程服务或内存,调用方只依赖「查询汇率」这一个能力。换实现很方便,测试时也能直接给一个固定汇率。

一次业务动作要有一个完整的调用入口。如果正确使用必须依次调用 begin、setX、setY、validate、commit,调用方就得自己管理一串中间状态,漏掉或调换任何一步,对象都可能停在非法状态。

确实要分步收集参数时,用 Builder 暂存输入,在 build 时统一校验。如果阶段顺序本身有业务含义,也可以让每个阶段用不同的类型,只暴露这个阶段允许的操作。

8. 并发、幂等与阻塞​

方法签名说明了传什么、返回什么,但没说调用会怎样等待、能不能重试、对象能不能共享。这些同样是契约的一部分,公开方法要回答五个问题:

  • 实例能否跨线程共享。
  • 操作是否会阻塞或发起 I/O。
  • 超时和中断怎样传播。
  • 重复调用是否安全。
  • 回调会在哪个线程执行。
PaymentResult charge(
IdempotencyKey key,
Money amount,
Duration timeout
);

幂等是指同一个请求重复执行多次,业务效果和执行一次一样。charge 的签名里,key 用来识别重复请求,timeout 表示调用方最多愿意等多久。

光有参数还不够。实现要按幂等键保存结果,并把等待上限传给下游,否则签名写得再好,调用方还是会碰到重复扣款或无限等待。这些约定明确了,调用方才能判断超时之后能不能放心重试。

9. 兼容性​

接口改动之后,旧客户端既要能继续调用,还要得到符合原来约定的结果。兼容性要从三个层面检查:

  • 源码兼容:旧客户端的源码能否重新编译。新增的重载会参与重载匹配,所以重新编译时选中的方法可能变了。
  • 二进制兼容:已经编译好的客户端能否继续链接运行。删掉它调用的公开方法会破坏链接;新增重载、保留旧方法,原来的入口就还在。
  • 行为兼容:旧客户端看到的结果、异常和副作用是否仍符合约定。

前两层编译器和链接器能帮你发现,第三层不能。即使方法签名一模一样,下面这些变化也会影响调用方:

  • 原来允许 null,现在拒绝。
  • 遍历顺序改变。
  • 异常类型或错误码改变。
  • 同步方法改为异步。
  • 返回可变集合改为不可修改集合。
  • equals、hashCode 或序列化形态改变。

所以发布前要记下调用方依赖的可观察行为,用旧客户端和契约测试去验证。契约测试检查双方约定好的输入输出和失败方式。迁移阶段同样要验证新旧调用方的行为,编译通过只说明源码这一层没问题。

10. Optional 的默认值求值​

查询结果缺失时,调用方经常要给一个默认值。这里要分清两种写法:直接传入默认值,还是传入一个计算默认值的函数。

orElse(defaultValue()) 会先执行 defaultValue(),再调用 orElse。Java 调用方法前总是先把实参算出来,所以即使 Optional 里有值,这次计算也已经发生了。默认值需要按需加载时,这样写:

User user = found.orElseGet(() -> loadDefaultUser());

orElseGet 接收一个 Supplier,也就是被调用时才产生结果的函数。只有 found 为空时,它才会调用这个函数去加载默认用户。如果默认值要查数据库,或者有其他副作用,这种按需求值就能省掉多余的操作。想把缺失直接变成异常,用 orElseThrow。

11. 常见问题​

11.1 应该使用构造器还是静态工厂?​

创建方式只有一种、含义明确时,用构造器。需要给不同的创建方式起名字、复用实例或返回子类型时,用静态工厂。不管哪种,都要在返回对象之前完成必需的校验。

11.2 参数多时都应该使用 Builder 吗?​

11.3 公共参数都要检查 null 吗?​

11.4 为了测试私有方法,应把它改成公开方法吗?​

12. 面试题卡片​

13. 参考资料​

来源:Coding 101 原文 · 免费阅读,引用请保留出处。内容使用说明