shanshanzhong
4b6fcb338e
All checks were successful
Build docker and publish / build (20.15.1) (push) Successful in 7m15s
重构设备解绑逻辑，简化事务处理流程并移除冗余代码。将错误上报接口的详细说明从主文档拆分到单独文件，提高文档可维护性。 - 合并设备查询与认证记录查询操作 - 简化匿名用户创建流程 - 移除冗余的错误日志记录 - 将错误上报接口文档拆分到单独文件
102 lines
4.2 KiB
Markdown
102 lines
4.2 KiB
Markdown
# 客户端错误上报接口文档
|
||
|
||
## 接口概览
|
||
- 路径：`POST /v1/common/log/message/report`
|
||
- 说明：APP/PC/Web 客户端错误与异常信息上报，服务端入库 `log_message` 表，并提供管理端查询。
|
||
- 认证：无需登录；若走设备安全通道需使用 `Login-Type: device` 与 AES 加密。
|
||
- 中间件：`DeviceMiddleware`（当请求头 `Login-Type=device` 时启用加解密）。
|
||
|
||
## 请求
|
||
- Headers：
|
||
- `Content-Type: application/json`
|
||
- 可选：`Login-Type: device`（启用设备加密通道）
|
||
- Body（JSON）：
|
||
- `platform` string 必填，客户端平台，如 `android`/`ios`/`windows`/`mac`/`web`
|
||
- `appVersion` string 可选，应用版本，如 `2.4.1`
|
||
- `osName` string 可选，系统名称，如 `Android`/`iOS`/`Windows`/`macOS`
|
||
- `osVersion` string 可选，系统版本，如 `14`
|
||
- `deviceId` string 可选，设备唯一标识
|
||
- `sessionId` string 可选，会话标识
|
||
- `level` uint8 可选，日志等级：`1=fatal`、`2=error`、`3=warn`、`4=info`（默认 `3`）
|
||
- `errorCode` string 可选，业务或系统错误码
|
||
- `message` string 必填，错误简述（服务器将超过约 64KB 的内容截断）
|
||
- `stack` string 可选，堆栈信息（服务器将超过约 1MB 的内容截断）
|
||
- `context` object 可选，扩展上下文（如接口路径、参数、网络状态等）
|
||
- `occurredAt` int64 可选，客户端发生时间，毫秒时间戳
|
||
|
||
- 服务器侧自动填充：
|
||
- `client_ip`、`user_agent`、`locale` 由请求解析
|
||
- `user_id` 仅在鉴权后由服务端注入（本接口默认匿名）
|
||
|
||
## 加密通道（设备）
|
||
- 当使用设备安全通道时（`Login-Type: device`），请求体需要将原始 JSON 加密为：
|
||
- `data` string：AES 加密后的密文
|
||
- `time` string：IV/nonce（与密文配套）
|
||
- 服务端会自动解密为明文 JSON，再进行字段校验与入库。
|
||
|
||
## 响应
|
||
- 成功：
|
||
```
|
||
{
|
||
"code": 0,
|
||
"msg": "OK",
|
||
"data": { "id": 123 }
|
||
}
|
||
```
|
||
- 常见错误：
|
||
- `{"code":401,"msg":"TooManyRequests"}` 触发速率限制（设备ID或IP维度）
|
||
- `{"code":400,"msg":"InvalidParams"}` 参数校验失败（缺少必填或类型不符）
|
||
- `{"code":10001,"msg":"DatabaseQueryError"}` 数据库操作异常
|
||
|
||
## 速率限制
|
||
- 默认按 `deviceId` 或 `client_ip` 每分钟最多约 `120` 条，超限即返回 `TooManyRequests`。
|
||
|
||
## 去重策略
|
||
- 服务端计算 `digest = sha256(message|stack|errorCode|appVersion|platform)` 并尝试唯一入库，重复日志可能返回已存在记录的 `id`。
|
||
|
||
## 示例
|
||
- 明文上报（推荐测试使用）：
|
||
```
|
||
curl -X POST http://localhost:8080/v1/common/log/message/report \
|
||
-H 'Content-Type: application/json' \
|
||
-d '{
|
||
"platform": "android",
|
||
"appVersion": "2.4.1",
|
||
"osName": "Android",
|
||
"osVersion": "14",
|
||
"deviceId": "and-9a7f3e2c-01",
|
||
"sessionId": "sess-73f8a2a4",
|
||
"level": 2,
|
||
"errorCode": "ORDER_RENEWAL_TIMEOUT",
|
||
"message": "订单续费接口超时：/v1/public/order/renewal",
|
||
"stack": "TimeoutException: request exceeded 8000ms\\n at HttpClient.post(HttpClient.kt:214)\\n at RenewalRepository.submit(RenewalRepository.kt:87)",
|
||
"context": {
|
||
"api": "/v1/public/order/renewal",
|
||
"method": "POST",
|
||
"endpoint": "https://api.example.com/v1/public/order/renewal",
|
||
"httpStatus": 504,
|
||
"responseTimeMs": 8123,
|
||
"retryCount": 2,
|
||
"network": { "type": "cellular", "carrier": "China Mobile" }
|
||
},
|
||
"occurredAt": 1733200005123
|
||
}'
|
||
```
|
||
|
||
- 设备加密上报（示意）：
|
||
```
|
||
# 将原始JSON通过AES加密得到密文data与随机IV time
|
||
curl -X POST http://localhost:8080/v1/common/log/message/report \
|
||
-H 'Content-Type: application/json' \
|
||
-H 'Login-Type: device' \
|
||
-d '{"data":"<aes_cipher>","time":"<iv_nonce>"}'
|
||
```
|
||
|
||
## 管理端查询（用于联调验证）
|
||
- 列表：`GET /v1/admin/log/message/error/list`（需 `Authorization`）
|
||
- 详情：`GET /v1/admin/log/message/error/detail?id=...`
|
||
|
||
## 备注
|
||
- 字段尽量避免携带敏感信息（密码、密钥、完整令牌等）；如需调试请截断或脱敏后上报。
|
||
- 建议在 APP/PC 端统一封装上报模块，包含：字段收集、级别过滤、采样策略、离线缓存与重试、速率限制配合。
|