HTTP 约定#

外部 HTTP 路径由服务 servlet context 与 Controller 映射共同组成。base URL、方法、Content-Type、参数位置和实际序列化均是端点级事实，不能按路径名称或旧文档推断；唯一权威源是清单层（data-service 端点清单、device-service 端点清单）与 Swagger 视图，请求/响应结构通则见 API 域规范页（data-service、device-service）。

常规响应的公共底座为 timestamp、status、error、localizedError、path、extraData 和 data。data 的形状由操作决定；extraData 可能由服务端补充，不能把任一响应样例当作固定全局结构。上传 Tus 等明确协议例外会直接处理 servlet response，不套用此响应底座。

HTTP status 与 JSON status 是两层信号。调用方不能仅以 HTTP 2xx 判成功，也不能假定任意失败均有 JSON body 或公共顶层 message。当前已知出口及适用边界见错误响应差异。

分页操作通常将列表置于 data，分页计数置于 extraData；请求参数、默认值、页长边界、排序和空结果语义以清单层与 Swagger 的端点级行为为准，通用查询控制字段（sqlQueryLimit 等）的语义见相应模块 business 页。

依据#

适用后端基线：源码归纳 @ 2026-09-14。响应信封底座、Tus 上传的响应例外与分页字段位置均为源码归纳结论。错误出口定位见错误响应差异。