C# HttpClient POST JSON 实战：序列化、超时重试与排错

简介：面向需要在 C# 项目中完成 HTTP POST 与 JSON 数据交互的开发者，尤其适合为不同 .NET 目标框架挑选兼容 Newtonsoft.Json 组件的场景，可解决请求体序列化、响应反序列化及多版本引用选择等问题。压缩包为 rar 格式，共 27 个文件，约 6.41MB，内含 9 个 dll、9 个 xml 与 9 个 pdb，分别对应可引用的程序集、API 文档和调试符号，覆盖 net20 至 netstandard2.0 等多个目标版本，便于按项目框架快速匹配。已有约 1400 人学习下载。对需要稳定处理 JSON 对象转换、排查序列化异常或补齐旧项目依赖的读者，这份资源能减少逐个查找版本的时间，也方便在调试时借助符号与文档定位调用细节。

1. 一个 POST 请求为什么会耗掉半天

对接某第三方接口时，我遇到过最典型的场景：本地 curl 一把过，换到 C# 客户端，返回 415；把 Content-Type 补上，变 400；改完字段名，又变超时。整个链路只有一句话——POST 一个 JSON 过去，拿 JSON 回来，可真正卡人的从来不是「怎么发」，而是编码、头、序列化、连接生命周期这几处细节叠加。c# 网络协议交互里，json 是最常见的载体，也是最容易被当成「随便写写就行」的一层。这篇按我实际拆过的顺序走：先把请求骨架立稳，再谈序列化选型，最后落到真实网络里的超时、重试和排查。适合正在写对接层、被 4xx 反复打回的人。

2. HttpClient 的请求骨架：从实例到报文

2.1 为什么不能把 HttpClient 塞进 using

新手最容易照抄的写法是using (var client = new HttpClient())，每次调用新建、用完释放。在控制台里跑一次没问题，放进 Web 服务或者循环里就会出问题。HttpClient 内部持有HttpMessageHandler，真正干活的是它维护的连接池；Dispose掉 HttpClient 会把底层 socket 一起关掉，于是短时间内大量连接进入 TIME_WAIT，端口被占满，表现为「跑一会儿就开始报连接失败」。

反直觉的地方在于：HttpClient 本身是线程安全的，绝大多数公开方法都支持并发调用，它被设计成长期存活。真正需要控制的是它的生命周期，而不是「用完就扔」。我一般的做法分两种：进程内只有一个远端地址，就用静态只读实例；要对接多个不同域名或不同配置，用IHttpClientFactory按名字取。前者简单，后者能顺带解决 DNS 刷新和统一配置的问题，第 4 章会展开。

提示：静态实例不等于配置永远不变。BaseAddress和DefaultRequestHeaders是共享状态，改了会影响所有并发请求，别在业务代码里随手改。

2.2 最小可跑的 POST JSON 骨架

先把能跑通的版本写出来，后面所有讨论都基于它改。这里用System.Text.Json，.NET Core 3.0 之后内置，不引第三方包。

