王绍宏
00c0a1fb7f
- 接入 NDRServer 告警和流量日志，支持凭据与任务管理 - 支持分页拉取、窗口拆分、调度优先级及 WAL 持久化后推进断点 - 增加迟到告警规则重放，优化多条泛化规则选择和事件时间处理 - 补充回归测试、数据库升级脚本及部署文档
67 lines
2.4 KiB
Markdown
67 lines
2.4 KiB
Markdown
# 设备 API 适配器开发说明
|
||
|
||
API 拉取代码放在 `syslog-serve`，不单独建 Maven 模块。
|
||
|
||
如果只是接入当前 NDRServer，不需要重新写整套拉取程序。先核对现有适配器是否缺少字段或接口参数，有差异时只修改 NDR 适配器。
|
||
|
||
## NDRServer
|
||
|
||
现有代码：
|
||
|
||
```text
|
||
syslog-serve/src/main/java/com/haobang/apipull/adapter/ndr/NdrServerApiAdapter.java
|
||
```
|
||
|
||
测试代码：
|
||
|
||
```text
|
||
syslog-serve/src/test/java/com/haobang/apipull/adapter/ndr/NdrServerApiAdapterTest.java
|
||
syslog-serve/src/test/java/com/haobang/apipull/adapter/ndr/NdrServerSpringWiringTest.java
|
||
```
|
||
|
||
现有 NDR 拉取实现如需补充特殊参数或字段处理，直接修改上述适配器和测试。定时任务、线程池、checkpoint 和 Kafka Producer 使用项目公共实现。
|
||
|
||
## 新厂商
|
||
|
||
新建厂商目录：
|
||
|
||
```text
|
||
syslog-serve/src/main/java/com/haobang/apipull/adapter/<vendor>/
|
||
```
|
||
|
||
实现 `ApiPullAdapter` 并加上 `@Component`。Spring 启动后会自动注册。
|
||
|
||
接口方法的作用：
|
||
|
||
| 方法 | 要返回什么 |
|
||
| --- | --- |
|
||
| `type()` | 厂商和协议版本的固定名称，例如 `VENDOR_X_V1` |
|
||
| `version()` | 当前代码的协议版本号 |
|
||
| `streams()` | 支持的日志类型，例如告警、流量日志 |
|
||
| `minimumWindowSeconds()` | 设备允许查询的最小时间范围 |
|
||
| `validateConfig()` | 检查地址、分页大小和超时时间 |
|
||
| `pull()` | 查询指定时间范围中的一页数据 |
|
||
|
||
适配器负责以下内容：
|
||
|
||
- 认证和 Token；
|
||
- 请求地址、参数和时间格式；
|
||
- 单页数据查询；
|
||
- 响应解析和厂商错误码；
|
||
- 事件时间、设备侧 ID 和平台事件 ID；
|
||
- 原始 JSON 及必要的兼容字段。
|
||
|
||
调度、并发、窗口拆分、checkpoint、WAL 和 Kafka 由公共代码处理。适配器不要直接写 Kafka，也不要自行推进 checkpoint。
|
||
|
||
如果新厂商不是 AppKey/AppSecret 认证，还需要一起调整凭据 DTO、`ApiCredentialService`、`DatabaseCredentialProvider` 和数据库脚本。
|
||
|
||
开发完成后至少检查：
|
||
|
||
1. 认证成功、认证失败和 Token 过期；
|
||
2. 接口返回空数据时任务能够正常推进；
|
||
3. 多页数据没有漏页；
|
||
4. 事件时间来自设备日志，不使用接口响应时间；
|
||
5. 同一条设备日志重复拉取时 `eventId` 保持不变；
|
||
6. 接口异常时 checkpoint 不推进；
|
||
7. 单元测试和 Spring 启动测试通过。
|