试用安装包下载 | SMS | 在线演示
项目源码地址：https://github.com/openskeye/go-vss
1. 目标与适用范围
本文用于统一 Skeyevss 对外接口规范，覆盖：
- RESTful API（HTTP/JSON）
- gRPC API（服务间或对外高性能接口）
- 错误码与错误响应模型
适用对象：后端研发、前端研发、第三方对接方、测试。
2. 设计原则
- 统一语义：路径、方法、状态码语义一致
- 稳定兼容：对外版本可演进，不破坏旧客户端
- 错误可定位：错误码可检索、可追踪、可国际化
- 接口可治理：便于文档生成、监控、审计与告警
3. RESTful 规范
3.1 路径与资源命名
- 使用名词复数表示集合资源：
/devices、/channels、/alarms - 使用短横线分词：
/video-projects - 禁止在路径中使用动词（除少数动作型接口）
推荐：
GET /devices：查询设备列表GET /devices/{deviceUniqueId}：查询设备详情POST /devices：新增设备PUT /devices/{deviceUniqueId}：整体更新PATCH /devices/{deviceUniqueId}：局部更新DELETE /devices/{deviceUniqueId}：删除
动作型接口（无法自然资源化时）建议：
POST /channels/{channelUniqueId}:playPOST /channels/{channelUniqueId}:stop
3.2 HTTP 方法语义
| 方法 | 语义 |
|---|---|
| GET | 读取 |
| POST | 创建/触发动作 |
| PUT | 全量更新 |
| PATCH | 部分更新 |
| DELETE | 删除 |
3.3 查询、分页与过滤
项目当前已使用ReqParams（conditions/orders/limit/page/...）作为通用查询结构。
对外建议保持一致，并补充以下约束：
page >= 11 <= limit <= 200- 默认排序字段固定（避免随机顺序）
- 复杂过滤放请求体（POST list）时，接口文档必须给示例
3.4 统一响应模型（兼容当前实现）
项目当前响应模型（来自core/pkg/response/http.go）可归纳为：
{"timestamp":1762393485500,"node":"0-1","version":"V1.0.6","data":{},"cc":0.011,"message":"请求消息","token":"new-token-if-refresh","code":10000,"logout":false,"reset-pwd":false}规范建议：
data：成功时必有（可为true）code：业务码（可选，针对复杂场景，通常成功与失败使用http code判断）message：面向用户的可读信息errors：仅非生产环境（SKEYEVSS_SERVER_ENV_MODE=dev）返回详细栈信息（线上环境已加密，通过响应查询获取真实信息）
3.5 HTTP 状态码使用建议
项目现状以400/401/403为主，建议扩展为完整分层：
| 场景 | HTTP Code | 说明 |
|---|---|---|
| 参数错误 | 400 | 字段格式、范围错误 |
| 未登录/Token无效 | 401 | 鉴权失败 |
| 无权限 | 403 | 有身份但无访问权限 |
| 资源不存在 | 404 | 指定资源不存在 |
| 限流 | 429 | 请求过于频繁 |
| 服务异常 | 500 | 服务端未预期错误 |
| 网关/依赖超时 | 504 | 下游服务超时 |
4. gRPC 规范
4.1 服务定义原则
- 服务名使用领域化命名：
DeviceService、BackendService、ConfigService - 接口按“动作 + 资源”命名：
DeviceRow、DeviceUpsert、ChannelRowFind - 请求/响应消息清晰区分
Req/Resp/ListReq/ListResp
4.2 proto
版本升级时：
- 仅新增字段：同版本兼容
- 只做新增
4.3 字段兼容规则
- 禁止复用已删除字段 tag
- 新字段一律
optional语义（兼容旧客户端） - 时间字段统一毫秒时间戳
5. 错误码设计规范
5.1 双层错误模型
建议统一：
- 传输层错误：HTTP Code / gRPC Code
- 业务层错误：
code（整型）+message（可国际化）
先看 HTTP/gRPC 是否成功，再看业务码。
5.2 错误响应示例（REST）
{"timestamp":1762393485500,"node":"0-1","version":"V1.0.6","code":30000,"message":"等待设备注册","error":"error: ...","cc":0.008}5.5 gRPC 错误映射
| gRPC Code | 对应HTTP | 业务语义 |
|---|---|---|
| InvalidArgument | 400 | 参数错误 |
| Unauthenticated | 401 | 未登录/签名无效 |
| PermissionDenied | 403 | 无权限 |
| NotFound | 404 | 资源不存在 |
| AlreadyExists | 409 | 资源冲突 |
| DeadlineExceeded | 504 | 请求超时 |
| Internal | 500 | 服务内部异常 |
6. 鉴权与安全规范
6.1 REST 鉴权头
Authorization: <token>refreshToken: 1|0
6.2 安全建议
- 对外接口走 HTTPS
- 不在响应中暴露内部堆栈（生产环境）注意
SKEYEVSS_SERVER_ENV_MODE的值 - 敏感字段（密码、密钥）脱敏或不返回
7. 版本与兼容策略
7.1 REST 版本化
建议对外路径统一带版本：
/api/v1/devices/api/v1/channels
需要在开发中自行拓展
7.2 gRPC 版本化
通过 proto package 版本化（...v1/...v2）。
需要在开发中自行拓展
7.3 兼容原则
- 只增不改优先
- 废弃接口需标注
deprecated并给迁移窗口 - 重大变更需发布升级说明与变更清单
9. 落地步骤
- 建立统一错误码字典（从
localization映射开始） - 统一 REST 响应模板（成功码、错误码、message）
- 统一 gRPC 错误映射中间层
- 增加接口文档模板与评审门禁
- 对历史接口分批治理，不做一次性重构
10. 总结
对外 API 规范的核心不只是写文档，而是需要形成可执行约束：
- REST 与 gRPC 命名一致
- HTTP/gRPC 与业务错误码分层清晰
- 错误可观测、可国际化、可追踪
这能显著降低前后端联调成本和第三方接入成本，并提升线上问题定位效率。
