SkeyeVSS国标信令中心服务中HTTP服务架构设计

本文说明core/app/sev/vss信令服务中REST/JSON HTTP API的分层结构：Gin 引擎、全局中间件、/api路由组、泛型 Handler 与业务 Logic 契约，以及与SIP、流媒体（MS）、设备 RPC的协作关系。

源代码 点击直达

一、在整体进程中的位置

二、分层结构总览

三、Server 层：中间件与路由组

3.1 全局中间件（所有路径）

在router.Use中：

• CORS：Access-Control-Allow-Origin: *、Methods/Headers*、预检缓存Max-Age等。
• JSON 倾向：c.Set("content-type", "application/json")。
• OPTIONS：直接204 No Content并Abort，便于浏览器跨域预检。

当前未默认启用gin.Logger()，生产日志依赖项目统一logx/ 业务日志。

3.2/api组

varaipGroup=router.Group("/api")aipGroup.Use(interceptor.HttpHeader(),interceptor.Timeout(time.Duration(Config.Timeout)*time.Millisecond))httpHandler.RegisterApiHandlers(svcCtx,aipGroup)

• HttpHeader()：现为透传Next()，可扩展为统一鉴权/Trace 等。
• Timeout(Config.Timeout)：对每个请求启 goroutine 执行c.Next()，超时则AbortWithStatusJSON(408, {"error":"request timeout"})。
  • Config.Timeout来自VssSevConfig.Timeout（core/tps/conf/config.go，字段与 YAML 一致，在代码中与time.Millisecond相乘，以实际配置文件为准，常见为毫秒量级整型）。
  • 注意：与「单接口长时间阻塞」（如设备录像轮询）需结合业务评估是否应调大超时或拆异步。

3.3 路由注册表

所有 HTTP 业务路由集中在internal/handler/http/routers.go的RegisterApiHandlers，按领域分组：

完整路径以各 Logic 的Path()为准（例如GET /api/status、POST /api/video/stream等）。

四、Handler 层：泛型适配与统一响应

4.1 两种入口

定义于internal/handler/http/handler.go：

1. newHandlerWithParams[Req, Logic]

   • 使用httpx.Parse将 Query / Path / JSON Body 绑定到Req。
   • 调用logic.New(ctx, c, svcCtx).DO(req)。

2. newHandler[Logic]（无请求体）

   • 直接logic.New(...).DO()，适用于纯GET或参数仅从 Path/Query 由 Logic 自行读取的场景（若仍用httpx.Parse需在 Logic 内处理，当前部分接口为无参DO()）。

4.2 Context 注入

在调用New之前向context.Context写入：

业务可通过contextx.GetIsInternalReq(ctx)读取（例如internal/pkg/ms/api.go中按内外网区分行为）。

4.3 统一响应toResp

Logic 返回types.HttpResponse：

typeHttpResponsestruct{Datainterface{}Err*response.HttpErr}

• Err != nil：response.New().RequestError(...)，携带统一错误语义与localization码。
• Data != nil：Success写出业务数据。
• 两者皆无 /resp == nil：成功但 body 为nil。

Handler 顶层有recover， panic 时打栈日志，避免进程崩溃（与 Gin 默认行为叠加，以实际为准）。

五、Logic 层契约（接口驱动）

定义于internal/types/types.go：

typeHttpHandleLogicBase[Logic any]interface{Path()stringNew(ctx context.Context,c*gin.Context,svcCtx*ServiceContext)Logic}typeHttpRHandleLogic[Logic,Req any]interface{HttpHandleLogicBase[Logic]DO(req Req)*HttpResponse}typeHttpEHandleLogic[Logic any]interface{HttpHandleLogicBase[Logic]DO()*HttpResponse}

约定习惯：

• 每个接口一个单例指针（如StatusLogic、VVideosLogic），在routers.go中传给newHandler/newHandlerWithParams。
• New注入ctx、gin.Context、ServiceContext，便于读 Header、访问RPC/Redis/配置。
• DO只做业务，不直接操作c.JSON，保持可测与响应格式统一。

编译期检查：Logic 文件内常见：

var_types.HttpEHandleLogic[*statusLogic]=(*statusLogic)(nil)

六、导航代码

6.1video：播放与流信息

对接 VSS 内部能力与 MS/VSS 协作，如StreamPlayLogic生成播放相关能力、StreamStopLogic停止会话等（具体见各文件DO）。

6.2gbs：国标信令侧 HTTP 触发

将 HTTP 转为channel 消息或SIP 发送（如 Catalog、Invite、StopStream、订阅、回放控制），与internal/logic/gbs_proc协程配合。

6.3ms：流媒体运维与查询

HTTP 代理调用MS 的 HTTP API（internal/pkg/ms），如 all_groups、query_by_names、reload 等；部分逻辑结合contextx.GetIsInternalReq。

6.4notify：流媒体事件回调

MS/边缘服务向 VSSPOST各类事件；公共逻辑在notify/common.go（如setStreamState：解析stream_name、校验通道存在、更新状态/保活）。与stream.New().Parse、设备 RPC强相关。

6.5onvif：探测与元数据

设备发现、Profile 等，配置依赖Config.Onvif。

6.6base：状态与辅助

• /status：返回绑定地址、HTTP/SIP 端口、部分 SIP 参数（便于探活与运维）。
• /device-videos：设备录像查询（SIP RecordInfo 聚合，见专项文档）。
• /ws-token：签发 WebSocket 子协议用 Token。

七、与 WebSocket / SSE 的关系

HTTP 中的/ws-token为 WebSocket 握手提供 Token，形成HTTP 辅助 + WS 长连接的组合。

八、扩展新接口的步骤建议

1. 在internal/types（或现有 types 文件）增加请求/响应结构体（若需要）。
2. 在internal/logic/http/<domain>新增xxxLogic，实现HttpRHandleLogic或HttpEHandleLogic，实现Path()与DO。
3. 在internal/handler/http/routers.go中router.GET/POST(..., newHandler...)注册。
4. 若需全链路超时，确认Config.Timeout是否足够；超长任务考虑异步化或单独调大（并评估Timeout中间件对 goroutine 的影响）。
5. 若依赖内部调用方Referer，注意网关/反向代理是否改写Referer，以免影响GetIsInternalReq。

九、设计要点小结

1. 前缀统一：对外 JSON API 集中在/api，与端口、文档、网关规则一致。
2. 契约清晰：Path+New+DO+HttpResponse，Handler 处理器、Logic 业务逻辑。
3. 解析统一：有 body 的接口优先httpx.Parse，减少手写ShouldBind。
4. 横切能力：CORS、OPTIONS、超时、（可扩展）Header 中间件；Context 注入 IP 与内部请求标记。
5. 领域分包：gbs/video/ms/notify/onvif/base边界清楚，notify与 MS 生命周期绑定紧密。

十、相关源码索引

可与《SkeyeVSS中WebSocket代码架构设计》对照阅读：二者共享ServiceContext，但监听端口与协议模型不同。