using System; using System.Net.Http; using System.Text; using System.Text.Json; using System.Threading; using System.Threading.Tasks; public class OrderClient { // 静态只读实例：整个进程复用同一份连接池 private static readonly HttpClient Http = new HttpClient { BaseAddress = new Uri("https://api.example.invalid/"), Timeout = TimeSpan.FromSeconds(15) // 整体超时，含连接+发送+读取 }; public async Task<OrderResult> CreateOrderAsync(OrderRequest req, CancellationToken ct) { // 1. 序列化：显式指定命名策略，避免 PascalCase 直接发出去 var json = JsonSerializer.Serialize(req, new JsonSerializerOptions { PropertyNamingPolicy = JsonNamingPolicy.CamelCase, DefaultIgnoreCondition = System.Text.Json.Serialization.JsonIgnoreCondition.WhenWritingNull }); // 2. 包成 StringContent，并在这里明确 mediaType 与编码 using var content = new StringContent(json, Encoding.UTF8, "application/json"); // 3. 发请求；ct 用于业务侧主动取消，和 Timeout 是两套机制 using var resp = await Http.PostAsync("v1/orders", content, ct).ConfigureAwait(false); // 4. 先读字符串再判断，错误响应体往往带业务错误码，不能直接丢 var body = await resp.Content.ReadAsStringAsync(ct).ConfigureAwait(false); if (!resp.IsSuccessStatusCode) throw new HttpRequestException($"HTTP {(int)resp.StatusCode}: {body}"); return JsonSerializer.Deserialize<OrderResult>(body, new JsonSerializerOptions { PropertyNameCaseInsensitive = true // 服务端字段大小写不固定时兜底 }) ?? throw new InvalidOperationException("响应体为空"); } } public record OrderRequest(string OrderNo, decimal Amount, string Currency); public record OrderResult(string TradeId, int Status);

这段代码有四个地方值得盯。第一，StringContent的三个参数是「内容、编码、媒体类型」，第三个参数写application/json之后，实际发出的头是Content-Type: application/json; charset=utf-8，charset 由第二个参数决定。很多人只写了new StringContent(json)，默认媒体类型是text/plain，服务端严格校验就会回 415。

第二，PropertyNamingPolicy = JsonNamingPolicy.CamelCase决定了 C# 的OrderNo发出去是orderNo。不加这一行，发出去就是OrderNo，对接方如果按 camelCase 解析，字段全丢，接口可能返回 200 但业务失败，这种问题最难查，因为状态码是对的。

第三，using var resp和using var content要保留。HttpResponseMessage和HttpContent都实现了IDisposable，不释放会把连接占住。注意using var的作用域是整个方法体，别在读完 body 之前就提前释放。

第四，ConfigureAwait(false)在类库代码里建议加，避免同步上下文死锁；在 ASP.NET Core 里影响不大，但保持习惯没坏处。

2.3 请求头到底该加在哪一层

请求头有三个落点，优先级从低到高：HttpClient.DefaultRequestHeaders、HttpRequestMessage.Headers、HttpContent.Headers。内容相关的头（Content-Type、Content-Length、Content-Encoding）属于第三层，只能挂在 content 上；其余业务头（Authorization、X-Request-Id、自定义签名）挂在第二层最稳。

如果你确实需要往DefaultRequestHeaders里加东西，务必只在初始化时加一次。它的典型翻车是：同一个静态 HttpClient，A 业务加了Authorization: Bearer a，B 业务加了Bearer b，因为默认头是共享的，最后谁后加谁生效，表现为「偶发鉴权失败」。一旦发现这种「时好时坏」的玄学问题，先去看有没有人往默认头里塞了动态值。

// 正确做法：请求级头，挂在 message 上，互不影响 using var msg = new HttpRequestMessage(HttpMethod.Post, "v1/orders") { Content = content }; msg.Headers.Add("X-Request-Id", Guid.NewGuid().ToString("N")); msg.Headers.Authorization = new System.Net.Http.Headers.AuthenticationHeaderValue("Bearer", token); using var resp = await Http.SendAsync(msg, HttpCompletionOption.ResponseHeadersRead, ct);

这里SendAsync的第二个参数是HttpCompletionOption。默认值ResponseContentRead表示「等响应体读完才返回」，ResponseHeadersRead表示「收到响应头就返回」，body 由你自己流式读。对返回体可能很大的接口，后者能显著降低内存峰值，也便于做流式解析；对返回体只有几百字节的普通 JSON 接口，两者差别可以忽略，用默认值更省心。

3. JSON 序列化选型：两套库的边界在哪

3.1 System.Text.Json 与 Newtonsoft.Json 的实际差异

.NET 生态里同时存在两套序列化器，选错不会立刻报错，但会在字段名、枚举、日期、空值这些地方悄悄偏掉。我按实际踩过的点列一下，这些差异比官方文档里那些性能对比更影响日常。

最常见的错配是「服务端用 Newtonsoft 序列化，客户端用 STJ 反序列化」。Newtonsoft 默认把枚举写成数字，STJ 读数字没问题；反过来 STJ 写数字、Newtonsoft 读数字也没问题。真正会炸的是日期：Newtonsoft 对DateTime默认按 ISO 8601 带偏移量输出，STJ 也是，但两边对DateTimeKind的处理不完全一致，跨时区服务上容易出现「时间差 8 小时」这类问题。我的习惯是 DTO 里统一用DateTimeOffset，两边都不纠结。

选型上没有绝对答案：新项目、只做 HTTP 对接、对性能敏感，用 STJ；已有大量 Newtonsoft 特性标注、需要复杂多态或JObject动态解析，继续用 Newtonsoft，别为了统一而统一。混用也可以，但要在边界处明确「这一段用的是哪套」，不要在一个 DTO 上同时挂两套特性。

3.2 用 DTO 固定请求体，别拼字符串

拼 JSON 字符串是我见过最容易出事的写法：少个逗号、引号没转义、金额用了浮点、中文没编码，全都要到联调时才发现。用 DTO 让编译器帮你挡一部分，剩下的交给序列化器。

using System.Text.Json.Serialization; public class PaymentRequest { [JsonPropertyName("merchant_id")] // 对接方要求下划线命名，逐个指定 public string MerchantId { get; set; } = ""; [JsonPropertyName("amount")] public decimal Amount { get; set; } // 金额用 decimal，不用 double [JsonPropertyName("currency")] public string Currency { get; set; } = "CNY"; [JsonPropertyName("extra")] public Dictionary<string, string>? Extra { get; set; } // 可选字段，null 时不输出 [JsonPropertyName("created_at")] public DateTimeOffset CreatedAt { get; set; } = DateTimeOffset.UtcNow; }

[JsonPropertyName]的优先级高于全局命名策略，字段命名不统一时逐个标最省事。金额那行是血泪经验：double在序列化时可能出现0.1 + 0.2 = 0.30000000000000004这种值，对账时会被财务打回来，decimal才是金额的正确类型。DateTimeOffset带上时区偏移，比裸DateTime少一层歧义。

Extra字段用Dictionary<string, string>，配合第 2 章里的DefaultIgnoreCondition = WhenWritingNull，为 null 时整个字段不出现。有些对接方对多余字段敏感，多一个 null 字段就报参数校验失败，这个配置能省掉一轮沟通。

3.3 反序列化的容错参数

服务端返回的 JSON 未必永远规整：有时多字段、有时少字段、有时数字是字符串。反序列化侧要提前想清楚「哪些可以忍、哪些必须炸」。

private static readonly JsonSerializerOptions ReadOptions = new() { PropertyNameCaseInsensitive = true, // 字段大小写不固定 NumberHandling = JsonNumberHandling.AllowReadingFromString, // "123" 也能读成 int ReadCommentHandling = JsonCommentHandling.Skip, // 容忍 // 注释 AllowTrailingCommas = true // 容忍尾逗号 }; public static T? SafeDeserialize<T>(string body) { try { return JsonSerializer.Deserialize<T>(body, ReadOptions); } catch (JsonException ex) { // 把原始报文带进异常，否则线上只能看到「解析失败」四个字 throw new InvalidOperationException($"JSON 解析失败，原始报文：{body[..Math.Min(body.Length, 500)]}", ex); } }

NumberHandling.AllowReadingFromString解决的是「服务端把金额写成"100.00"字符串」这类情况，不加就会抛JsonException。AllowTrailingCommas和注释跳过是针对手工拼接的响应体做的兜底。异常里带原始报文这一点很关键——线上排查时，没有原始报文的解析异常基本等于黑匣子，只能靠猜。

注意JsonSerializerOptions实例应当缓存复用。每次反序列化都 new 一个 options，STJ 无法复用内部元数据缓存，高并发下性能会明显下降。写成静态只读字段是标准做法。

4. 认证、超时与重试：让请求活过真实网络

4.1 超时是分层的，别只设一个

HttpClient.Timeout是整体超时，从发出请求到读完响应体，全都算在内。它管不到连接建立阶段的细节。真正分层的超时在SocketsHttpHandler上：

var handler = new SocketsHttpHandler { ConnectTimeout = TimeSpan.FromSeconds(5), // TCP+TLS 建连上限 PooledConnectionLifetime = TimeSpan.FromMinutes(5), // 连接存活上限，解决 DNS 变更 PooledConnectionIdleTimeout = TimeSpan.FromMinutes(2), // 空闲连接回收 MaxConnectionsPerServer = 20 // 单服务端并发连接上限 }; var client = new HttpClient(handler) { Timeout = TimeSpan.FromSeconds(20) // 整体上限，要大于 ConnectTimeout };

ConnectTimeout和Timeout的关系要理顺：整体超时必须大于建连超时，否则建连还没结束，整体超时先触发，日志里只会看到一次笼统的取消，分不清是网络不通还是服务端慢。我一般按「建连 5 秒、整体 15 到 30 秒」配，具体看接口的 P99 耗时。

PooledConnectionLifetime是很多人忽略的一项。HttpClient 长期存活时，连接池里的连接可能一直指向旧 IP，服务端做了 DNS 切换或扩容，客户端还在往老地址发，表现为「部分请求持续失败、重启进程就好」。设一个 5 分钟左右的存活上限，能把这个窗口压到可接受范围。

4.2 取消令牌和超时是两套机制

CancellationToken用于业务侧主动取消（用户关页面、上游请求已断开），Timeout用于保护自己不被慢接口拖死。两者都会让SendAsync抛TaskCanceledException，但含义完全不同。

using var cts = CancellationTokenSource.CreateLinkedTokenSource(ct); cts.CancelAfter(TimeSpan.FromSeconds(10)); // 业务级超时，比 HttpClient.Timeout 更细 try { using var resp = await client.SendAsync(msg, cts.Token); // ... } catch (OperationCanceledException) when (!ct.IsCancellationRequested) { // 不是外部取消，那就是超时 throw new TimeoutException("请求超时，耗时超过 10 秒"); }

CreateLinkedTokenSource把外部取消和本地超时串起来，when过滤条件用来区分「谁取消的」。.NET 5 之后，HttpClient自身超时会在TaskCanceledException的InnerException里塞一个TimeoutException，但依赖这个内部结构不如自己判ct.IsCancellationRequested稳。

4.3 重试之前先问幂等

POST 天然不幂等，同一个请求发两次可能产生两笔订单。重试这件事必须先和对接方确认语义，常见做法是带一个客户端生成的幂等键：

public async Task<string> PostWithRetryAsync(HttpRequestMessageFactory factory, CancellationToken ct) { var idempotencyKey = Guid.NewGuid().ToString("N"); // 同一次业务操作复用同一个 key var delays = new[] { 200, 500, 1200 }; // 毫秒，最多重试 3 次 for (var i = 0; i <= delays.Length; i++) { using var msg = factory.Create(); // 每次重试都要新建 message，不能复用 msg.Headers.Add("Idempotency-Key", idempotencyKey); try { using var resp = await client.SendAsync(msg, ct); if ((int)resp.StatusCode is >= 500 or 429) // 只对可恢复状态码重试 { if (i == delays.Length) return await resp.Content.ReadAsStringAsync(ct); await Task.Delay(delays[i], ct); continue; } return await resp.Content.ReadAsStringAsync(ct); // 4xx 直接返回，重试没意义 } catch (HttpRequestException) when (i < delays.Length) { await Task.Delay(delays[i], ct); // 网络层异常才重试 } } throw new InvalidOperationException("重试次数已用尽"); }

三个要点。其一，HttpRequestMessage不能被重复发送，第二次SendAsync会抛InvalidOperationException，所以每次重试都要重新构造，用工厂委托是最省事的写法。其二，只对 5xx、429 和网络异常重试，4xx 是参数或鉴权问题，重试一百次也是同一个结果。其三，退避时间要有间隔，连续快速重试在服务端看来和攻击没区别，反而会触发限流。

注意：幂等键要由业务侧生成并在一次业务操作内保持一致。每次重试都新生成一个 key，等于告诉服务端「这是新请求」，幂等保护直接失效。

4.4 多客户端场景用工厂管

一个进程里要对接多个服务、每个服务的 BaseAddress、超时、认证方式都不同时，IHttpClientFactory是标准解法：

// Program.cs（.NET 6+ 最小宿主写法） builder.Services.AddHttpClient("payment", c => { c.BaseAddress = new Uri("https://pay.example.invalid/"); c.Timeout = TimeSpan.FromSeconds(10); c.DefaultRequestHeaders.Add("Accept", "application/json"); }) .ConfigurePrimaryHttpMessageHandler(() => new SocketsHttpHandler { PooledConnectionLifetime = TimeSpan.FromMinutes(5) });

工厂内部维护 handler 池，按配置复用，避免每次 new 造成的端口耗尽，同时解决 DNS 刷新。注入到业务类里用IHttpClientFactory.CreateClient("payment")取，取到的 HttpClient 可以短生命周期使用，底层连接仍然复用。

5. 避坑与排查：五条从日志里翻出来的记录

5.1 415 之后补了头，还是 415

现象：返回415 Unsupported Media Type，检查代码发现已经设了Content-Type: application/json。

原因：头加在了HttpRequestMessage.Headers上，而不是 content 上。Content-Type属于内容头，挂在 message 的Headers集合里会抛异常或者被忽略，实际发出的请求仍然没有正确的内容类型。

解决：统一用new StringContent(json, Encoding.UTF8, "application/json")，或者content.Headers.ContentType = new MediaTypeHeaderValue("application/json")。排查时打开HttpClient的DefaultRequestHeaders和实际 message 的头对照一下，别只看代码里写了什么。

5.2 状态码 200，业务却报「参数缺失」

现象：接口返回 200，响应体里是业务错误码和「缺少 orderNo 字段」。

原因：C# 属性是OrderNo，序列化时没用 camelCase 策略，发出去是OrderNo，对接方按orderNo取值取不到。

解决：全局设PropertyNamingPolicy = JsonNamingPolicy.CamelCase，或者对每个字段加[JsonPropertyName]。验证方式很简单：在发送前把序列化结果打出来看一眼，比事后猜快得多。这类问题在联调阶段出现是好事，上线后才发现就要走紧急发版。

5.3 偶发超时，重启就好

现象：服务跑几个小时之后开始零星超时，重启进程立刻恢复。

原因：两种可能。一是 HttpClient 每次 new 且没释放，连接和端口堆积；二是长期存活的连接指向了旧的服务端 IP，DNS 变更后没有刷新。

解决：静态复用 HttpClient 或走IHttpClientFactory，并给 handler 设PooledConnectionLifetime。排查时看进程的 TCP 连接数，netstat或ss都行，连接数持续上涨基本就是前者。

5.4 中文变成乱码或 \uXXXX

现象：请求体里的中文到了服务端变成问号，或者日志里看到一堆\u4f60\u597d。

原因：前者是编码不一致，StringContent的第二个参数如果传了Encoding.Default（在某些环境是 GBK），而服务端按 UTF-8 解，就会乱码；后者是 STJ 默认把非 ASCII 字符转义成\uXXXX，功能上没问题，但人看着难受，某些老系统还会解析失败。

解决：编码固定Encoding.UTF8。要去掉转义，配置Encoder = JavaScriptEncoder.UnsafeRelaxedJsonEscaping：

var options = new JsonSerializerOptions { Encoder = System.Text.Encodings.Web.JavaScriptEncoder.UnsafeRelaxedJsonEscaping };

名字里带 Unsafe 是因为它放宽了 HTML 敏感字符的转义，如果序列化结果直接拼进 HTML 页面会有 XSS 风险。只做 HTTP 传输、不落地到前端页面时，用它是安全的。

5.5 在同步方法里调 .Result 卡死

现象：控制台程序正常，放到某些宿主环境里，调用PostAsync(...).Result或.Wait()之后整个线程卡住不动。

原因：同步阻塞等待异步任务，而异步方法内部捕捉了同步上下文，回调需要回到原线程执行，原线程却被.Result占着，互相等，形成死锁。

解决：一路 async 到底，不要在中途.Result。类库代码里所有 await 加ConfigureAwait(false)。如果调用方确实是同步接口无法改，用Task.Run(() => xxxAsync()).GetAwaiter().GetResult()把异步挪到线程池，但这只是绕开，不是修复，长期还是要把调用链改成异步。

6. 进阶：用 DelegatingHandler 统一日志与签名

6.1 把横切逻辑从业务里抽出来

每写一个接口就重复加签名头、打日志、算耗时，代码很快就会变成一坨。DelegatingHandler是 HttpClient 管道里的拦截器，请求发出前和响应回来后都能插一脚，适合放这类横切逻辑。

using System.Diagnostics; using System.Net.Http; using System.Threading; using System.Threading.Tasks; public class SigningLoggingHandler : DelegatingHandler { private readonly ILogger<SigningLoggingHandler> _logger; public SigningLoggingHandler(ILogger<SigningLoggingHandler> logger) => _logger = logger; protected override async Task<HttpResponseMessage> SendAsync( HttpRequestMessage request, CancellationToken ct) { var sw = Stopwatch.StartNew(); var traceId = Guid.NewGuid().ToString("N"); request.Headers.Add("X-Trace-Id", traceId); // 请求体只能读一次，读之前先 buffer，读完再重建 content string? reqBody = null; if (request.Content is not null) { reqBody = await request.Content.ReadAsStringAsync(ct); var bytes = System.Text.Encoding.UTF8.GetBytes(reqBody); request.Content = new ByteArrayContent(bytes); request.Content.Headers.ContentType = new System.Net.Http.Headers.MediaTypeHeaderValue("application/json"); } _logger.LogInformation("[{TraceId}] {Method} {Url} body={Body}", traceId, request.Method, request.RequestUri, reqBody); try { var resp = await base.SendAsync(request, ct); var respBody = await resp.Content.ReadAsStringAsync(ct); // 响应读完要重建，否则业务层拿到的 content 是空的 var buffer = System.Text.Encoding.UTF8.GetBytes(respBody); resp.Content = new ByteArrayContent(buffer); resp.Content.Headers.ContentType = new System.Net.Http.Headers.MediaTypeHeaderValue("application/json"); _logger.LogInformation("[{TraceId}] {Status} {Elapsed}ms resp={Body}", traceId, (int)resp.StatusCode, sw.ElapsedMilliseconds, respBody); return resp; } catch (Exception ex) { _logger.LogError(ex, "[{TraceId}] 请求异常，耗时 {Elapsed}ms", traceId, sw.ElapsedMilliseconds); throw; } } }

这段代码的核心是「读一次、重建一次」。HttpContent本质是流，被读过一次之后再读就是空字符串，如果 handler 里读了响应体但没重建，业务代码拿到的resp.Content永远是空的，这个 bug 极其隐蔽，日志里一切正常，只有业务层报「响应体为空」。重建时要连Content-Type一起补回去，ByteArrayContent默认不带媒体类型。

注册方式：

builder.Services.AddTransient<SigningLoggingHandler>(); builder.Services.AddHttpClient("payment", c => { /* 配置 */ }) .AddHttpMessageHandler<SigningLoggingHandler>();

Handler 的注册生命周期用Transient，不要用单例：它有InnerHandler状态，被多个 HttpClient 共享会出错。

6.2 怎么验证请求真的发对了

联调阶段最有效的手段不是看代码，是看报文。我一般做两件事。

第一件，构造一个本地回显服务，把收到的原始请求行、头、body 原样返回，客户端把响应打出来，对照是否和服务端约定一致。用HttpListener或者最小 API 起一个都行，几十行代码。

第二件，抓包。开发机上起抓包工具，过滤目标端口，看实际发出的Content-Type、Content-Length、字段名。代码里写的是 A，线上发的是 B，这种事只有抓包能看见。

最后一件事，把这一层做成可开关的。日志 Handler 在 Debug 下全量打 body，生产环境关掉或者只打摘要，金额、手机号这类字段要做脱敏。我吃过亏：为了排查临时打开全量日志，忘了关，敏感字段在日志系统里留了两个月。从那以后我每次加日志 Handler 都强制走一遍「默认关闭、按开关打开、字段白名单」这三步，宁可排查时多花五分钟，也不让原始报文裸奔。

希望帮到你。

本文还有配套的精品资源，点击获取