76 lines
1.9 KiB
Markdown
76 lines
1.9 KiB
Markdown
# Fabric 错误码与重试策略 v1
|
||
|
||
## 1) 统一错误响应结构
|
||
所有非 2xx 响应建议返回：
|
||
|
||
```json
|
||
{
|
||
"error": {
|
||
"code": "FABRIC_XXX",
|
||
"message": "human readable",
|
||
"retryable": false
|
||
}
|
||
}
|
||
```
|
||
|
||
可选字段：
|
||
- `requestId`: 请求追踪 id
|
||
- `details`: 参数错误详情
|
||
|
||
---
|
||
|
||
## 2) 业务错误码（v1）
|
||
|
||
### 通用
|
||
- `FABRIC_BAD_REQUEST` → 400（参数不合法）
|
||
- `FABRIC_UNAUTHORIZED` → 401（认证失败）
|
||
- `FABRIC_FORBIDDEN` → 403（鉴权/签名失败）
|
||
- `FABRIC_NOT_FOUND` → 404（资源不存在）
|
||
- `FABRIC_CONFLICT` → 409（资源冲突/重复）
|
||
- `FABRIC_RATE_LIMITED` → 429（限流）
|
||
- `FABRIC_INTERNAL_ERROR` → 500（服务内部错误）
|
||
- `FABRIC_UNAVAILABLE` → 503（依赖不可用）
|
||
|
||
### Center↔Guild 协议
|
||
- `FABRIC_HMAC_MISSING_HEADERS` → 403
|
||
- `FABRIC_HMAC_INVALID_SIGNATURE` → 403
|
||
- `FABRIC_HMAC_TIMESTAMP_EXPIRED` → 403
|
||
- `FABRIC_NODE_ID_CONFLICT` → 409
|
||
- `FABRIC_NODE_ENDPOINT_CONFLICT` → 409
|
||
|
||
### Messaging
|
||
- `FABRIC_EDIT_WINDOW_EXPIRED` → 409
|
||
- `FABRIC_IDEMPOTENCY_REPLAY` → 200（命中幂等缓存，非错误）
|
||
|
||
---
|
||
|
||
## 3) 重试策略（客户端/插件侧）
|
||
|
||
### 可重试（指数退避）
|
||
- HTTP: `429`, `500`, `502`, `503`, `504`
|
||
- 网络异常：超时/连接重置/临时 DNS 故障
|
||
|
||
### 不可重试
|
||
- HTTP: `400`, `401`, `403`, `404`, `409`（除非业务明确允许）
|
||
|
||
### 退避规则
|
||
- 基础间隔：1s
|
||
- 退避序列：1s / 2s / 4s / 8s / 16s
|
||
- 最大重试次数：5
|
||
- 加抖动：`±20%`
|
||
- 若有 `Retry-After`：优先按 `Retry-After`
|
||
|
||
---
|
||
|
||
## 4) 幂等与重试配合
|
||
- 写接口重试必须带 `Idempotency-Key`
|
||
- 同 key 重放返回首次响应，避免重复写入
|
||
- 幂等记录建议至少保留 24h
|
||
|
||
---
|
||
|
||
## 5) 服务端落地建议
|
||
- 网关/中间件统一异常映射为标准 `error.code`
|
||
- 在日志中记录：`error.code`、`requestId`、`status`
|
||
- 对 429/503 返回 `Retry-After`
|