dark/FtpTool
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

补充pi文档

Browse Source
This commit is contained in:
dark 2026-04-16 10:57:48 +08:00
parent bd1e4fa69a
commit 064a68d2a3
1 changed files with 424 additions and 0 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

424
docs/prod-api-v1.md Normal file
View File

@ -0,0 +1,424 @@
# 生产端配置同步接口文档 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` 预校验接口