58 lines
2.4 KiB
Markdown
58 lines
2.4 KiB
Markdown
# 文件格式转换示例
|
||
|
||
本例使用独立 Go SDK 提交一份小型 CSV 文件快照，由真实 Worker 转换成 JSON 文件正文，再查询平台权威结果。它只演示通用的任务受理、处理器版本、执行授权和结果确认，不包含行业规则或接入方项目名称。
|
||
|
||
## 前置
|
||
|
||
需要当前迁移、已启动 Orbit 服务，以及具备任务提交/读取和 Worker 消费权限的专用凭据。凭据文件应只保存在本地受保护目录：
|
||
|
||
```sh
|
||
cd sdk/go
|
||
ORBIT_URL=http://127.0.0.1:8080 \
|
||
ORBIT_CREDENTIALS_FILE=../../.local/worker.credentials.json \
|
||
go run ./examples/file-conversion
|
||
```
|
||
|
||
## 调用链与预期
|
||
|
||
示例生成独立的运行身份和处理器能力，提交以下输入：
|
||
|
||
```json
|
||
{
|
||
"file_name": "records.csv",
|
||
"content": "name,amount\nalpha,2\nbeta,3\n",
|
||
"target_format": "json"
|
||
}
|
||
```
|
||
|
||
Worker 使用固定的 `file.convert.csv-json` 处理器版本完成转换。预期输出类似：
|
||
|
||
```text
|
||
input=records.csv output=records.json rows=2 state=SUCCEEDED worker_drained=true
|
||
```
|
||
|
||
任务结果中的 `content` 是：
|
||
|
||
```json
|
||
[{"amount":"2","name":"alpha"},{"amount":"3","name":"beta"}]
|
||
```
|
||
|
||
提交键由本次运行身份和场景组成；网络结果不明时必须复用相同提交键查询，不能生成随机新键。示例只执行一次处理器，Worker 结束前等待排空，任务和审计历史保留。
|
||
|
||
## 生产接入边界
|
||
|
||
示例将小文件正文放在任务 JSON 中，方便隔离运行和回归。生产大文件应由业务侧先保存到受控对象存储，再把不可变对象引用、格式和业务操作键放入任务；处理器需要使用上下文取消、对象版本和业务幂等键，不能把 `AttemptID` 当作跨尝试的业务幂等键。
|
||
|
||
如果处理器在外部写入后失去连接，普通错误只能报告未知效果，接入方应使用查询或证据核对；不能因为 HTTP 或 Worker 回执超时就再次生成文件。平台保存的是任务结果快照，不替代业务对象存储、病毒扫描、权限策略或归档策略。
|
||
|
||
## 回归
|
||
|
||
单元转换校验：
|
||
|
||
```sh
|
||
cd sdk/go
|
||
GOWORK=off go test ./examples/file-conversion
|
||
```
|
||
|
||
`make integration` 会在一次性 MySQL 和真实 Orbit HTTP 服务上运行该示例，确认提交、Worker 执行、结果查询和排空均通过。该场景不证明外部对象存储的持久性，也不替代生产容量、故障切换或 RPO/RTO 验收。
|