性能与最佳实践
Quick Reference
What性能优化
Why通过合理的重试与幂等策略构建可靠的高吞吐集成
Difficulty中级
Prerequisites身份验证 → 创建扣款
高性能集成结合幂等请求、智能重试、凭证缓存和分层身份验证，以最大化吞吐量和通过率。
速率限制
| 层级 | 限制 | 范围 |
|---|---|---|
| 标准 | 100 请求/分钟 | 按 access token（访问令牌） |
| 突发 | 20 请求/秒 | 按访问令牌 |
| 自定义 | 可配置 | 联系集成经理 |
当触发速率限制时，A55 返回 HTTP 429 并附带 Retry-After 头（秒数）。
避免循环
永远不要在紧密循环中重试 4xx 错误。收到 429 时退避等待，5xx 时使用指数退避重试，将卡片拒绝视为终态。
超时设置
| 操作 | 建议超时 | 最大超时 |
|---|---|---|
| 获取身份验证令牌 | 10 秒 | 30 秒 |
| 创建扣款 | 60 秒 | 90 秒 |
| 3DS 设置 / 验证 | 30 秒 | 60 秒 |
| 零额验证 | 15 秒 | 30 秒 |
| 查询 / 列表端点 | 10 秒 | 30 秒 |
重试策略
指数退避
import time, requests
def call_with_retry(url, headers, payload, max_retries=3):
for attempt in range(max_retries):
try:
r = requests.post(url, headers=headers, json=payload, timeout=60)
if r.status_code < 500:
return r
time.sleep(2 ** attempt)
except requests.exceptions.Timeout:
time.sleep(2 ** attempt)
raise Exception("超过最大重试次数")
幂等键
通过发送 Idempotency-Key 头防止重试导致的重复扣款：
curl -X POST 'https://core-manager.a55.tech/api/v1/bank/wallet/charge/' \
-H 'Authorization: Bearer $ACCESS_TOKEN' \
-H 'Content-Type: application/json' \
-H 'Idempotency-Key: ord_001_attempt_1' \
-d '{ ... }'
| 行为 | 说明 |
|---|---|
| 相同键 + 相同请求体 | 返回原始响应（不产生重复扣款） |
| 相同键 + 不同请求体 | 返回 409 Conflict |
| 不使用键 | 每次请求创建一笔新扣款 |
键格式
使用订单 ID 和尝试次数的组合：{order_id}_attempt_{n}。这样便于调试且避免意外重用。
身份验证性能
- 缓存 access token——令牌有效期为 3600 秒。请求一次，跨调用复用
- 不要每次 API 调用都请求令牌——这会浪费速率限制配额并增加延迟
- 主动刷新——在约 3500 秒时刷新，而非等到过期
import os, time, requests
_token_cache = {"token": None, "expires_at": 0}
def get_token():
if time.time() < _token_cache["expires_at"] - 100:
return _token_cache["token"]
r = requests.post(
"https://core-manager.a55.tech/api/v1/auth/token",
data={
"grant_type": "client_credentials",
"client_id": os.environ["A55_CLIENT_ID"],
"client_secret": os.environ["A55_CLIENT_SECRET"],
},
timeout=10,
)
data = r.json()
_token_cache["token"] = data["access_token"]
_token_cache["expires_at"] = time.time() + data["expires_in"]
return _token_cache["token"]
优化体系
| 层级 | 技术 | 效果 |
|---|---|---|
| 身份验证 | Visa/Mastercard DataOnly 3DS | 更高通过率，无质询摩擦 |
| 凭证 | 网络令牌（DPAN + 密码学凭证） | 发卡行信任、卡片生命周期连续性 |
| 设备 | A55Pay.getDeviceId() 指纹 | 更强的风控评分 |
| 可靠性 | 每次扣款使用幂等键 | 零重复扣款 |
| 效率 | 令牌缓存、连接池 | 更低延迟 |
永远不要记录敏感数据
记录完整 PAN 或 CVV 存在严重安全风险，会导致服务器上留存敏感数据。请使用关联 ID 进行链路追踪。
可观测性
跟踪从您的边缘到 A55 的 p95 延迟、按路由的错误率和 Webhook 交付延迟。在客户察觉之前发出告警。