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

本文说明core/app/sev/vss信令服务中REST/JSON HTTP API的分层结构Gin 引擎、全局中间件、/api路由组、泛型 Handler 与业务 Logic 契约以及与SIP、流媒体MS、设备 RPC的协作关系。源代码 点击直达一、在整体进程中的位置项目说明启动main.go中go server.NewHttpSev(svcCtx).Start()与SIPTCP/UDP、SSE、WebSocket并行运行。监听: Config.Http.Port仅端口绑定0.0.0.0由 Gin 默认行为决定。框架Gingin.New()默认ReleaseMode。API 前缀业务接口统一挂在/api下见internal/server/http.go。二、分层结构总览internal/logic/http/*internal/handler/httpHttpSev.Startgin.New()全局: CORS OPTIONSGroup /apiHttpHeader TimeoutRegisterApiHandlersnewHandler / newHandlerWithParamshttpx.Parse - ReqContext: IP IsInternalReqtoResp(HttpResponse)base / video / ms / gbs / onvif / notify层级路径职责Serverinternal/server/http.go创建 Engine、挂中间件、注册/api、监听端口。Handlerinternal/handler/http/handler.go、routers.go解析请求、注入Context、调用 Logic、统一写出 JSON。Logicinternal/logic/http/{base,video,ms,gbs,onvif,notify}具体业务实现Path()New()DO()契约。Interceptorinternal/interceptor/http.go/api组内超时及预留 Header Hooks。类型与上下文internal/types/types.go、internal/svc/service_context.goHttpResponse、HttpRHandleLogic/HttpEHandleLogic、ServiceContext。三、Server 层中间件与路由组3.1 全局中间件所有路径在router.Use中CORSAccess-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组varaipGrouprouter.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.Timeoutcore/tps/conf/config.go字段与 YAML 一致在代码中与time.Millisecond相乘以实际配置文件为准常见为毫秒量级整型。注意与「单接口长时间阻塞」如设备录像轮询需结合业务评估是否应调大超时或拆异步。3.3 路由注册表所有 HTTP 业务路由集中在internal/handler/http/routers.go的RegisterApiHandlers按领域分组分组包路径典型能力baselogic/http/base/status、/device-videos、/ws-tokenvideologic/http/video取流地址、停流、流信息mslogic/http/ms流组、按名查录像、MS 配置、reloadgbslogic/http/gbsCatalog、Invite、StopStream、回放控制、订阅onviflogic/http/onvif发现、设备信息、Profilenotifylogic/http/notify流媒体回调推/拉流、订阅、统计、HLS、帧信息等完整路径以各 Logic 的Path()为准例如GET /api/status、POST /api/video/stream等。四、Handler 层泛型适配与统一响应4.1 两种入口定义于internal/handler/http/handler.gonewHandlerWithParams[Req, Logic]使用httpx.Parse将 Query / Path / JSON Body 绑定到Req。调用logic.New(ctx, c, svcCtx).DO(req)。newHandler[Logic]无请求体直接logic.New(...).DO()适用于纯GET或参数仅从 Path/Query 由 Logic 自行读取的场景若仍用httpx.Parse需在 Logic 内处理当前部分接口为无参DO()。4.2 Context 注入在调用New之前向context.Context写入Key含义constants.HEADER_IPc.ClientIP()便于下游直接获取。constants.CTX_VSS_IS_INTERNAL_REQ是否「内部请求」根据Referer的 host 是否为127.0.0.1/::1/localhost或Config.InternalIp判定。业务可通过contextx.GetIsInternalReq(ctx)读取例如internal/pkg/ms/api.go中按内外网区分行为。4.3 统一响应toRespLogic 返回types.HttpResponsetypeHttpResponsestruct{Datainterface{}Err*response.HttpErr}Err ! nilresponse.New().RequestError(...)携带统一错误语义与localization码。Data ! nilSuccess写出业务数据。两者皆无 /resp nil成功但 body 为nil。Handler 顶层有recover panic 时打栈日志避免进程崩溃与 Gin 默认行为叠加以实际为准。五、Logic 层契约接口驱动定义于internal/types/types.gotypeHttpHandleLogicBase[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 APIinternal/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 APIConfig.Http.Port本文主体/api/...WebSocketConfig.WS.Port独立net/http见《VSS-WebSocket架构设计》SSEConfig.SSE.Port独立服务运维状态推送等HTTP 中的/ws-token为 WebSocket 握手提供 Token形成HTTP 辅助 WS 长连接的组合。八、扩展新接口的步骤建议在internal/types或现有 types 文件增加请求/响应结构体若需要。在internal/logic/http/domain新增xxxLogic实现HttpRHandleLogic或HttpEHandleLogic实现Path()与DO。在internal/handler/http/routers.go中router.GET/POST(..., newHandler...)注册。若需全链路超时确认Config.Timeout是否足够超长任务考虑异步化或单独调大并评估Timeout中间件对 goroutine 的影响。若依赖内部调用方Referer注意网关/反向代理是否改写Referer以免影响GetIsInternalReq。九、设计要点小结前缀统一对外 JSON API 集中在/api与端口、文档、网关规则一致。契约清晰PathNewDOHttpResponseHandler 处理器、Logic 业务逻辑。解析统一有 body 的接口优先httpx.Parse减少手写ShouldBind。横切能力CORS、OPTIONS、超时、可扩展Header 中间件Context 注入 IP 与内部请求标记。领域分包gbs/video/ms/notify/onvif/base边界清楚notify与 MS 生命周期绑定紧密。十、相关源码索引说明路径HTTP 服务启动core/app/sev/vss/internal/server/http.go泛型 Handler / toRespcore/app/sev/vss/internal/handler/http/handler.go路由注册core/app/sev/vss/internal/handler/http/routers.go超时与 Header 中间件core/app/sev/vss/internal/interceptor/http.goHTTP 契约类型core/app/sev/vss/internal/types/types.goHttpResponse、HttpRHandleLogic等进程入口core/app/sev/vss/main.goVSS 配置结构core/tps/conf/config.goVssSevConfig可与《SkeyeVSS中WebSocket代码架构设计》对照阅读二者共享ServiceContext但监听端口与协议模型不同。