【ZTAPI × Moya】交易所 REST 协议与 iOS 网络抽象层：该比什么、怎么用？
基于上次有反馈说尝试下ZTAPI，而不是用Moya、Alamofire。特意出一期比较，到头来发现没有什么可比性，因为这两者不是一个纬度的，ZTAPI只是一个接口文档，并不是一个 iOS 三方库。但是看也看了，顺便出一期文章吧～
前置知识：REST 是什么？
REST（Representational State Transfer，表述性状态转移）是一种 Web API 的架构风格，不是具体的协议或库。它由 Roy Fielding 在 2000 年的博士论文中提出，核心思想是：
| 核心概念 | 说明 |
|---|---|
| 资源（Resource） | 每个 URL 代表一个资源，如 /api/v1/tickers 代表“所有交易对行情” |
| HTTP 动词 | 用 GET（查）、POST（增）、PUT（改）、DELETE（删）表达操作意图 |
| 无状态 | 每次请求携带完整信息，服务端不保留会话上下文 |
| JSON 响应 | 返回结构化数据，客户端自行解析渲染 |
简单说：REST = 用标准 HTTP 方法 + URL 路径来操作服务端资源，返回 JSON。ZTAPI 就是一套遵循 REST 风格的交易所开放接口。
一、先把概念对齐：两者不是「二选一」
| 名称 | 本质 | 类比 |
|---|---|---|
| ZTAPI（本文指 ZT 交易所开放文档 中的 HTTP API） | 服务端规定的 URL、参数、签名规则、返回 JSON 结构 | 「菜单 + 点餐规则」 |
| Moya | iOS 里基于 Alamofire 的客户端封装库，用 TargetType 把每个接口变成类型安全的枚举 | 「后厨标准化出餐流程」 |
因此：ZTAPI 描述「调什么」；Moya 描述「在 App 里怎么组织这次调用」。
你要做的是：用 URLSession / Alamofire / Moya 等客户端技术，实现 ZTAPI 文档里的请求；Moya 只是其中一种更利于工程化的写法。
二、ZTAPI 要点（基于公开文档归纳）
1. 接入与请求形态
- 域名：文档提供海外 / 大陆等入口（以官网最新为准，Demo 使用文档中出现的
https://www.ztbzh.net仅作示例）。 - 请求：支持 GET/POST；POST 时常为
application/x-www-form-urlencoded。 - 必选请求头：
X-SITE-ID: 1（文档明确要求）。 - 接口类型：
- 公共接口（如行情）：一般无需
api_key/sign。 - 私有接口（账户、下单等）：需要
api_key+ 按文档对参数做 MD5 签名 等。
- 公共接口（如行情）：一般无需
2. 公共行情示例
GET /api/v1/tickers：返回多交易对行情（文档中有响应字段说明）。- 适合作为 Demo：无密钥、逻辑简单，便于和 Moya 写法对照。
3. 私有接口与签名（概念）
文档给出思路：对 POST 业务参数排序拼接，再拼接 secret_key，MD5 大写十六进制 得到 sign。
在 iOS 用 Moya 时，常见做法是：
- 用 Plugin 或 自定义
Task/参数构建 统一注入api_key与sign； - 绝不把 Secret 写进客户端仓库或前端；生产环境应以后端代理或安全环境为准。
三、Moya 能帮你解决什么（相对「手写 URLSession」）
- 一个枚举 case 对应一个接口：
path、method、parameters、headers集中维护，减少字符串散落。 - 与业务模型解耦：
response.map(T.self)解码路径清晰。 - 插件链：日志、Token、将来接 ZT 签名 都可以插件化。
- 测试：
sampleData+StubbingProvider可离线测解码与 UI。
ZTAPI 本身不提供这些能力——它只是 HTTP 契约；Moya 是 Swift 侧的实现与组织方式。
四、差异对照表
| 维度 | ZTAPI（交易所 REST） | Moya（iOS 库） |
|---|---|---|
| 所在层次 | 服务端 API 规范 | 客户端网络封装 |
| 是否依赖 Swift | 否，任意语言可调 | 是，Swift + Alamofire |
| 认证 | 公共行情无；私有接口要 key + sign | 无内置「交易所签名」，需自写 Plugin/拼接 |
| 版本演进 | 随交易所文档变更 | 随 CocoaPods/SPM 版本 |
| 典型用途 | 行情、交易、订单 | 任意后端（含把 ZT 当作普通 REST 调） |
五、使用场景建议
| 场景 | 建议 |
|---|---|
| 学习 REST、对照文档练手 | 先用 URLSession 调通公共 tickers，再改 Moya TargetType 复现同一请求，理解分层。 |
| 公司内部业务后端（非交易所） | 优先 Moya（或同类） 统一工程内所有 TargetType，与 ZT 无关。 |
| 正式接入交易所私有接口 | 密钥与签名放服务端；App 只调自家网关，或严格安全审计后再直连；客户端可用 Moya + Plugin 减少重复代码。 |
| 仅需行情展示、无交易 | 公共接口 + Moya 即可；注意频率限制与合规。 |
六、安全与合规
- 交易与资产相关能力涉及高风险，务必阅读交易所最新条款与本地法规。
- 不要在示例或生产代码中硬编码 API Secret；文档中的签名示例仅作理解算法之用。
- 生产环境优先 服务端聚合行情/交易，App 只访问自家域名。
七、延伸阅读
- ZT 官方 API 文档：zt-global.github.io/ztapi/cn/
- Moya 官方仓库：github.com/Moya/Moya
文档中的域名、路径与签名规则以 ZT 官方最新说明为准；本文仅用于技术学习。
