425 lines
9.9 KiB
Markdown
425 lines
9.9 KiB
Markdown
# 生产端配置同步接口文档 V1
|
||
|
||
## 1. 文档目的
|
||
|
||
本文档定义生产端提供给同步工具使用的接口协议，用于支持以下两类能力：
|
||
|
||
- 接收开发侧下发的配置包并导入生产环境
|
||
- 向同步工具提供当前生产环境配置快照
|
||
|
||
本文档面向：
|
||
|
||
- 生产端接口开发人员
|
||
- 同步工具开发人员
|
||
- 联调与运维人员
|
||
|
||
## 2. 适用范围
|
||
|
||
本文档适用于“基于 FTP 中转的配置双向同步工具”中的生产端接口。
|
||
|
||
当前接口版本：
|
||
|
||
- `V1`
|
||
|
||
生产端建议提供两个接口：
|
||
|
||
- `POST /api/config/push`
|
||
- `GET /api/config/pull`
|
||
|
||
## 3. 设计原则
|
||
|
||
- 接口必须可被自动化任务调用，不依赖人工交互
|
||
- `push` 必须具备幂等能力，避免重复导入
|
||
- `pull` 必须返回当前生产正在生效的配置快照
|
||
- 返回结果要足够明确，便于同步工具决定是否写 ACK
|
||
- 接口协议尽量简单，优先保证稳定性和可追踪性
|
||
|
||
## 4. 认证与安全
|
||
|
||
### 4.1 认证方式
|
||
|
||
建议使用：
|
||
|
||
- `Bearer Token`
|
||
|
||
请求头示例：
|
||
|
||
```http
|
||
Authorization: Bearer xxxxxxxxxxxxx
|
||
```
|
||
|
||
### 4.2 传输协议
|
||
|
||
建议使用：
|
||
|
||
- `HTTPS`
|
||
|
||
### 4.3 调用方
|
||
|
||
仅允许生产环境内部部署的 `prod-agent` 调用。
|
||
|
||
## 5. 公共约定
|
||
|
||
### 5.1 公共请求头
|
||
|
||
建议所有请求携带以下 Header：
|
||
|
||
| Header | 必填 | 说明 |
|
||
| --- | --- | --- |
|
||
| `Authorization` | 是 | Bearer Token |
|
||
| `Content-Type` | `push` 必填 | `multipart/form-data` |
|
||
| `Accept` | 否 | 推荐 `application/json` |
|
||
| `X-Trace-Id` | 否 | 同步链路跟踪号，可与报文中的 `traceId` 一致 |
|
||
|
||
### 5.2 公共响应体
|
||
|
||
除 `pull` 成功场景外，建议统一返回 JSON：
|
||
|
||
```json
|
||
{
|
||
"code": "SUCCESS",
|
||
"message": "Operation succeeded",
|
||
"traceId": "4ec9506b4edf438ab6b6f7764e2d1d28",
|
||
"timestamp": "2026-04-16T10:20:30+08:00",
|
||
"data": {}
|
||
}
|
||
```
|
||
|
||
字段说明：
|
||
|
||
| 字段 | 类型 | 说明 |
|
||
| --- | --- | --- |
|
||
| `code` | string | 业务码 |
|
||
| `message` | string | 说明信息 |
|
||
| `traceId` | string | 链路追踪号 |
|
||
| `timestamp` | string | 接口返回时间，ISO-8601 格式 |
|
||
| `data` | object | 业务数据 |
|
||
|
||
### 5.3 公共业务码
|
||
|
||
| code | 说明 |
|
||
| --- | --- |
|
||
| `SUCCESS` | 处理成功 |
|
||
| `ACCEPTED` | 已接收，异步处理中 |
|
||
| `INVALID_PARAM` | 参数错误 |
|
||
| `UNAUTHORIZED` | 认证失败 |
|
||
| `FORBIDDEN` | 无权限 |
|
||
| `DUPLICATE_REQUEST` | 重复请求 |
|
||
| `PACKAGE_VALIDATE_FAILED` | 包校验失败 |
|
||
| `CONFIG_IMPORT_FAILED` | 配置导入失败 |
|
||
| `CONFIG_NOT_FOUND` | 当前无可导出的生产配置 |
|
||
| `INTERNAL_ERROR` | 系统内部异常 |
|
||
|
||
说明：
|
||
|
||
- 当前同步工具实现更适合同步处理，因此 `push` 推荐返回 `SUCCESS`，不建议首版做异步。
|
||
|
||
## 6. 配置包约定
|
||
|
||
`push` 接口接收的文件建议为 zip 包，结构如下：
|
||
|
||
```text
|
||
package.zip
|
||
|- manifest.json
|
||
|- config/
|
||
|- sha256.txt
|
||
```
|
||
|
||
### 6.1 manifest.json 示例
|
||
|
||
```json
|
||
{
|
||
"traceId": "4ec9506b4edf438ab6b6f7764e2d1d28",
|
||
"direction": "DEV_TO_PROD",
|
||
"sourceEnv": "DEV",
|
||
"sourceVersion": "c1d2e3f4",
|
||
"contentHash": "b0f8f1d0ef7b7f0b8cb72a1cbf877f49d2d4073c8444a64eb8fd2e684cb7fe53",
|
||
"createdAt": "2026-04-16T10:18:00+08:00",
|
||
"packageName": "dev_to_prod-c1d2e3f4-4ec9506b4edf438ab6b6f7764e2d1d28.zip"
|
||
}
|
||
```
|
||
|
||
### 6.2 生产端校验要求
|
||
|
||
生产端在导入前建议至少执行以下校验：
|
||
|
||
1. zip 包可正常解压
|
||
2. `manifest.json` 存在且字段完整
|
||
3. `config/` 目录存在
|
||
4. `manifest.contentHash` 与实际内容哈希一致
|
||
5. `direction` 必须为 `DEV_TO_PROD`
|
||
6. 同一个 `traceId` 或同一个 `sourceVersion + contentHash` 不重复导入
|
||
|
||
## 7. 接口一：推送配置到生产
|
||
|
||
### 7.1 接口信息
|
||
|
||
- 方法：`POST`
|
||
- 路径：`/api/config/push`
|
||
- 说明：接收开发侧配置包并导入生产环境
|
||
|
||
### 7.2 请求格式
|
||
|
||
`Content-Type`：
|
||
|
||
- `multipart/form-data`
|
||
|
||
表单字段定义：
|
||
|
||
| 字段 | 类型 | 必填 | 说明 |
|
||
| --- | --- | --- | --- |
|
||
| `file` | file | 是 | 配置 zip 包 |
|
||
| `traceId` | string | 是 | 同步链路唯一标识 |
|
||
| `direction` | string | 是 | 固定为 `DEV_TO_PROD` |
|
||
| `sourceVersion` | string | 是 | 开发侧来源版本号，通常为 Git Commit ID |
|
||
| `contentHash` | string | 是 | 配置内容哈希 |
|
||
|
||
### 7.3 curl 示例
|
||
|
||
```bash
|
||
curl -X POST "https://prod.example.com/api/config/push" \
|
||
-H "Authorization: Bearer xxxxxxxxxxxxx" \
|
||
-H "Accept: application/json" \
|
||
-F "file=@dev_to_prod-c1d2e3f4-4ec9506b4edf438ab6b6f7764e2d1d28.zip" \
|
||
-F "traceId=4ec9506b4edf438ab6b6f7764e2d1d28" \
|
||
-F "direction=DEV_TO_PROD" \
|
||
-F "sourceVersion=c1d2e3f4" \
|
||
-F "contentHash=b0f8f1d0ef7b7f0b8cb72a1cbf877f49d2d4073c8444a64eb8fd2e684cb7fe53"
|
||
```
|
||
|
||
### 7.4 成功响应示例
|
||
|
||
```json
|
||
{
|
||
"code": "SUCCESS",
|
||
"message": "Configuration imported successfully",
|
||
"traceId": "4ec9506b4edf438ab6b6f7764e2d1d28",
|
||
"timestamp": "2026-04-16T10:20:30+08:00",
|
||
"data": {
|
||
"applied": true,
|
||
"sourceVersion": "c1d2e3f4",
|
||
"contentHash": "b0f8f1d0ef7b7f0b8cb72a1cbf877f49d2d4073c8444a64eb8fd2e684cb7fe53",
|
||
"importTime": "2026-04-16T10:20:30+08:00"
|
||
}
|
||
}
|
||
```
|
||
|
||
### 7.5 重复请求响应示例
|
||
|
||
```json
|
||
{
|
||
"code": "DUPLICATE_REQUEST",
|
||
"message": "The same package has already been applied",
|
||
"traceId": "4ec9506b4edf438ab6b6f7764e2d1d28",
|
||
"timestamp": "2026-04-16T10:20:35+08:00",
|
||
"data": {
|
||
"applied": true,
|
||
"sourceVersion": "c1d2e3f4",
|
||
"contentHash": "b0f8f1d0ef7b7f0b8cb72a1cbf877f49d2d4073c8444a64eb8fd2e684cb7fe53"
|
||
}
|
||
}
|
||
```
|
||
|
||
说明：
|
||
|
||
- 对同步工具而言，`DUPLICATE_REQUEST` 可以按成功处理。
|
||
|
||
### 7.6 失败响应示例
|
||
|
||
```json
|
||
{
|
||
"code": "PACKAGE_VALIDATE_FAILED",
|
||
"message": "Package content hash mismatch",
|
||
"traceId": "4ec9506b4edf438ab6b6f7764e2d1d28",
|
||
"timestamp": "2026-04-16T10:20:40+08:00",
|
||
"data": {}
|
||
}
|
||
```
|
||
|
||
### 7.7 HTTP 状态码建议
|
||
|
||
| HTTP 状态码 | 场景 |
|
||
| --- | --- |
|
||
| `200` | 导入成功或重复导入 |
|
||
| `400` | 参数缺失、方向错误、文件格式错误 |
|
||
| `401` | Token 无效 |
|
||
| `403` | 无权限 |
|
||
| `409` | 幂等冲突或状态冲突 |
|
||
| `422` | 包内容校验失败、配置业务校验失败 |
|
||
| `500` | 服务端异常 |
|
||
|
||
### 7.8 处理语义
|
||
|
||
`push` 接口建议采用同步处理语义：
|
||
|
||
1. 接收请求
|
||
2. 校验包
|
||
3. 导入并应用配置
|
||
4. 成功后返回 `200`
|
||
|
||
说明：
|
||
|
||
- 同步工具当前在收到 `2xx` 后会回写 FTP ACK，因此生产端若采用异步处理，会导致工具提前判定成功。
|
||
- 如后续要改异步，需要同时调整同步工具 ACK 逻辑。
|
||
|
||
## 8. 接口二：拉取生产配置快照
|
||
|
||
### 8.1 接口信息
|
||
|
||
- 方法：`GET`
|
||
- 路径：`/api/config/pull`
|
||
- 说明：返回当前生产环境已生效配置的快照
|
||
|
||
### 8.2 请求格式
|
||
|
||
当前 V1 版不要求请求参数。
|
||
|
||
curl 示例：
|
||
|
||
```bash
|
||
curl -X GET "https://prod.example.com/api/config/pull" \
|
||
-H "Authorization: Bearer xxxxxxxxxxxxx"
|
||
```
|
||
|
||
### 8.3 成功响应约定
|
||
|
||
成功时返回：
|
||
|
||
- `HTTP 200`
|
||
- `Content-Type: application/json;charset=UTF-8`
|
||
|
||
推荐响应头：
|
||
|
||
| Header | 必填 | 说明 |
|
||
| --- | --- | --- |
|
||
| `X-Config-Version` | 推荐 | 当前生产配置版本号 |
|
||
| `X-Config-Hash` | 推荐 | 当前配置内容哈希 |
|
||
| `ETag` | 可选 | 可作为版本标识备用 |
|
||
|
||
说明：
|
||
|
||
- 当前同步工具优先读取 `X-Config-Version`，其次读取 `ETag`，如果都没有则退化为以内容哈希作为版本号。
|
||
|
||
### 8.4 成功响应体示例
|
||
|
||
```json
|
||
{
|
||
"systemCode": "PAY_CENTER",
|
||
"version": "2026.04.16.01",
|
||
"profiles": [
|
||
{
|
||
"name": "default",
|
||
"items": [
|
||
{
|
||
"key": "feature.switch.payment",
|
||
"value": "true"
|
||
},
|
||
{
|
||
"key": "payment.timeout.seconds",
|
||
"value": "30"
|
||
}
|
||
]
|
||
}
|
||
]
|
||
}
|
||
```
|
||
|
||
### 8.5 成功响应头示例
|
||
|
||
```http
|
||
HTTP/1.1 200 OK
|
||
Content-Type: application/json;charset=UTF-8
|
||
X-Config-Version: 2026.04.16.01
|
||
X-Config-Hash: 3d96f8d4c6d6d7cfcb1dc3d2c335ad426376cf2f774ab5b5567f7f8e9b30b5d1
|
||
```
|
||
|
||
### 8.6 无配置场景示例
|
||
|
||
```json
|
||
{
|
||
"code": "CONFIG_NOT_FOUND",
|
||
"message": "No active production configuration found",
|
||
"traceId": "server-generated-trace-id",
|
||
"timestamp": "2026-04-16T10:30:00+08:00",
|
||
"data": {}
|
||
}
|
||
```
|
||
|
||
### 8.7 HTTP 状态码建议
|
||
|
||
| HTTP 状态码 | 场景 |
|
||
| --- | --- |
|
||
| `200` | 成功返回配置快照 |
|
||
| `204` | 无可导出配置 |
|
||
| `401` | Token 无效 |
|
||
| `403` | 无权限 |
|
||
| `500` | 服务端异常 |
|
||
|
||
说明：
|
||
|
||
- 当前同步工具对 `204` 尚未做专门分支处理，如果生产端预计长期存在“无配置”场景，建议工具侧后续补充兼容逻辑。
|
||
|
||
## 9. 幂等规则
|
||
|
||
### 9.1 push 幂等建议
|
||
|
||
生产端建议以下任一方式作为幂等判断条件：
|
||
|
||
1. `traceId`
|
||
2. `sourceVersion + contentHash`
|
||
|
||
建议优先：
|
||
|
||
- `traceId`
|
||
|
||
补充校验：
|
||
|
||
- 如果 `traceId` 相同但 `contentHash` 不同，应返回冲突错误，不允许覆盖
|
||
|
||
## 10. 审计建议
|
||
|
||
生产端建议记录以下审计信息：
|
||
|
||
- `traceId`
|
||
- 调用时间
|
||
- 调用方 IP
|
||
- 来源版本号
|
||
- 内容哈希
|
||
- 导入结果
|
||
- 失败原因
|
||
|
||
## 11. 联调建议
|
||
|
||
联调时建议优先确认以下内容：
|
||
|
||
1. `Authorization` 认证是否打通
|
||
2. `push` 是否按 `multipart/form-data` 接收
|
||
3. `pull` 是否返回原始 JSON 字节流
|
||
4. `X-Config-Version` 是否稳定返回
|
||
5. 重复请求是否能幂等处理
|
||
|
||
## 12. 与当前同步工具实现的对应关系
|
||
|
||
当前同步工具中的生产接口调用实现文件为：
|
||
|
||
- [ProdConfigApiService.java](e:/AIcoding/FtpTool/src/main/java/com/ftptool/sync/service/ProdConfigApiService.java)
|
||
|
||
目前工具侧已按以下假设实现：
|
||
|
||
- `push` 使用 `POST + multipart/form-data`
|
||
- `pull` 使用 `GET`
|
||
- `pull` 成功后将响应体直接保存为本地文件 `prod-config.json`
|
||
- `pull` 优先从 `X-Config-Version` 或 `ETag` 中提取版本号
|
||
|
||
因此本接口文档与当前工具实现是兼容的。
|
||
|
||
## 13. 后续可扩展项
|
||
|
||
后续如需增强，可在 V2 中考虑：
|
||
|
||
- `push` 增加签名校验
|
||
- `pull` 支持增量拉取
|
||
- `pull` 增加查询参数，如 `systemCode`、`profile`、`version`
|
||
- `push` 增加灰度导入、预校验模式
|
||
- 增加 `/api/config/validate` 预校验接口
|