C#调用WebAPI的最佳实践与常见坑点
在微服务架构盛行的今天，通过HttpClient调用WebAPI几乎是每个C#开发者的日常。然而，从简单的GET请求到高并发下的稳定通信，中间隔着一系列容易踩坑的细节。下面我们就来梳理几个关键的最佳实践和那些容易让人栽跟头的“坑点”。
HttpClient 实例复用为什么不能每次 new
很多开发者习惯在方法内部直接 new HttpClient()，觉得这样用起来干净利落。但殊不知，这恰恰是导致性能问题和诡异错误的根源。频繁创建和销毁HttpClient实例，会迅速耗尽系统的Socket连接端口，导致出现 SocketException: Too many open files 或 HttpRequestException: Connection refused 这样的错误。更隐蔽的是，它还会使DNS缓存失效，每次请求都可能重新解析域名，在高并发场景下，这简直是性能杀手。
那么，正确的做法是什么？
- 最佳实践：将HttpClient作为单例或静态成员在整个应用生命周期内复用。在ASP.NET Core中，最优雅的方式是在Startup.cs（.NET 6及以上在Program.cs）中通过依赖注入注册：
services.AddSingleton。或者，更推荐使用() IHttpClientFactory，它能更好地管理生命周期和连接池。 - 务必避免：在循环或高频调用的方法体内使用
var client = new HttpClient();。即使你记得调用Dispose()，底层连接的释放也可能存在延迟。 - 补充一点：直接new出来的HttpClient不会自动参与连接池管理，而IHttpClientFactory背后则是一套完整的、经过优化的HTTP连接管理机制。
IHttpClientFactory 如何避免 DNS 变更不生效
用了IHttpClientFactory就高枕无忧了吗？未必。它默认会复用连接池以提升性能，但这带来了一个新的问题：当后端服务的DNS记录发生变更时（例如在Kubernetes中进行滚动更新、服务IP切换），客户端可能还在使用旧的、已经缓存的连接，持续将请求发往已经下线的节点，导致一段时间内的请求全部失败。
这并非Bug，而是HTTP/1.1连接复用机制的一个副作用。如何解决？
- 核心方案：配置连接的存活时间（PooledConnectionLifetime），强制定期重建连接池。例如，设置为2分钟是一个比较平衡的选择：
services.AddHttpClient(“MyApi”) .ConfigurePrimaryHttpMessageHandler(() => new SocketsHttpHandler { PooledConnectionLifetime = TimeSpan.FromMinutes(2) }); - 注意事项：不要将其设置为
TimeSpan.Zero，这等同于禁用连接池，会严重损害性能。当然，也不宜设置得过长（比如30分钟），那样会失去故障转移的敏捷性。 - 典型场景：这个问题在云原生环境下尤为突出。你的WebAPI在K8s里滚动更新后，客户端如果没刷新连接，可能会持续收到一波
502 Bad Gateway或连接超时错误。
WebAPI 返回 401/403 时，HttpClient 不抛异常？
这是一个让很多开发者困惑的地方：明明服务器返回了401未授权或403禁止访问，为什么我的 await client.GetAsync(url) 没有抛出异常？
原因在于设计如此。HttpClient.SendAsync() 方法只在网络层失败（如超时、无法连接、DNS解析失败）时才会抛出异常。而对于HTTP协议层面的状态码，无论是表示成功的200，还是表示客户端错误的401、403、404，都被视为“成功的响应”。服务器确实响应了，只是响应的内容告诉你“这事儿没成”。
- 正确做法：在得到
HttpResponseMessage后，务必调用response.EnsureSuccessStatusCode()方法。这个方法会检查状态码是否为2xx成功范围，如果不是，则会抛出一个包含状态码的HttpRequestException。 - 常见坑点：如果你直接使用
await response.Content.ReadAsStringAsync()来读取内容，却忽略了检查response.IsSuccessStatusCode，那么当API返回一个错误HTML或JSON时，你的后续反序列化逻辑就会崩溃，报错信息可能风马牛不相及，增加调试难度。 - 实用技巧：建议封装一个通用的请求辅助方法，在其中统一处理状态码检查、日志记录和可能的错误重试逻辑，让业务代码更清晰。
FromBody 参数绑定失败的三个典型原因
在WebAPI的Controller里，使用 [FromBody] 来接收JSON数据是标准操作。但时不时就会遇到参数绑定失败，传入的模型对象莫名其妙变成了null。问题出在哪里？通常不是业务逻辑，而是序列化或配置的细节。
以下是三个最需要排查的方向：
- 请求头必须正确：客户端发出的请求，其Header里必须包含
Content-Type: application/json。如果缺少这个头，ASP.NET Core默认不会尝试将请求体当作JSON来解析。 - 模型结构需兼容：用于绑定的模型类必须有一个无参数的公共构造函数，并且属性需要有public的setter。如果你使用了C# 9.0的record类型或init-only属性，需要确认你的目标框架版本是否支持，并可能需要配置
JsonSerializerOptions.IncludeFields = true等选项。 - 警惕不可为空的值类型：一个非常隐蔽的坑是，前端可能发送了一个空对象
{}，但后端的模型里有一个不可为空的int Id字段。此时模型验证会失败，ModelState.IsValid会变为false，而默认的API控制器行为可能不会给出清晰的错误信息，导致你只知道绑定失败，却不知为何。
当遇到绑定问题时，调试可以遵循这个顺序：首先抓包（使用Fiddler或浏览器开发者工具）确认请求体和Header是否符合预期；其次在Controller方法内检查 ModelState 的错误详情；最后查看应用程序日志，寻找 JsonSerializer 在反序列化时抛出的内部异常——很多时候，这些异常被中间件静默处理了，需要你主动去发现。
