第3章:环境信息

系统对外提供 测试环境(Sandbox)生产环境(Production) 两套服务地址,分别用于开发调试与正式业务使用。


3.1 环境说明

环境类型说明是否开放外网访问数据影响用途
Sandbox(测试环境)模拟真实业务逻辑,供开发及联调使用✅ 支持❌ 不影响正式业务数据接口调试、参数验证
Production(生产环境)正式业务系统,所有数据真实有效✅ 支持(需授权)✅ 影响正式业务数据正式业务调用

建议:

  • 所有新集成的系统,应先在 Sandbox 环境完成完整流程验证;
  • 验证通过后,再切换至 Production 环境进行真实业务调用;
  • Sandbox 与 Production 环境的数据、Token、API Key 不互通。

3.2 环境地址信息

环境API 域名协议端口说明
Sandboxhttps://api.sandbox.onixportltl.comHTTPS443测试环境
Productionhttps://api.onixportsystem.comHTTPS443生产环境

3.2.0 沙箱环境测试凭证

为了方便开发者快速测试,沙箱环境提供以下测试凭证:

参数
API Key3F2504E04F8911D39A0C0305E82C3301
API SecretL9Gf7bQ2xU3VjK1Yp8nR5wT0eXz6Hq2fAaJdKsLmQpU

注意

  • 以上凭证仅用于沙箱环境测试,生产环境需要联系技术支持团队申请正式凭证
  • 请妥善保管 API Key 和 API Secret,避免泄露
  • 生产环境的 API Key 和 API Secret 与沙箱环境不同,需要单独申请

3.2.1 接口路径前缀

WMS API 接口根据功能分为两类,使用不同的路径前缀:

接口类型路径前缀说明示例
Token 获取接口/ucauth用于获取访问令牌POST /ucauth/authc/account/createToken
业务接口/onixport所有业务接口的统一前缀POST /onixport/api/wms/product/create

3.2.2 完整接口地址示例

Token 获取接口

环境完整地址
Sandboxhttps://api.sandbox.onixportltl.com/ucauth/authc/account/createToken
Productionhttps://api.onixportsystem.com/ucauth/authc/account/createToken

业务接口示例

接口类型环境完整地址
创建商品Sandboxhttps://api.sandbox.onixportltl.com/onixport/api/wms/product/create
创建商品Productionhttps://api.onixportsystem.com/onixport/api/wms/product/create
创建出库订单Sandboxhttps://api.sandbox.onixportltl.com/onixport/api/wms/outbound/create
创建出库订单Productionhttps://api.onixportsystem.com/onixport/api/wms/outbound/create

说明:

  • Token 获取接口路径前缀:/ucauth
  • 业务接口路径前缀:/onixport
  • 所有业务接口的完整路径格式:/onixport/api/wms/{模块}/{操作}
  • 生产环境请求需使用我司正式分配的 API KeyAPI Secret

3.3 网络与安全要求

  • 协议要求:仅支持 HTTPS,禁止使用 HTTP;
  • 端口开放:仅开放 443(HTTPS);
  • 请求头要求
  • Token 获取接口:需携带 X-Api-KeyX-Api-SecretContent-Type
  • 业务接口:需携带 Authorization: Bearer {token}Content-Type
  • 超时控制
  • 建议调用方设置超时时间为 30 秒
  • 若接口超过 60 秒未响应,请重试或联系技术支持;
  • 错误重试
  • 建议实现指数退避重试机制;
  • 对于 5xx 错误可适当重试,4xx 错误不建议重试。

3.4 环境切换建议

场景推荐使用环境原因
接口开发与调试Sandbox避免污染正式业务数据
接口验收与联调Sandbox可快速回滚与修改数据
正式上线运行Production保证数据真实性与一致性

3.5 环境差异说明

差异项SandboxProduction
数据隔离✅ 完全隔离✅ 真实业务数据
API Key测试环境专用生产环境专用
Token独立生成,不互通独立生成,不互通
数据持久化可能定期清理永久保存
性能可能较低生产级性能
稳定性可能维护高可用保障

3.6 接口限流说明

3.6.1 限流规则

为了保障系统稳定性和公平使用,WMS API 实施了接口限流策略:

限流维度限制说明
单个 API Key100 QPS单个 API Key 每秒最多 100 次请求
单个 IP200 QPS单个 IP 地址每秒最多 200 次请求
批量操作200 条/次单次批量操作最多 200 条数据

说明

  • QPS(Queries Per Second):每秒查询数
  • 限流基于滑动窗口算法
  • 超过限制会返回 429 错误

3.6.2 限流响应

当请求超过限流阈值时,系统会返回以下响应:

HTTP 状态码429 Too Many Requests

响应示例

{
  "success": false,
  "errorCode": 429,
  "errorMsg": "请求频率过高,请稍后重试",
  "result": null
}

