架构与系统设计 / 系统课时

订单查询接口

订单查询接口

本课实现统一的订单查询能力:商户既能按商户订单号查询,也能按平台订单号查询;当平台状态不确定时,系统还能安全补查渠道并校正本地订单状态。

学习目标

  • 设计商户订单查询与平台订单查询的统一入口
  • 控制渠道补查条件,避免每次查询都访问外部渠道
  • 处理身份校验、幂等校正和稳定响应字段

查询模型与调用路径

查询接口应先定位本地订单,再判断是否需要访问渠道。商户订单号必须与 merchantNo 联合查询,避免不同商户使用相同订单号时发生越权读取;平台订单号同样要校验订单归属。

只有本地状态处于 PENDING、CLOSING 或 UNKNOWN,且距离上次渠道查询超过最小间隔时,才执行补查。成功、失败、关闭等终态通常直接返回本地结果。

订单查询与渠道补查时序

接口约定

可以提供一个查询端点,同时接受两种定位方式,但必须保证二选一:merchantOrderNo 用于商户订单查询,platformOrderNo 用于平台订单查询。响应字段保持稳定,不直接暴露渠道原始报文。示例请求:

json
{
  "merchantNo": "M10001",
  "merchantOrderNo": "SHOP202608030001",
  "platformOrderNo": null,
  "refresh": true
}

生效行为:接口按 merchantNo + merchantOrderNo 查询订单;refresh=true 只表示允许补查,不代表一定访问渠道。验证时应确认终态订单不会触发渠道请求。

核心实现

下面是一个可运行的 Java 示例,演示两种订单定位方式、归属校验、补查条件和状态校正。为便于运行,示例使用内存仓库和固定渠道响应。

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());
    }
}

预期输出:

text
P202608030001 SUCCESS

实际订单号、时间和渠道状态会不同。生产实现应把渠道返回值先映射为平台统一状态,再使用“当前状态仍可变”的条件更新,防止补查结果覆盖已经到达的异步回调。

响应与异常处理

查询成功时建议返回平台订单号、商户订单号、金额、币种、支付方式、订单状态、创建时间、支付时间和关闭时间。渠道流水号可按业务需要返回,但不应暴露签名字段、密钥、完整卡号或渠道内部调试信息。

未找到订单时,对外统一返回“订单不存在或无权访问”,避免通过错误差异探测其他商户订单。渠道补查失败时可返回本地状态,并在响应中使用平台定义的 statusReason 表示“渠道状态待确认”,同时记录重试任务。

补查频率与验收

接口层要限制单订单补查间隔,并对商户维度做限流,避免高频轮询击穿渠道。多个请求同时补查时,可用短期分布式锁或数据库中的 nextQueryTime 抢占执行权。

验收时分别测试商户订单号查询、平台订单号查询、跨商户访问、终态直返、非终态补查、渠道超时和并发补查。无论走哪条路径,返回结构和状态枚举都必须一致。

按自己的节奏,确认真正理解。

目录与阅读设置

阅读设置

17

记录一个想法

订单查询接口

0 / 10000 · 笔记保存到账号。未提交的修改会在关闭、离开或刷新后丢失。

登录哪都通