对于交易 API 而言，"能调用"只是开始；真正决定系统是否可靠的，是高峰行情、网络抖动、密钥轮换和异常重试时，它是否仍能避免重复下单、请求失控和数据失真。
一套稳定的 API 系统，不应把安全、限频和风控视为上线前的补丁，而应将其放进订单生命周期的每个环节：请求发出前有权限控制，请求处理中有速率管理，异常发生后有状态核验，系统恢复时有对账机制。
本文以 WEEX 现货 API 为例，整理一套可落地的工程化清单。
一、稳定性不是"永不报错"，而是出错后仍能恢复正确状态
一个成熟的交易 API 服务，应具备以下能力：
正常请求 → 记录状态 → 接收结果 → 持续核验
↓
异常发生 → 限制影响 → 查询真实状态 → 恢复或人工介入
这意味着系统设计的目标不只是提高请求成功率，更是保证在以下情况发生时，订单事实仍然可追溯：
- API 请求超时；
- 网络中断或 WebSocket 断线；
- 收到限频响应；
- 服务端返回临时错误；
- 订单部分成交；
- 撤单与成交在短时间内交错发生；
- 部署重启、进程崩溃或密钥轮换。
最需要避免的行为是：把"未收到响应"直接理解为"请求失败"，然后立即生成新的订单号再次下单。对于有状态的交易请求，这种做法可能导致重复订单。
二、限频：不要依赖固定数字，要读取实时限制
限频并不只是"每分钟最多请求多少次"。不同接口可能使用不同的限频维度和权重，且规则可能随 API 版本更新。
WEEX 现货 API 当前文档说明：
- 除下单接口外，REST 接口主要按 IP 限频；
- 单笔下单和批量下单按账户维度的 ORDERS 类型限频；
- 撤单、订单查询等其他订单相关接口仍按 IP 限频；
- 超限时会返回 HTTP 429，收到后应停止继续发送请求；
- 限频信息会通过响应头返回。
因此，系统不应把频率阈值硬编码在业务逻辑里，而应该同时读取接口响应头中的实时使用量和剩余额度。常见限频响应头包括：
例如，X-USED-WEIGHT-1M 表示当前 IP 在 1 分钟窗口内已使用的请求权重。
一个更合理的限频策略
建议将请求分成三类，分别管理：
当剩余额度接近阈值时，系统可以主动降级：
- 暂停非关键的数据刷新；
- 合并相同交易对的查询；
- 使用 WebSocket 代替高频 REST 轮询；
- 保留订单核验和风险控制请求的优先级。
限频的本质不是"尽量打满额度"，而是确保关键请求在必要时仍能发送。
三、收到 429 后：停止、退避、恢复，不要持续重试
429 Too Many Requests 表示请求过于频繁。此时若立即、持续地重试，只会扩大问题，并可能导致连接或 IP 被临时限制。
可采用"指数退避 + 随机抖动"的思路：
第一次重试：短暂等待
第二次重试：增加等待时间
后续重试：继续增加等待，并设置最大次数
"随机抖动"指在等待时间上增加少量随机值，避免多个服务实例在同一时刻再次发起请求，形成新的请求峰值。
但必须区分请求类型：
- 对公共行情查询，可以安全地延后或放弃一次刷新；
- 对订单查询，可延后后再核验；
- 对下单请求，不能在收到超时或限频后直接换一个订单号重试，应先查询原订单状态。
建议把 429 作为监控告警事件，而不是普通日志。它通常意味着轮询频率、缓存策略、调用方隔离或异常重试逻辑需要调整。
四、密钥安全：把 API Key 当作生产权限，而不是配置字符串
API Key、Secret Key 和 Access Passphrase 一旦泄露，风险不在于"代码不够优雅"，而在于敏感账户能力可能暴露。
WEEX 私有 REST 请求需要使用 API Key、签名、时间戳和 Access Passphrase。请求的 Content-Type 应统一为 application/json；签名由时间戳、请求方法、请求路径、查询参数和请求体等内容构成。
建议落实以下最低安全要求：
- 密钥只保存在服务端
不要将任何私钥、Secret Key 或 Access Passphrase 放入：
- 前端 JavaScript；
- 移动端安装包；
- 浏览器本地存储；
- 截图、文档或即时通讯工具；
- 公开仓库、示例代码或日志。
前端页面若需要展示订单或账户信息，应访问自建业务服务；由自建服务在受控环境中调用私有 API。
- 使用环境隔离和最小权限
为开发、测试和生产环境分别创建独立 API Key。不要让测试脚本与生产服务共享同一密钥。
如果业务只需要读取数据，就不应使用带交易权限的密钥；如果某个服务只负责订单查询，也应限制其可访问范围。权限越小，密钥泄露后的影响范围越小。
- 配置 IP 白名单并定期轮换
应将生产服务的固定出口 IP 加入白名单，并为密钥建立轮换机制：创建新密钥 → 更新服务配置 → 验证运行正常 → 停用旧密钥
密钥轮换时，要避免"同时停用旧密钥和未验证新密钥"，否则可能导致订单管理系统失联。
- 日志必须脱敏
以下内容不得原样写入日志：ACCESS-KEY、ACCESS-SIGN、ACCESS-PASSPHRASE、Secret Key、完整请求头
日志应保留请求路径、请求时间、HTTP 状态、业务错误码、clientOrderId 和 orderId，但必须隐藏敏感字段。
五、时间同步和签名一致性：最常见、也最容易忽略的故障点
WEEX 文档要求 ACCESS-TIMESTAMP 使用毫秒级 Unix 时间戳，且必须处于 API 服务时间允许的窗口内；本地服务器时间偏差过大时，请求可能因过期被拒绝因此，生产环境应确保：
- 服务器启用可靠的时间同步服务；
- 时间戳在发出请求前即时生成；
- 签名使用的 body 字符串与实际发送的请求体完全一致；
- 查询参数的顺序、编码方式和实际请求 URL 保持一致。
尤其要注意：如果先用一个 JSON 字符串计算签名，再由 HTTP 客户端重新格式化请求体，可能导致签名不匹配。正确做法是先序列化一次请求体，用这同一个字符串完成签名并发送。
六、重试不是万能药：先判断"请求是否幂等"
幂等，简单来说，就是同一个请求执行一次或执行多次，最终结果是否一致。
对于查询类请求，如获取订单详情或当前挂单，通常可以在合理限频范围内重试；但对于下单、撤单等状态变更请求，不能按普通网络请求的方式直接重试。
WEEX 下单接口支持 newClientOrderId。文档说明，当账户中已有相同客户端订单号的委托时，接口会返回成功但不会重复创建订单。这使得客户端订单号成为防止重复下单的重要机制。
下单超时的正确恢复流程
下单请求超时
↓
不要立即重新下单
↓
使用原 clientOrderId 查询订单
↓
查到订单 → 恢复订单跟踪
未查到订单 → 结合日志与业务规则决定是否重试
错误做法：请求超时 → 生成新的 clientOrderId → 再次下单
这会使系统无法判断第一笔订单是否已被交易所受理，从而可能造成重复订单。
七、WebSocket 负责实时，REST 负责核验
在订单和账户场景中，REST 与 WebSocket 不应互相替代，而应相互补充。
WEEX 私有 WebSocket 连接需要鉴权头信息；连接后服务端会定期发送 Ping，客户端需要回复 Pong。若连续多次未响应，服务端会主动断开连接。因此，连接管理模块至少应具备：
- Ping/Pong 响应；
- 断线检测；
- 指数退避重连；
- 重连后重新订阅；
- 重连后使用 REST 查询当前挂单和关键订单状态；
- 记录断线时间段，便于后续排查是否遗漏事件。
不要假设"重连成功"就代表数据已经恢复完整。对于深度、订单和成交等状态型数据，应通过快照或查询接口重新校验。
八、将风控前置到"发送请求之前"
技术风控并不负责预测市场走势，而是避免系统因参数异常、程序缺陷或运行失控而执行超出预期的操作。
建议在下单前设置一层独立的风控校验器：
策略或业务请求
↓
参数校验
↓
额度与频率校验
↓
风险规则校验
↓
生成 clientOrderId
↓
发送 API 请求
可以从以下基础规则开始：
其中，"仅允许撤单模式"尤为重要：当系统检测到行情数据失真、订单状态异常、密钥故障或频繁限流时，应能迅速停止新增订单，同时保留必要的查询和撤单能力。
九、建立熔断与人工介入机制
当异常不再是单个请求问题，而是持续发生时，系统应主动熔断，防止错误扩大。
可考虑设置以下触发条件：
- 连续出现签名或鉴权失败；
- 在短时间内多次收到 429；
- WebSocket 长时间未恢复；
- 行情数据时间戳明显滞后；
- 本地订单状态与接口查询结果长期不一致；
- 单位时间内下单数量异常增长；
- 出现无法解释的重复客户端订单号。
熔断后的可选状态：
熔断不能只是一条报错日志，而应该是可见、可审计、可由授权人员恢复的系统状态。
十、可观测性：没有监控，就无法证明系统稳定
稳定性需要量化。建议至少记录以下指标：
建议为以下事件设置告警，而非仅记录日志：
- 私有 WebSocket 断线超过预设时间；
- 下单请求超时；
- 短时间内多次 429；
- 连续鉴权失败；
- 订单状态长期停留在未知状态；
- 风控规则触发熔断。
附：生产部署前检查清单
✅ API Key、Secret Key 和 Access Passphrase 未出现在前端、仓库或日志中
✅ 已配置 IP 白名单，并完成密钥轮换预案
✅ 服务器时间已同步，签名字符串与实际请求完全一致
✅ 已读取并记录限频响应头，不依赖硬编码阈值
✅ 收到 429 后会停止高频请求并执行退避
✅ 所有下单请求使用唯一 newClientOrderId
✅ 下单超时后会先查询原订单，而不是直接重复下单
✅ 已使用 WebSocket 接收实时状态，并用 REST 进行补偿核验
✅ 已实现断线重连、重新订阅和重连后对账
✅ 已配置单笔、累计、频率和紧急开关等风控规则
✅ 已建立"只撤单"和"全暂停"等熔断状态
✅ 已监控请求延迟、错误码、限频、订单状态和数据滞后
总结一下：
交易 API 的稳定性，最终体现为系统在异常条件下是否仍能保持"少做错、能恢复、可追溯"。
对于 WEEX API 接入，限频管理可以防止请求失控，密钥隔离减少敏感权限暴露，客户端订单号降低重复下单风险，WebSocket 与 REST 协同则帮助系统在断线或超时后恢复真实订单状态。将这些能力工程化，才是自动化订单管理从"可运行"走向"可维护"的关键。
本文仅介绍 API 系统安全、稳定性与风险控制的技术实践，不构成投资、交易或收益建议。WEEX 现货 API 文档当前标注为 V3（BETA）。在正式部署前，请以官方文档的最新接口参数、签名规范和访问限制为准。