响应头信息(如果提供):

  • Retry-After: 建议等待的秒数(如:Retry-After: 60
  • X-RateLimit-Limit: 限流阈值(如:X-RateLimit-Limit: 100
  • X-RateLimit-Remaining: 剩余请求数(如:X-RateLimit-Remaining: 50
  • X-RateLimit-Reset: 限流重置时间(Unix 时间戳)

3.6.3 限流处理建议

1. 客户端限流控制

建议实现

  • 在客户端实现请求队列
  • 控制请求发送频率,避免超过限流阈值
  • 使用令牌桶或漏桶算法

示例代码

// 示例代码 - 令牌桶算法
import java.util.concurrent.atomic.AtomicLong;
import java.util.concurrent.locks.ReentrantLock;

public class RateLimiter {
    private final int maxRequests; // 100
    private final long timeWindow; // 1000ms (1秒)
    private AtomicLong tokens;
    private AtomicLong lastRefill;
    private final ReentrantLock lock = new ReentrantLock();
    
    public RateLimiter(int maxRequests, long timeWindow) {
        this.maxRequests = maxRequests;
        this.timeWindow = timeWindow;
        this.tokens = new AtomicLong(maxRequests);
        this.lastRefill = new AtomicLong(System.currentTimeMillis());
    }
    
    public boolean acquire() throws InterruptedException {
        refill();
        if (tokens.get() > 0) {
            tokens.decrementAndGet();
            return true;
        }
        // 等待下一个令牌
        long waitTime = timeWindow / maxRequests;
        Thread.sleep(waitTime);
        return acquire();
    }
    
    private void refill() {
        long now = System.currentTimeMillis();
        long elapsed = now - lastRefill.get();
        if (elapsed >= timeWindow) {
            lock.lock();
            try {
                // 双重检查
                if (elapsed >= timeWindow) {
                    tokens.set(maxRequests);
                    lastRefill.set(now);
                }
            } finally {
                lock.unlock();
            }
        }
    }
}

// 使用示例
RateLimiter limiter = new RateLimiter(100, 1000); // 100 QPS
limiter.acquire();
// 发送请求

2. 遇到限流时的处理

处理策略

1. 立即停止发送请求:避免进一步触发限流

2. 等待后重试:根据 Retry-After 响应头等待指定时间

3. 降低请求频率:减少并发请求数

4. 分批处理:将大批量操作拆分成多个小批次

示例代码

// 示例代码
import org.springframework.http.HttpStatus;
import org.springframework.http.ResponseEntity;

public class RateLimitHandler {
    
    /**
     * 处理限流错误
     */
    public ResponseEntity<?> handleRateLimit(ResponseEntity<?> response) throws InterruptedException {
        if (response.getStatusCode() == HttpStatus.TOO_MANY_REQUESTS) {
            // 获取 Retry-After 响应头,默认60秒
            String retryAfterHeader = response.getHeaders().getFirst("Retry-After");
            long retryAfter = retryAfterHeader != null ? Long.parseLong(retryAfterHeader) : 60;
            
            System.out.println("限流错误,等待 " + retryAfter + " 秒后重试");
            Thread.sleep(retryAfter * 1000);
            
            // 降低请求频率
            reduceRequestRate();
            
            // 重新发送请求
            return retryRequest();
        }
        return response;
    }
    
    private void reduceRequestRate() {
        // 降低请求频率的逻辑
    }
    
    private ResponseEntity<?> retryRequest() {
        // 重新发送请求的逻辑
        return null;
    }
}

3. 批量操作优化

建议

  • 单次批量操作不超过 100 条(虽然限制是 200 条)
  • 多个批量操作之间增加延迟(如 100ms)
  • 使用异步处理,避免阻塞

示例代码

// 示例代码
import java.util.List;
import java.util.ArrayList;

public class BatchOperationService {
    
    private static final int BATCH_SIZE = 100; // 每批100条
    
    /**
     * 批量创建,分批处理避免触发限流
     */
    public void batchCreate(List<Object> items) throws InterruptedException {
        // 分批处理
        for (int i = 0; i < items.size(); i += BATCH_SIZE) {
            int end = Math.min(i + BATCH_SIZE, items.size());
            List<Object> batch = items.subList(i, end);
            
            // 创建当前批次
            createBatch(batch);
            
            // 批次之间延迟,避免触发限流
            if (end < items.size()) {
                Thread.sleep(100);
            }
        }
    }
    
    private void createBatch(List<Object> batch) {
        // 创建批次的逻辑
    }
}

3.6.4 限流监控

建议监控指标

1. 请求频率:监控实际 QPS,确保不超过限制

2. 限流错误率:监控 429 错误出现频率

3. 响应时间:限流可能导致响应时间增加

告警阈值

  • 请求频率 > 80 QPS(接近限流阈值)
  • 429 错误率 > 1%
  • 响应时间 > 2 秒

3.6.5 限流提升

如果需要更高的限流阈值,请联系技术支持团队,提供以下信息:

  • 业务场景说明
  • 预期请求频率
  • 业务高峰期时间

技术支持团队将根据实际情况评估是否可以提高限流阈值。