第3章:环境信息
系统对外提供 测试环境(Sandbox) 与 生产环境(Production) 两套服务地址,分别用于开发调试与正式业务使用。
3.1 环境说明
| 环境类型 | 说明 | 是否开放外网访问 | 数据影响 | 用途 |
|---|---|---|---|---|
| Sandbox(测试环境) | 模拟真实业务逻辑,供开发及联调使用 | ✅ 支持 | ❌ 不影响正式业务数据 | 接口调试、参数验证 |
| Production(生产环境) | 正式业务系统,所有数据真实有效 | ✅ 支持(需授权) | ✅ 影响正式业务数据 | 正式业务调用 |
建议:
- 所有新集成的系统,应先在 Sandbox 环境完成完整流程验证;
- 验证通过后,再切换至 Production 环境进行真实业务调用;
- Sandbox 与 Production 环境的数据、Token、API Key 不互通。
3.2 环境地址信息
| 环境 | API 域名 | 协议 | 端口 | 说明 |
|---|---|---|---|---|
| Sandbox | https://api.sandbox.onixportltl.com | HTTPS | 443 | 测试环境 |
| Production | https://api.onixportsystem.com | HTTPS | 443 | 生产环境 |
3.2.0 沙箱环境测试凭证
为了方便开发者快速测试,沙箱环境提供以下测试凭证:
| 参数 | 值 |
|---|---|
| API Key | 3F2504E04F8911D39A0C0305E82C3301 |
| API Secret | L9Gf7bQ2xU3VjK1Yp8nR5wT0eXz6Hq2fAaJdKsLmQpU |
注意:
- 以上凭证仅用于沙箱环境测试,生产环境需要联系技术支持团队申请正式凭证
- 请妥善保管 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 获取接口
| 环境 | 完整地址 |
|---|---|
| Sandbox | https://api.sandbox.onixportltl.com/ucauth/authc/account/createToken |
| Production | https://api.onixportsystem.com/ucauth/authc/account/createToken |
业务接口示例
| 接口类型 | 环境 | 完整地址 |
|---|---|---|
| 创建商品 | Sandbox | https://api.sandbox.onixportltl.com/onixport/api/wms/product/create |
| 创建商品 | Production | https://api.onixportsystem.com/onixport/api/wms/product/create |
| 创建出库订单 | Sandbox | https://api.sandbox.onixportltl.com/onixport/api/wms/outbound/create |
| 创建出库订单 | Production | https://api.onixportsystem.com/onixport/api/wms/outbound/create |
说明:
- Token 获取接口路径前缀:
/ucauth- 业务接口路径前缀:
/onixport- 所有业务接口的完整路径格式:
/onixport/api/wms/{模块}/{操作}- 生产环境请求需使用我司正式分配的 API Key 与 API Secret。
3.3 网络与安全要求
- 协议要求:仅支持
HTTPS,禁止使用 HTTP; - 端口开放:仅开放 443(HTTPS);
- 请求头要求:
- Token 获取接口:需携带
X-Api-Key、X-Api-Secret、Content-Type; - 业务接口:需携带
Authorization: Bearer {token}、Content-Type; - 超时控制:
- 建议调用方设置超时时间为 30 秒;
- 若接口超过 60 秒未响应,请重试或联系技术支持;
- 错误重试:
- 建议实现指数退避重试机制;
- 对于 5xx 错误可适当重试,4xx 错误不建议重试。
3.4 环境切换建议
| 场景 | 推荐使用环境 | 原因 |
|---|---|---|
| 接口开发与调试 | Sandbox | 避免污染正式业务数据 |
| 接口验收与联调 | Sandbox | 可快速回滚与修改数据 |
| 正式上线运行 | Production | 保证数据真实性与一致性 |
3.5 环境差异说明
| 差异项 | Sandbox | Production |
|---|---|---|
| 数据隔离 | ✅ 完全隔离 | ✅ 真实业务数据 |
| API Key | 测试环境专用 | 生产环境专用 |
| Token | 独立生成,不互通 | 独立生成,不互通 |
| 数据持久化 | 可能定期清理 | 永久保存 |
| 性能 | 可能较低 | 生产级性能 |
| 稳定性 | 可能维护 | 高可用保障 |
3.6 接口限流说明
3.6.1 限流规则
为了保障系统稳定性和公平使用,WMS API 实施了接口限流策略:
| 限流维度 | 限制 | 说明 |
|---|---|---|
| 单个 API Key | 100 QPS | 单个 API Key 每秒最多 100 次请求 |
| 单个 IP | 200 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 限流提升
如果需要更高的限流阈值,请联系技术支持团队,提供以下信息:
- 业务场景说明
- 预期请求频率
- 业务高峰期时间
技术支持团队将根据实际情况评估是否可以提高限流阈值。