照着接口定义书实现 REST 对接

目标

阅读接口定义文档并据此实现 REST 客户端，同时具备发送前验证、错误码映射、超时处理和集成日志。

为什么重要

同步 REST 集成真正困难的并不是发起调用，而是对方响应缓慢或行为异常时如何处理。连接超时设置过长，对方的故障就会变成我方故障；如果没有为每个错误码规定处理措施，就可能把错误数据重发 100 次，或因临时故障而停止业务。此外，不做发送前验证，就会让对方系统日志堆满我方错误，引发集成人员之间无谓的情绪消耗。“坏数据应在我方拦截”是集成开发的基本礼仪。

步骤

阅读 /opt/lab/fixtures/eai/spec/IF-ORD-001.md，创建 /root/eai/spec.csv。第一行为 field,type,length,required。把定义文档中的全部请求字段按字段名升序写入。required 使用 Y/N。
启动对方系统。 python3 /opt/lab/fixtures/eai/rest/partner_api.py 9200（后台运行）把 http://127.0.0.1:9200/health 的响应保存到 /root/eai/health.json。status 值必须为 UP。
按定义文档向 POST /api/v1/orders 发送一笔正常订单，并把响应保存到 /root/eai/res-ok.json。resultCode 必须为 0000。
创建 /root/eai/validate.sh。接收一个参数（JSON 文件路径），按定义文档进行验证；没有问题时退出码为 0，有问题时在第一行输出原因，并以非 0 退出码结束。至少必须发现缺少必填项 / 长度超限 / 数值字段中包含字符这三类问题。
创建 /root/eai/errmap.csv。第一行为 code,meaning,action。写入定义文档中规定的所有响应码，action 为 재시도, 중단, 통보 之一。
http://127.0.0.1:9200/api/v1/slow 会延迟 5 秒响应。使用2 秒超时调用并使其失败，然后创建 /root/eai/timeout.txt。文件共两行。
```
exit_code=<curl 종료코드>
policy=<타임아웃 시 처리 방침 한 줄>
```
创建 /root/eai/send.sh。接收一个参数（订单号），按定义文档发起调用，并在第一行输出响应的 resultCode。值为 0000 时退出码为 0，否则以非 0 退出码结束。
创建 /root/eai/if.log。文件至少有3 行，每行包含以管道符（|）分隔的7 个字段。
```
시각|인터페이스ID|송신시스템|수신시스템|응답코드|소요ms|추적ID
```
接口 ID 为 IF-ORD-001，每行的跟踪 ID 必须互不相同。

参考

POST：curl -s -X POST -H 'Content-Type: application/json' -d @파일 <URL>
超时：curl --max-time 2 ... / 通过 $? 查看退出码
耗时：curl -w '%{time_total}'
常见错误 1：HTTP 200 就判断为成功。业务错误经常以 200 + resultCode 返回。
常见错误 2：按字符数验证长度。如果定义文档采用字节标准，就必须按字节计数。
常见错误 3：使用固定跟踪 ID。每次调用都必须不同，才能进行核对。

从定义文档提取字段

阅读 /opt/lab/fixtures/eai/spec/IF-ORD-001.md，创建 /root/eai/spec.csv。第一行为 field,type,length,required。把定义文档中的全部请求字段按字段名升序写入。required 使用 Y/N。

阅读定义文档，把必填/可选、类型和长度整理成表。该表将成为下一步验证逻辑的规格。

启动并确认对方系统

启动对方系统。 python3 /opt/lab/fixtures/eai/rest/partner_api.py 9200（后台运行）把 http://127.0.0.1:9200/health 的响应保存到 /root/eai/health.json。status 值必须为 UP。

集成开发的第一步始终是确认“对方是否存活”。如果有健康检查端点，应首先检查它。

正常调用

按定义文档向 POST /api/v1/orders 发送一笔正常订单，并把响应保存到 /root/eai/res-ok.json。resultCode 必须为 0000。

必须准确设置 Content-Type。请注意，响应码字段与 HTTP 状态码彼此独立——业务错误经常以 HTTP 200 返回。

发送前验证脚本

创建 /root/eai/validate.sh。接收一个参数（JSON 文件路径），按定义文档进行验证；没有问题时退出码为 0，有问题时在第一行输出原因，并以非 0 退出码结束。至少必须发现缺少必填项 / 长度超限 / 数值字段中包含字符这三类问题。

在我方拦截坏数据是集成开发的基本要求。请区分缺少必填项、长度超限和格式不符，并输出相应原因。

错误码映射表

创建 /root/eai/errmap.csv。第一行为 code,meaning,action。写入定义文档中规定的所有响应码，action 为 재시도, 중단, 통보 之一。

关键是为每个代码标注“重试/中止/通知”中的一种措施。缺少这一区分时，开发人员会选择全部重试或全部放弃。

重现超时

http://127.0.0.1:9200/api/v1/slow 会延迟 5 秒响应。使用2 秒超时调用并使其失败，然后创建 /root/eai/timeout.txt。文件共两行。

exit_code=<curl 종료코드>
policy=<타임아웃 시 처리 방침 한 줄>

curl 提供限制总时间的选项。预先确认超时时 curl 返回的退出码，便可在脚本中据此分支处理。

集成客户端脚本

创建 /root/eai/send.sh。接收一个参数（订单号），按定义文档发起调用，并在第一行输出响应的 resultCode。值为 0000 时退出码为 0，否则以非 0 退出码结束。

必须根据响应码返回不同退出码，调用方才能作出判断。请同时测试成功和失败情况。

集成日志标准

创建 /root/eai/if.log。文件至少有3 行，每行包含以管道符（|）分隔的7 个字段。

시각|인터페이스ID|송신시스템|수신시스템|응답코드|소요ms|추적ID

接口 ID 为 IF-ORD-001，每行的跟踪 ID 必须互不相同。

跟踪 ID 是与对方系统日志核对时唯一的关键。每次调用都必须不同，而且只有随请求一同发送才有意义。