简介一份面向.NET开发者的ASP.NET Core 6 Web API入门示例演示如何结合Entity Framework Core实现RESTful接口。资源包含完整的项目源码基于.NET 6.0构建覆盖从服务配置、数据库上下文、迁移、控制器到实体模型的完整开发链路并展示依赖注入、中间件管道、路由映射、异步流等核心用法适合初学者快速掌握从零搭建API的流程。项目中的Migrations记录了数据库结构变更历史Controller利用属性路由定义HTTP动作DbContext则映射相关实体关系通过LINQ查询和保存数据形成一套层次分明、可直接运行的示例工程。包内共16个文件以C#源文件为主辅以JSON配置文件、解决方案文件与项目文件整体仅13KB结构精简便于对照阅读。已有388人学习下载读者可借助该示例理解数据访问层设计、HTTP方法映射、异常处理与日志记录等关键实现也可作为后续扩展身份验证、授权机制等功能的起点。 这段时间很多朋友问我能不能出一个 ASP.NET Core 6 Web API 示例正好我最近在做安防平台对接接触了海康综合安防管理平台的 Web 取 HLS 流接口踩了不少坑也摸出了一套比较顺手的写法。这篇文章就把这个示例项目完整拆开从设计思路到核心代码再到上线前一定要处理的鉴权、缓存和异常问题全部过一遍。如果你正准备做监控视频上墙、大屏可视化或者只是想把海康平台的 HLS 流安全地暴露给前端播放器这篇文章应该能帮你省掉至少两三天的试错时间。1. 为什么需要自建 Web API 中间层而不是让前端直接调海康平台先说一个很多刚接触安防平台的人容易踩的坑拿到海康综合安防管理平台的取流文档后第一反应是让前端通过浏览器直接调平台的 API拿到 HLS 地址再塞给播放器。听起来很简单实际跑起来全是问题。首先是跨域。海康平台一般运行在客户的内网环境前端页面可能是公网上的 Web 应用就算你强行在前端开了 CORS浏览器对跨域请求的限制也会让调试变得非常痛苦。其次是安全。调用海康平台 OpenAPI 通常需要 AppKey 和 AppSecret还要做签名如果把这些密钥放在前端代码里就相当于把监控系统的访问凭证直接公开了稍微有点安全意识的人都接受不了这种做法。还有一个特别容易被忽略的问题HLS 地址有时效性。海康平台返回的拉流地址不是永久有效的过期之后前端播放器就会一直转圈。如果前端每个播放器都直接去请求海康平台同时请求量一大平台侧压力就会上来而且 HLS 地址缓存、刷新、统一管理都会变成一团乱麻。所以比较合理的方案是在中间层用 ASP.NET Core 6 写一个 Web API统一负责和海康平台通信拿到 HLS 流地址后在服务端做缓存和访问控制前端只需要请求我们自己暴露的接口。ASP.NET Core 6 在这类场景下有几个天然优势自带依赖注入和 HttpClientFactory可以优雅地管理 HTTP 请求内置 JWT 认证中间件做接口鉴权非常方便跨平台部署也很省心Linux 容器里跑完全没问题。2. 对接海康取流之前的三个准备在写代码之前别急着开项目。我建议先把下面三件事确认完不然后面返工非常磨人。2.1 确认平台版本和文档版本海康综合安防管理平台iSecure Center不同版本的 OpenAPI 接口路径和参数格式是有差异的。我手头这个项目用的是比较常见的版本取 HLS 流的接口路径大致长这样/api/video/v1/cameras/preview但你这边的平台版本不一定一样所以第一件事就是拿到对应版本的《OpenAPI 联调文档》。千万别拿着网上几年前的旧文档直接套我见过有朋友因为接口版本不匹配排查了两天才发现是文档过期了。2.2 提前申请应用凭证不要等联调时再要取流接口走平台开放接口时需要用到 AppKey 和 AppSecret。这个通常是管理员在平台后台创建“应用”后生成的。你在搭建环境阶段就应该把它申请好不要等到代码写完再去找管理员因为有些客户的审批流程很慢。拿到 AppKey 和 AppSecret 后一般还需要确认你调用的接口是否需要“订阅”或者“授权”也就是在平台上开通对应的 API 权限。很多联调失败其实不是代码问题而是应用没有对应的接口权限。2.3 摸清网络拓扑想清楚服务部署在哪里海康平台基本都部署在客户的内网环境中我们的 ASP.NET Core 6 Web API 服务必须能访问到平台接口。这里有两种常见部署方式Web API 也部署在客户内网直接通过内网地址访问海康平台。Web API 部署在公网通过防火墙白名单或专线打通访问通道。无论哪种方式都需要提前确认网络策略否则代码写完了本地能跑一到测试环境就超时。另外还要注意海康平台返回的 HLS 流地址通常是内网地址比如http://192.168.x.x:8080/...。如果前端播放器在公网那么这个地址是拉不到流的。这个问题我在后面“上线踩坑”部分会专门讲怎么处理。3. 取流接口的核心实现从 HttpClient 到统一响应这一部分是整个示例的重头戏。我会把关键的代码结构贴出来并解释每一步为什么这样做。3.1 项目目录与模型定义创建一个 ASP.NET Core 6 Web API 项目解决方案结构大致如下HikVisionStreamApi/ ├── Controllers/ │ └── StreamController.cs ├── Services/ │ ├── IHikVisionService.cs │ └── HikVisionService.cs ├── Models/ │ ├── StreamRequest.cs │ └── StreamResponse.cs ├── appsettings.json └── Program.cs模型定义不要太复杂够用就行。前端请求过来时只需要带上设备编号和通道编号返回时统一封装成我们自己的数据格式避免把海康平台的字段原样暴露给前端。public class StreamRequest { public string DeviceId { get; set; } public string ChannelId { get; set; } } public class StreamResponse { public bool Success { get; set; } public string Message { get; set; } public string HlsUrl { get; set; } public DateTime ExpireTime { get; set; } }3.2 注册 HttpClient 服务和配置在Program.cs里用一个AddHttpClient注册海康服务专用的 HttpClient。这里我特意给不同外部服务定义了不同的 HttpClient 名称便于后续单独调整超时时间和弹性策略。builder.Services.AddHttpClient(HikVision, client { client.Timeout TimeSpan.FromSeconds(15); client.BaseAddress new Uri(builder.Configuration[HikVision:BaseUrl]); });在appsettings.json里保存海康平台的基础配置。有一点要注意AppSecret等敏感信息在真实生产环境不要直接放明文配置建议结合环境变量或者密钥管理服务来使用。{ HikVision: { BaseUrl: http://your-hikvision-platform-ip, AppKey: your-app-key, AppSecret: your-app-secret } }这里用BaseAddress统一管理基础地址后续调用具体接口时只需要写相对路径避免到处都是硬编码的 URL。3.3 服务层实现与签名处理海康平台的 OpenAPI 通常要求在请求头中带上签名参数。不同版本的签名规则不太一样常见的做法是通过AppKey、AppSecret、时间戳和请求参数生成一个X-Signature头。下面这个示例代表了一个比较通用的签名流程public class HikVisionService : IHikVisionService { private readonly IHttpClientFactory _httpClientFactory; private readonly IConfiguration _configuration; private readonly ILoggerHikVisionService _logger; public HikVisionService( IHttpClientFactory httpClientFactory, IConfiguration configuration, ILoggerHikVisionService logger) { _httpClientFactory httpClientFactory; _configuration configuration; _logger logger; } public async TaskStreamResponse GetHlsUrlAsync(string deviceId, string channelId) { var appKey _configuration[HikVision:AppKey]; var appSecret _configuration[HikVision:AppSecret]; var timestamp DateTimeOffset.UtcNow.ToUnixTimeSeconds().ToString(); // 这里只是示例签名逻辑实际要以官方文档为准 var signSource ${appKey}{timestamp}{deviceId}{channelId}; var signature Convert.ToHexString( System.Security.Cryptography.SHA256.HashData( System.Text.Encoding.UTF8.GetBytes(signSource))); var client _httpClientFactory.CreateClient(HikVision); var request new HttpRequestMessage(HttpMethod.Post, /api/video/v1/cameras/preview); request.Headers.Add(AppKey, appKey); request.Headers.Add(Timestamp, timestamp); request.Headers.Add(Signature, signature); request.Content JsonContent.Create(new { deviceId, channelId, protocol hls }); var response await client.SendAsync(request); if (!response.IsSuccessStatusCode) { _logger.LogError(海康取流失败: {StatusCode}, {Body}, response.StatusCode, await response.Content.ReadAsStringAsync()); return new StreamResponse { Success false, Message 平台取流失败 }; } var json await response.Content.ReadFromJsonAsyncHikVisionPreviewResponse(); var hlsUrl json?.Data?.Url; if (string.IsNullOrWhiteSpace(hlsUrl)) { return new StreamResponse { Success false, Message 平台未返回有效的HLS地址 }; } // HLS地址一般有一个过期时间具体字段以文档为准 return new StreamResponse { Success true, HlsUrl hlsUrl, ExpireTime DateTime.UtcNow.AddMinutes(30) }; } }注意这里我用了IHttpClientFactory而不是直接new HttpClient()。原因很简单频繁地创建和销毁 HttpClient 会耗尽 Socket 资源而IHttpClientFactory帮你管理连接生命周期和 DNS 刷新这是生产环境里非常容易忽略的细节。3.4 控制器层只做“翻译”工作控制器不要写业务逻辑只负责接收前端参数、调用服务、返回统一格式的结果。[ApiController] [Route(api/[controller])] public class StreamController : ControllerBase { private readonly IHikVisionService _hikVisionService; public StreamController(IHikVisionService hikVisionService) { _hikVisionService hikVisionService; } [HttpPost(hls)] public async TaskIActionResult GetHlsUrl([FromBody] StreamRequest request) { if (string.IsNullOrWhiteSpace(request.DeviceId) || string.IsNullOrWhiteSpace(request.ChannelId)) { return BadRequest(new { Success false, Message 设备编号和通道编号不能为空 }); } var result await _hikVisionService.GetHlsUrlAsync(request.DeviceId, request.ChannelId); return result.Success ? Ok(result) : StatusCode(502, result); } }前端请求方式很简单POST /api/stream/hls Content-Type: application/json { deviceId: 摄像头设备编号, channelId: 通道编号 }到这一步一个最基本的取流接口就通了。4. 从“能调通”到“敢上线”缓存、鉴权与异常兜底联调时接口能拿到流地址只是第一步。真正要上线还差三件很重要的事。4.1 给 HLS 地址加上缓存避免打爆平台接口海康平台的取流接口不适合频繁调用。一方面平台侧会有频控限制另一方面 HLS 地址短期内是有效的没必要每次都重新向平台申请。我用的是 ASP.NET Core 6 内置的IMemoryCache在服务层加一层缓存Key 用设备编号和通道编号拼起来过期时间比地址实际有效时间短一些默认 25 分钟。这样做的好处是即使前端有几十个观众同时观看同一个摄像头第一次请求会穿透到海康平台后续请求都直接命中缓存。private readonly IMemoryCache _cache; private static string BuildCacheKey(string deviceId, string channelId) $hls:{deviceId}:{channelId}; public async TaskStreamResponse GetHlsUrlWithCacheAsync(string deviceId, string channelId) { var cacheKey BuildCacheKey(deviceId, channelId); if (_cache.TryGetValue(cacheKey, out StreamResponse cached)) { return cached; } var result await GetHlsUrlAsync(deviceId, channelId); if (result.Success) { _cache.Set(cacheKey, result, TimeSpan.FromMinutes(25)); } return result; }如果你的项目做了负载均衡或者有多实例部署那就得考虑使用 Redis 做分布式缓存否则每个实例的缓存是独立的压力还是会打回平台。不过对于大多数单机部署的安防项目IMemoryCache已经够用了。4.2 对外接口必须加鉴权取流接口一旦暴露到公网任何人都可以拿着摄像头编号去拉流这是非常严重的安全隐患。我的做法是启用 JWT 认证前端先登录获取 Token再调用取流接口时在Authorization头里带上 Bearer Token 即可。最小化的 JWT 配置如下builder.Services.AddAuthentication(Bearer) .AddJwtBearer(Bearer, options { options.Authority builder.Configuration[Jwt:Authority]; options.TokenValidationParameters new() { ValidateAudience false, ValidateIssuer true, ValidIssuer builder.Configuration[Jwt:Issuer], ValidateLifetime true, ValidateIssuerSigningKey true }; });如果你的项目里没有独立的身份认证服务也可以用中间件做一个简单的 AppKey 校验在调用StreamController之前先检查请求头里的X-App-Key是否在白名单里。记住一点能用现成框架解决的就不要自己发明轮子JWT 是相对标准且成熟的方案。4.3 统一异常兜底别把平台原始错误直接抛给前端海康平台返回的错误信息有时是一大段 XML 或者 JSON直接透传给前端既不优雅还可能泄露内部接口细节。我习惯在服务层捕获外部 API 的异常转换成业务错误码。同时在控制器外层加一个全局异常过滤器兜底所有未处理异常。[AttributeUsage(AttributeTargets.Class | AttributeTargets.Method)] public class GlobalExceptionFilter : ExceptionFilterAttribute { private readonly ILoggerGlobalExceptionFilter _logger; public GlobalExceptionFilter(ILoggerGlobalExceptionFilter logger) { _logger logger; } public override void OnException(ExceptionContext context) { _logger.LogError(context.Exception, 未处理异常: {Message}, context.Exception.Message); context.Result new ObjectResult(new { Success false, Message 服务暂时不可用请稍后重试 }) { StatusCode StatusCodes.Status500InternalServerError }; context.ExceptionHandled true; } }5. 部署阶段我踩过的三个坑最后说说我在真实项目里踩过的三个坑。这些坑网上资料不多但实战中非常高发。5.1 HttpClient 超时设置太激进导致大量请求堆积一开始我把AddHttpClient的Timeout设成了 5 秒结果海康平台在高峰期响应速度有点慢一个取流请求超过 5 秒就会抛TaskCanceledException。由于我的服务层没有做降级处理前端只要并发稍微上来一点连接池就会堆积大量等待请求整个 Web API 都变慢了。后来我把超时调成 15 秒并且用WaitAndRetryAsync策略做了两层重试第一层是瞬时网络抖动重试一次第二层是超时后延迟 2 秒再重试一次。注意重试一定要控制次数不能对写操作做盲目重试但取流是幂等查询重试两三次问题不大。5.2 HLS 地址里的内网 IP 公网无法访问这个坑最让人头疼。海康平台返回的 HLS 地址往往是http://192.168.1.20:8080/...在我们服务所在的内网环境能正常拉流但前端播放器在公网拿着这个地址完全连不上。我们的处理方案是在 Web API 层对返回的 URL 做一次重写将内网地址替换成经过 Nginx 反向代理后的公网域名。这样前端拿到的就是https://video.example.com/live/...这样可访问的地址。重写逻辑并不复杂但一定要提前规划好代理转发规则别等到上线了才想在播放地址上做手脚。5.3 缓存过期时间比流地址实际有效时间长前端播放到一半黑屏这个问题很隐蔽。一开始我以为 HLS 地址的有效时间肯定是几小时所以把缓存设成了 60 分钟。结果实际运行中发现部分设备返回的 HLS 地址有效时间只有 30 分钟左右前端播放器在 30 分钟后就拉不到新的分片画面直接卡死。排查了很久才发现是缓存策略和实际有效期不匹配。最终我把缓存过期时间改成了 20 分钟并专门写了一个后台任务每隔一段时间主动向海康平台校验地址并刷新缓存。稳妥起见前端播放器也应该监听播放错误事件遇到network error时主动向后端请求一个新的取流地址而不是一直停在黑屏。写在最后如果你也要做类似的海康 HLS 取流对接我的建议是先把网络环境、接口文档、应用凭证这三件事确认好再动笔写代码。中间层用 ASP.NET Core 6 封装一个 Web API 是性价比很高的方案它既解决了跨域和密钥泄露的问题也让你有了统一控制缓存、鉴权、日志的入口。代码不用写得特别复杂先把链路跑通再逐步加上重试、缓存和监控这样整个项目会稳定很多。本文还有配套的精品资源点击获取
ASP.NET Core 6 Web API对接海康HLS流实战指南
简介一份面向.NET开发者的ASP.NET Core 6 Web API入门示例演示如何结合Entity Framework Core实现RESTful接口。资源包含完整的项目源码基于.NET 6.0构建覆盖从服务配置、数据库上下文、迁移、控制器到实体模型的完整开发链路并展示依赖注入、中间件管道、路由映射、异步流等核心用法适合初学者快速掌握从零搭建API的流程。项目中的Migrations记录了数据库结构变更历史Controller利用属性路由定义HTTP动作DbContext则映射相关实体关系通过LINQ查询和保存数据形成一套层次分明、可直接运行的示例工程。包内共16个文件以C#源文件为主辅以JSON配置文件、解决方案文件与项目文件整体仅13KB结构精简便于对照阅读。已有388人学习下载读者可借助该示例理解数据访问层设计、HTTP方法映射、异常处理与日志记录等关键实现也可作为后续扩展身份验证、授权机制等功能的起点。 这段时间很多朋友问我能不能出一个 ASP.NET Core 6 Web API 示例正好我最近在做安防平台对接接触了海康综合安防管理平台的 Web 取 HLS 流接口踩了不少坑也摸出了一套比较顺手的写法。这篇文章就把这个示例项目完整拆开从设计思路到核心代码再到上线前一定要处理的鉴权、缓存和异常问题全部过一遍。如果你正准备做监控视频上墙、大屏可视化或者只是想把海康平台的 HLS 流安全地暴露给前端播放器这篇文章应该能帮你省掉至少两三天的试错时间。1. 为什么需要自建 Web API 中间层而不是让前端直接调海康平台先说一个很多刚接触安防平台的人容易踩的坑拿到海康综合安防管理平台的取流文档后第一反应是让前端通过浏览器直接调平台的 API拿到 HLS 地址再塞给播放器。听起来很简单实际跑起来全是问题。首先是跨域。海康平台一般运行在客户的内网环境前端页面可能是公网上的 Web 应用就算你强行在前端开了 CORS浏览器对跨域请求的限制也会让调试变得非常痛苦。其次是安全。调用海康平台 OpenAPI 通常需要 AppKey 和 AppSecret还要做签名如果把这些密钥放在前端代码里就相当于把监控系统的访问凭证直接公开了稍微有点安全意识的人都接受不了这种做法。还有一个特别容易被忽略的问题HLS 地址有时效性。海康平台返回的拉流地址不是永久有效的过期之后前端播放器就会一直转圈。如果前端每个播放器都直接去请求海康平台同时请求量一大平台侧压力就会上来而且 HLS 地址缓存、刷新、统一管理都会变成一团乱麻。所以比较合理的方案是在中间层用 ASP.NET Core 6 写一个 Web API统一负责和海康平台通信拿到 HLS 流地址后在服务端做缓存和访问控制前端只需要请求我们自己暴露的接口。ASP.NET Core 6 在这类场景下有几个天然优势自带依赖注入和 HttpClientFactory可以优雅地管理 HTTP 请求内置 JWT 认证中间件做接口鉴权非常方便跨平台部署也很省心Linux 容器里跑完全没问题。2. 对接海康取流之前的三个准备在写代码之前别急着开项目。我建议先把下面三件事确认完不然后面返工非常磨人。2.1 确认平台版本和文档版本海康综合安防管理平台iSecure Center不同版本的 OpenAPI 接口路径和参数格式是有差异的。我手头这个项目用的是比较常见的版本取 HLS 流的接口路径大致长这样/api/video/v1/cameras/preview但你这边的平台版本不一定一样所以第一件事就是拿到对应版本的《OpenAPI 联调文档》。千万别拿着网上几年前的旧文档直接套我见过有朋友因为接口版本不匹配排查了两天才发现是文档过期了。2.2 提前申请应用凭证不要等联调时再要取流接口走平台开放接口时需要用到 AppKey 和 AppSecret。这个通常是管理员在平台后台创建“应用”后生成的。你在搭建环境阶段就应该把它申请好不要等到代码写完再去找管理员因为有些客户的审批流程很慢。拿到 AppKey 和 AppSecret 后一般还需要确认你调用的接口是否需要“订阅”或者“授权”也就是在平台上开通对应的 API 权限。很多联调失败其实不是代码问题而是应用没有对应的接口权限。2.3 摸清网络拓扑想清楚服务部署在哪里海康平台基本都部署在客户的内网环境中我们的 ASP.NET Core 6 Web API 服务必须能访问到平台接口。这里有两种常见部署方式Web API 也部署在客户内网直接通过内网地址访问海康平台。Web API 部署在公网通过防火墙白名单或专线打通访问通道。无论哪种方式都需要提前确认网络策略否则代码写完了本地能跑一到测试环境就超时。另外还要注意海康平台返回的 HLS 流地址通常是内网地址比如http://192.168.x.x:8080/...。如果前端播放器在公网那么这个地址是拉不到流的。这个问题我在后面“上线踩坑”部分会专门讲怎么处理。3. 取流接口的核心实现从 HttpClient 到统一响应这一部分是整个示例的重头戏。我会把关键的代码结构贴出来并解释每一步为什么这样做。3.1 项目目录与模型定义创建一个 ASP.NET Core 6 Web API 项目解决方案结构大致如下HikVisionStreamApi/ ├── Controllers/ │ └── StreamController.cs ├── Services/ │ ├── IHikVisionService.cs │ └── HikVisionService.cs ├── Models/ │ ├── StreamRequest.cs │ └── StreamResponse.cs ├── appsettings.json └── Program.cs模型定义不要太复杂够用就行。前端请求过来时只需要带上设备编号和通道编号返回时统一封装成我们自己的数据格式避免把海康平台的字段原样暴露给前端。public class StreamRequest { public string DeviceId { get; set; } public string ChannelId { get; set; } } public class StreamResponse { public bool Success { get; set; } public string Message { get; set; } public string HlsUrl { get; set; } public DateTime ExpireTime { get; set; } }3.2 注册 HttpClient 服务和配置在Program.cs里用一个AddHttpClient注册海康服务专用的 HttpClient。这里我特意给不同外部服务定义了不同的 HttpClient 名称便于后续单独调整超时时间和弹性策略。builder.Services.AddHttpClient(HikVision, client { client.Timeout TimeSpan.FromSeconds(15); client.BaseAddress new Uri(builder.Configuration[HikVision:BaseUrl]); });在appsettings.json里保存海康平台的基础配置。有一点要注意AppSecret等敏感信息在真实生产环境不要直接放明文配置建议结合环境变量或者密钥管理服务来使用。{ HikVision: { BaseUrl: http://your-hikvision-platform-ip, AppKey: your-app-key, AppSecret: your-app-secret } }这里用BaseAddress统一管理基础地址后续调用具体接口时只需要写相对路径避免到处都是硬编码的 URL。3.3 服务层实现与签名处理海康平台的 OpenAPI 通常要求在请求头中带上签名参数。不同版本的签名规则不太一样常见的做法是通过AppKey、AppSecret、时间戳和请求参数生成一个X-Signature头。下面这个示例代表了一个比较通用的签名流程public class HikVisionService : IHikVisionService { private readonly IHttpClientFactory _httpClientFactory; private readonly IConfiguration _configuration; private readonly ILoggerHikVisionService _logger; public HikVisionService( IHttpClientFactory httpClientFactory, IConfiguration configuration, ILoggerHikVisionService logger) { _httpClientFactory httpClientFactory; _configuration configuration; _logger logger; } public async TaskStreamResponse GetHlsUrlAsync(string deviceId, string channelId) { var appKey _configuration[HikVision:AppKey]; var appSecret _configuration[HikVision:AppSecret]; var timestamp DateTimeOffset.UtcNow.ToUnixTimeSeconds().ToString(); // 这里只是示例签名逻辑实际要以官方文档为准 var signSource ${appKey}{timestamp}{deviceId}{channelId}; var signature Convert.ToHexString( System.Security.Cryptography.SHA256.HashData( System.Text.Encoding.UTF8.GetBytes(signSource))); var client _httpClientFactory.CreateClient(HikVision); var request new HttpRequestMessage(HttpMethod.Post, /api/video/v1/cameras/preview); request.Headers.Add(AppKey, appKey); request.Headers.Add(Timestamp, timestamp); request.Headers.Add(Signature, signature); request.Content JsonContent.Create(new { deviceId, channelId, protocol hls }); var response await client.SendAsync(request); if (!response.IsSuccessStatusCode) { _logger.LogError(海康取流失败: {StatusCode}, {Body}, response.StatusCode, await response.Content.ReadAsStringAsync()); return new StreamResponse { Success false, Message 平台取流失败 }; } var json await response.Content.ReadFromJsonAsyncHikVisionPreviewResponse(); var hlsUrl json?.Data?.Url; if (string.IsNullOrWhiteSpace(hlsUrl)) { return new StreamResponse { Success false, Message 平台未返回有效的HLS地址 }; } // HLS地址一般有一个过期时间具体字段以文档为准 return new StreamResponse { Success true, HlsUrl hlsUrl, ExpireTime DateTime.UtcNow.AddMinutes(30) }; } }注意这里我用了IHttpClientFactory而不是直接new HttpClient()。原因很简单频繁地创建和销毁 HttpClient 会耗尽 Socket 资源而IHttpClientFactory帮你管理连接生命周期和 DNS 刷新这是生产环境里非常容易忽略的细节。3.4 控制器层只做“翻译”工作控制器不要写业务逻辑只负责接收前端参数、调用服务、返回统一格式的结果。[ApiController] [Route(api/[controller])] public class StreamController : ControllerBase { private readonly IHikVisionService _hikVisionService; public StreamController(IHikVisionService hikVisionService) { _hikVisionService hikVisionService; } [HttpPost(hls)] public async TaskIActionResult GetHlsUrl([FromBody] StreamRequest request) { if (string.IsNullOrWhiteSpace(request.DeviceId) || string.IsNullOrWhiteSpace(request.ChannelId)) { return BadRequest(new { Success false, Message 设备编号和通道编号不能为空 }); } var result await _hikVisionService.GetHlsUrlAsync(request.DeviceId, request.ChannelId); return result.Success ? Ok(result) : StatusCode(502, result); } }前端请求方式很简单POST /api/stream/hls Content-Type: application/json { deviceId: 摄像头设备编号, channelId: 通道编号 }到这一步一个最基本的取流接口就通了。4. 从“能调通”到“敢上线”缓存、鉴权与异常兜底联调时接口能拿到流地址只是第一步。真正要上线还差三件很重要的事。4.1 给 HLS 地址加上缓存避免打爆平台接口海康平台的取流接口不适合频繁调用。一方面平台侧会有频控限制另一方面 HLS 地址短期内是有效的没必要每次都重新向平台申请。我用的是 ASP.NET Core 6 内置的IMemoryCache在服务层加一层缓存Key 用设备编号和通道编号拼起来过期时间比地址实际有效时间短一些默认 25 分钟。这样做的好处是即使前端有几十个观众同时观看同一个摄像头第一次请求会穿透到海康平台后续请求都直接命中缓存。private readonly IMemoryCache _cache; private static string BuildCacheKey(string deviceId, string channelId) $hls:{deviceId}:{channelId}; public async TaskStreamResponse GetHlsUrlWithCacheAsync(string deviceId, string channelId) { var cacheKey BuildCacheKey(deviceId, channelId); if (_cache.TryGetValue(cacheKey, out StreamResponse cached)) { return cached; } var result await GetHlsUrlAsync(deviceId, channelId); if (result.Success) { _cache.Set(cacheKey, result, TimeSpan.FromMinutes(25)); } return result; }如果你的项目做了负载均衡或者有多实例部署那就得考虑使用 Redis 做分布式缓存否则每个实例的缓存是独立的压力还是会打回平台。不过对于大多数单机部署的安防项目IMemoryCache已经够用了。4.2 对外接口必须加鉴权取流接口一旦暴露到公网任何人都可以拿着摄像头编号去拉流这是非常严重的安全隐患。我的做法是启用 JWT 认证前端先登录获取 Token再调用取流接口时在Authorization头里带上 Bearer Token 即可。最小化的 JWT 配置如下builder.Services.AddAuthentication(Bearer) .AddJwtBearer(Bearer, options { options.Authority builder.Configuration[Jwt:Authority]; options.TokenValidationParameters new() { ValidateAudience false, ValidateIssuer true, ValidIssuer builder.Configuration[Jwt:Issuer], ValidateLifetime true, ValidateIssuerSigningKey true }; });如果你的项目里没有独立的身份认证服务也可以用中间件做一个简单的 AppKey 校验在调用StreamController之前先检查请求头里的X-App-Key是否在白名单里。记住一点能用现成框架解决的就不要自己发明轮子JWT 是相对标准且成熟的方案。4.3 统一异常兜底别把平台原始错误直接抛给前端海康平台返回的错误信息有时是一大段 XML 或者 JSON直接透传给前端既不优雅还可能泄露内部接口细节。我习惯在服务层捕获外部 API 的异常转换成业务错误码。同时在控制器外层加一个全局异常过滤器兜底所有未处理异常。[AttributeUsage(AttributeTargets.Class | AttributeTargets.Method)] public class GlobalExceptionFilter : ExceptionFilterAttribute { private readonly ILoggerGlobalExceptionFilter _logger; public GlobalExceptionFilter(ILoggerGlobalExceptionFilter logger) { _logger logger; } public override void OnException(ExceptionContext context) { _logger.LogError(context.Exception, 未处理异常: {Message}, context.Exception.Message); context.Result new ObjectResult(new { Success false, Message 服务暂时不可用请稍后重试 }) { StatusCode StatusCodes.Status500InternalServerError }; context.ExceptionHandled true; } }5. 部署阶段我踩过的三个坑最后说说我在真实项目里踩过的三个坑。这些坑网上资料不多但实战中非常高发。5.1 HttpClient 超时设置太激进导致大量请求堆积一开始我把AddHttpClient的Timeout设成了 5 秒结果海康平台在高峰期响应速度有点慢一个取流请求超过 5 秒就会抛TaskCanceledException。由于我的服务层没有做降级处理前端只要并发稍微上来一点连接池就会堆积大量等待请求整个 Web API 都变慢了。后来我把超时调成 15 秒并且用WaitAndRetryAsync策略做了两层重试第一层是瞬时网络抖动重试一次第二层是超时后延迟 2 秒再重试一次。注意重试一定要控制次数不能对写操作做盲目重试但取流是幂等查询重试两三次问题不大。5.2 HLS 地址里的内网 IP 公网无法访问这个坑最让人头疼。海康平台返回的 HLS 地址往往是http://192.168.1.20:8080/...在我们服务所在的内网环境能正常拉流但前端播放器在公网拿着这个地址完全连不上。我们的处理方案是在 Web API 层对返回的 URL 做一次重写将内网地址替换成经过 Nginx 反向代理后的公网域名。这样前端拿到的就是https://video.example.com/live/...这样可访问的地址。重写逻辑并不复杂但一定要提前规划好代理转发规则别等到上线了才想在播放地址上做手脚。5.3 缓存过期时间比流地址实际有效时间长前端播放到一半黑屏这个问题很隐蔽。一开始我以为 HLS 地址的有效时间肯定是几小时所以把缓存设成了 60 分钟。结果实际运行中发现部分设备返回的 HLS 地址有效时间只有 30 分钟左右前端播放器在 30 分钟后就拉不到新的分片画面直接卡死。排查了很久才发现是缓存策略和实际有效期不匹配。最终我把缓存过期时间改成了 20 分钟并专门写了一个后台任务每隔一段时间主动向海康平台校验地址并刷新缓存。稳妥起见前端播放器也应该监听播放错误事件遇到network error时主动向后端请求一个新的取流地址而不是一直停在黑屏。写在最后如果你也要做类似的海康 HLS 取流对接我的建议是先把网络环境、接口文档、应用凭证这三件事确认好再动笔写代码。中间层用 ASP.NET Core 6 封装一个 Web API 是性价比很高的方案它既解决了跨域和密钥泄露的问题也让你有了统一控制缓存、鉴权、日志的入口。代码不用写得特别复杂先把链路跑通再逐步加上重试、缓存和监控这样整个项目会稳定很多。本文还有配套的精品资源点击获取