试用安装包下载 | SMS | 在线演示

项目源码地址：https://github.com/openskeye/go-vss

---

1. 目标与适用范围

本文用于统一 Skeyevss 对外接口规范，覆盖：

• RESTful API（HTTP/JSON）
• gRPC API（服务间或对外高性能接口）
• 错误码与错误响应模型

适用对象：后端研发、前端研发、第三方对接方、测试。

---

2. 设计原则

1. 统一语义：路径、方法、状态码语义一致
2. 稳定兼容：对外版本可演进，不破坏旧客户端
3. 错误可定位：错误码可检索、可追踪、可国际化
4. 接口可治理：便于文档生成、监控、审计与告警

---

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}:play
• POST /channels/{channelUniqueId}:stop

---

3.2 HTTP 方法语义

方法	语义
GET	读取
POST	创建/触发动作
PUT	全量更新
PATCH	部分更新
DELETE	删除

---

3.3 查询、分页与过滤

项目当前已使用 ReqParams（conditions/orders/limit/page/...）作为通用查询结构。
对外建议保持一致，并补充以下约束：

• page >= 1
• 1 <= 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 双层错误模型

建议统一：

1. 传输层错误：HTTP Code / gRPC Code
2. 业务层错误：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. 落地步骤

1. 建立统一错误码字典（从 localization 映射开始）
2. 统一 REST 响应模板（成功码、错误码、message）
3. 统一 gRPC 错误映射中间层
4. 增加接口文档模板与评审门禁
5. 对历史接口分批治理，不做一次性重构

---

10. 总结

对外 API 规范的核心不只是写文档，而是需要形成可执行约束：

• REST 与 gRPC 命名一致
• HTTP/gRPC 与业务错误码分层清晰
• 错误可观测、可国际化、可追踪

这能显著降低前后端联调成本和第三方接入成本，并提升线上问题定位效率。