架构与系统设计 / 系统课时
订单查询接口
订单查询接口
本课实现统一的订单查询能力:商户既能按商户订单号查询,也能按平台订单号查询;当平台状态不确定时,系统还能安全补查渠道并校正本地订单状态。
学习目标
- 设计商户订单查询与平台订单查询的统一入口
- 控制渠道补查条件,避免每次查询都访问外部渠道
- 处理身份校验、幂等校正和稳定响应字段
查询模型与调用路径
查询接口应先定位本地订单,再判断是否需要访问渠道。商户订单号必须与 merchantNo 联合查询,避免不同商户使用相同订单号时发生越权读取;平台订单号同样要校验订单归属。
只有本地状态处于 PENDING、CLOSING 或 UNKNOWN,且距离上次渠道查询超过最小间隔时,才执行补查。成功、失败、关闭等终态通常直接返回本地结果。

接口约定
可以提供一个查询端点,同时接受两种定位方式,但必须保证二选一:merchantOrderNo 用于商户订单查询,platformOrderNo 用于平台订单查询。响应字段保持稳定,不直接暴露渠道原始报文。示例请求:
{
"merchantNo": "M10001",
"merchantOrderNo": "SHOP202608030001",
"platformOrderNo": null,
"refresh": true
}生效行为:接口按 merchantNo + merchantOrderNo 查询订单;refresh=true 只表示允许补查,不代表一定访问渠道。验证时应确认终态订单不会触发渠道请求。
核心实现
下面是一个可运行的 Java 示例,演示两种订单定位方式、归属校验、补查条件和状态校正。为便于运行,示例使用内存仓库和固定渠道响应。
import java.time.Duration;
import java.time.Instant;
import java.util.List;
public class OrderQueryDemo {
enum Status { PENDING, CLOSING, SUCCESS, FAILED, CLOSED, UNKNOWN }
record QueryRequest(
String merchantNo,
String merchantOrderNo,
String platformOrderNo,
boolean refresh
) {}
record Order(
String merchantNo,
String merchantOrderNo,
String platformOrderNo,
Status status,
Instant lastChannelQueryAt
) {
Order withStatus(Status next, Instant queryTime) {
return new Order(merchantNo, merchantOrderNo, platformOrderNo, next, queryTime);
}
}
static class OrderRepository {
private Order order = new Order(
"M10001",
"SHOP202608030001",
"P202608030001",
Status.PENDING,
Instant.parse("2026-08-03T10:00:00Z")
);
Order find(QueryRequest request) {
if (request.platformOrderNo() != null) {
return order.platformOrderNo().equals(request.platformOrderNo()) ? order : null;
}
return order.merchantNo().equals(request.merchantNo())
&& order.merchantOrderNo().equals(request.merchantOrderNo()) ? order : null;
}
void updateIfPending(Status next, Instant now) {
if (List.of(Status.PENDING, Status.CLOSING, Status.UNKNOWN).contains(order.status())) {
order = order.withStatus(next, now);
}
}
}
static class ChannelClient {
Status query(String platformOrderNo) {
return Status.SUCCESS;
}
}
static class QueryService {
private final OrderRepository repository;
private final ChannelClient channelClient;
QueryService(OrderRepository repository, ChannelClient channelClient) {
this.repository = repository;
this.channelClient = channelClient;
}
Order query(QueryRequest request, Instant now) {
Order order = repository.find(request);
if (order == null || !order.merchantNo().equals(request.merchantNo())) {
throw new IllegalArgumentException("ORDER_NOT_FOUND");
}
boolean nonFinal = List.of(Status.PENDING, Status.CLOSING, Status.UNKNOWN)
.contains(order.status());
boolean intervalReached = Duration.between(order.lastChannelQueryAt(), now).getSeconds() >= 30;
if (request.refresh() && nonFinal && intervalReached) {
repository.updateIfPending(channelClient.query(order.platformOrderNo()), now);
order = repository.find(request);
}
return order;
}
}
public static void main(String[] args) {
QueryService service = new QueryService(new OrderRepository(), new ChannelClient());
QueryRequest request = new QueryRequest(
"M10001",
"SHOP202608030001",
null,
true
);
Order result = service.query(request, Instant.parse("2026-08-03T10:01:00Z"));
System.out.println(result.platformOrderNo() + " " + result.status());
}
}预期输出:
P202608030001 SUCCESS实际订单号、时间和渠道状态会不同。生产实现应把渠道返回值先映射为平台统一状态,再使用“当前状态仍可变”的条件更新,防止补查结果覆盖已经到达的异步回调。
响应与异常处理
查询成功时建议返回平台订单号、商户订单号、金额、币种、支付方式、订单状态、创建时间、支付时间和关闭时间。渠道流水号可按业务需要返回,但不应暴露签名字段、密钥、完整卡号或渠道内部调试信息。
未找到订单时,对外统一返回“订单不存在或无权访问”,避免通过错误差异探测其他商户订单。渠道补查失败时可返回本地状态,并在响应中使用平台定义的 statusReason 表示“渠道状态待确认”,同时记录重试任务。
补查频率与验收
接口层要限制单订单补查间隔,并对商户维度做限流,避免高频轮询击穿渠道。多个请求同时补查时,可用短期分布式锁或数据库中的 nextQueryTime 抢占执行权。
验收时分别测试商户订单号查询、平台订单号查询、跨商户访问、终态直返、非终态补查、渠道超时和并发补查。无论走哪条路径,返回结构和状态枚举都必须一致。