通用约定（Conventions）

所有接口的共性规则集中在这里，具体接口文档不再重复。

1. Base URL 与前缀

• 默认：http://127.0.0.1:27660/api/v1
• 文档里写成 {base}；SDK 自动补 / 结尾
• 三种子前缀：

系统级根路径：

2. HTTP 方法

• cmd 接口（路径形如 /api/v1/map/cmd/<cmd>/<mapid>/<version>）既接受 GET 也接受 POST；网关 Router.Any 统一挂载。SDK 默认走 POST，原因：
  1. 请求体大时 GET 超长
  2. 语义上是"动作"而非"只读资源"
• 其它接口遵循标准 REST：GET 查、POST 创建、PUT 修改、DELETE 删除

3. 鉴权

详情见 03-authentication.md。

• 必带：token=<JWT>（推荐放 query，也可放 header）
• 加密图：请求头 secretKey: <key1>_;_<key2>... 或 query secret_key=...
• 全局 access key（ak 开头 18 位）：可放在 accessKey 位置用来一次性访问多张加密图

4. 路径占位符

重要：SDK 会对占位符做 encodeURIComponent，别再手动编码。

5. 请求体约定

6. 响应结构

两类并存，SDK 都能识别：

6.1 web服务 网关标准响应

{
  "code": 0,
  "msg": "",
  "data": { /* 实际内容 */ }
}

• code == 0 → SDK unwrap 成 data
• code != 0 → SDK 抛 VjmapError(status=200, body={...})

6.2 图形服务

{
  "bounds": [...],
  "layers": [...],
  ...
}

直接返回，不包 {code,msg,data}。

6.3 错误响应

• HTTP 4xx / 5xx：SDK 抛 VjmapError(status=4xx|5xx, url, body)
• cmd 执行失败但网关路由成功：多数 cmd 用 {error: "..."} 或 {result: {succeed: false}} 表达；SDK 不会自动判断业务成功/失败，请业务侧自行校验

7. 分页 / 列表

大部分列出接口没有分页，一次返回全部：

• listmaps：按 mapid 聚合，返回 {mapid: [ {version, db, filename, ...} ]}
• symbol/list/{cat}：数组
• getWorkspace：数组

少数有 limit / offset / pageSize / pageNum（例如 fullsearch/search），每个接口文档单独说明。

8. 幂等性与重试

SDK 不内置重试；

9. 超时

• SDK 默认 60 秒；超长 cmd（composeNewMap、saveOfflineTileDb、extractTable on 大图）可能要 3-5 分钟，调用时显式 timeout=300（秒）。
• 图形服务单请求默认 600000 ms = 10 min（runstatus.process.reqTimeout），超过会被强杀。

10. 文件下载 / 流式接口

导出 PDF、DXF、离线瓦片包、缩略图等接口返回 二进制流。SDK 里对应方法：

• Python：svc._request("POST", url, stream=True) 返回原始 requests.Response，自己 .iter_content() 写文件
• Node：svc._request('POST', url, { stream: true }) 返回原始 Response，自己 await res.arrayBuffer() 或管道到文件

11. 命名风格（跨语言）

12. 日志与可观测

• runstatus?detail=true：看引擎 pid、活跃请求、子进程等
• viewlogs?record=100：看最近 100 条日志；含 cmd 耗时、错误