RestSharp v112 响应处理指南RestResponse 与 RestResponseT 属性全解析【免费下载链接】RestSharpSimple REST and HTTP API Client for .NET项目地址: https://gitcode.com/gh_mirrors/re/RestSharp本指南以 RestSharp v112 版本文档的 Handling responses 一章为核心系统讲解RestResponse与RestResponseT的每一个公开属性、ResponseStatus状态机的语义以及IsSuccessful的正确判定逻辑。读完本文你将能熟练读取响应头、正文与错误信息正确区分 HTTP 错误与传输层错误并在实际项目中使用泛型响应安全地获取反序列化结果。一、响应对象的两种形态RestResponse 与 RestResponseT在 RestSharp 中所有Execute{Method}Async函数都会返回RestResponse实例而以Execute{Method}AsyncT命名的泛型重载则返回RestResponseT其中T是响应对象反序列化目标的类型。这一点在 execute.md 中列举的调用签名中可以看到TaskRestResponse ExecuteGetAsync(RestRequest request, CancellationToken cancellationToken) TaskRestResponseT ExecuteGetAsyncT(RestRequest request, CancellationToken cancellationToken)从源码看两个类型是继承关系RestResponse.cs 中定义了RestResponseT它直接继承自RestResponse并额外增加了一个Data属性而 RestResponseBase.cs 中的RestResponseBase则承载了两个响应类型共享的全部公共属性。也就是说无论你是否使用泛型重载你拿到的响应对象都包含下面这套完整的属性。二、RestResponse 完整属性表RestResponse对象包含以下属性内容直接继承自 response.md 官方文档属性类型说明RequestRestRequest用于产生该响应的请求实例。ContentTypestring?响应内容类型MIME。响应无内容时为Null。ContentLengthlong?响应内容长度字节。响应无内容时为Null。ContentEncodingICollectionstring内容编码集合。响应无内容时为空集合。Contentstring?以字符串表示的响应内容。响应无内容时为Null。IsSuccessfulStatusCodebool指示响应是否成功即服务器未报告错误。ResponseStatusNone、Completed、Error、TimedOut、Aborted响应完成状态。注意状态为Completed的响应仍然可能携带 HTTP 错误。IsSuccessfulbool当IsSuccessfulStatusCode为true且ResponseStatus为Completed时为True。StatusDescriptionstring?响应状态描述若可用。RawBytesbyte[]?以字节数组表示的响应内容。响应无内容时为Null。ResponseUriUri?响应对应的 URI发生重定向时可能与请求 URI 不同。Serverstring?响应的Server头值。CookiesCookieCollection?响应携带的 Cookie 集合若有。HeadersHeaderParameter集合响应头。ContentHeadersHeaderParameter集合响应内容头。ErrorMessagestring?尝试请求时产生的传输层或其他非 HTTP 错误。ErrorExceptionException?执行请求时抛出的异常若有。VersionVersion?请求的 HTTP 协议版本。RootElementstring?序列化响应内容的根元素仅在反序列化器支持时生效。属性之间的细微差别Content与RawBytesContent是经过解码的字符串形式RawBytes是原始字节。需要保存文件、计算哈希或做二进制处理时优先使用RawBytes。Headers与ContentHeaders前者来自HttpResponseMessage.Headers如Server、Location后者来自HttpResponseMessage.Content.Headers如Content-Type、Content-Length。二者在 RestResponse.cs 的FromHttpResponse中分别通过GetHeaderParameters()填充。ResponseUri从源码可见其特殊逻辑——当状态码位于 300399 且存在Location头时会优先解析重定向后的 URI相对地址会基于请求 URI 组合见 RestResponse.cs。三、ResponseStatus五种完成状态ResponseStatus枚举定义于 Enum.cs五种取值的精确语义如下取值语义None不适用通常表示请求尚未发出构造RestResponseBase时的默认值见 RestResponseBase.cs。Completed请求正常完成——HttpResponseMessage.IsSuccessStatusCode为true或响应状态为404 Not Found。Error请求失败——IsSuccessStatusCode为false404 除外。TimedOut请求超时——超过RestRequest.Timeout规定的时间或HttpClient自身超时导致操作取消。Aborted操作被取消且原因不是超时。需要特别注意文档中的警告Completed并不等于业务成功。服务器返回500之类的错误码时网络传输本身是完成的此时ResponseStatus仍可能是Completed但IsSuccessfulStatusCode为false。因此判断一次请求是否真正成功请使用下一节的IsSuccessful而不是单独看ResponseStatus。一个快速判断的成功属性IsSuccessfulIsSuccessful的定义在 RestResponseBase.cspublic bool IsSuccessful IsSuccessStatusCode ResponseStatus ResponseStatus.Completed;它要求两个条件同时成立HTTP 状态码位于成功区间IsSuccessStatusCode true没有发生传输层错误、超时或取消ResponseStatus Completed。换句话说IsSuccessful是服务器层面成功与传输层面成功的合取。在编写业务代码时用if (response.IsSuccessful)作为总入口可以同时覆盖 HTTP 错误与网络异常两类失败场景。四、RestResponseT 的额外属性DataRestResponseT在继承全部上述属性的基础上额外增加一个属性属性类型说明DataT?反序列化后的响应对象。当响应无内容、反序列化器无法理解响应内容或请求失败时该属性为Null。Data由ExecuteAsyncT系列泛型重载在获得响应后调用客户端配置的反序列化器填充其声明位于 RestResponse.cspublic partial class RestResponseT(RestRequest request) : RestResponse(request) { public T? Data { get; set; } }典型用法var response await client.ExecuteGetAsyncTResponse(request, cancellationToken); if (response.IsSuccessful response.Data is not null) { // 使用 response.Data 中的业务数据 } else { // 从 response.ErrorMessage / response.StatusCode 中提取失败原因 }需要注意Data为Null有三种可能响应体为空、反序列化失败、请求本身失败。所以即便IsSuccessful为真也应防御性地对Data判空。五、从源码看响应对象的构建过程要真正理解这些属性的来源可以阅读 RestResponse.cs 中的FromHttpResponse方法。RestSharp 在收到HttpResponseMessage后按以下步骤组装RestResponse读取响应流并转为字节数组stream.ReadAsBytes将字节按客户端配置的编码options.Encoding转为字符串填充Content逐项填充ContentType、ContentLength、ContentEncoding、ContentHeaders、Headers、Server、StatusCode、StatusDescription、ResponseStatus、Version等将 HTTP 响应头的Location等用于计算ResponseUri将request.RootElement透传到RootElement供支持根元素的反序列化器使用依据options.SetErrorExceptionOnUnsuccessfulStatusCode决定是否在非成功状态码时填充ErrorException。这条构建路径解释了为什么Content、ContentType、ContentLength在响应无内容时会为Null——它们都来源于HttpResponseMessage.Content而Content本身为空时这些属性自然无从谈起。六、配套扩展方法读取头与抛出错误除了属性RestSharp 还提供了与响应对象配套的扩展方法读取响应头RestResponseExtensions.cs 提供了按名称读取头的方法大小写不敏感匹配// 单个值 string? etag response.GetHeaderValue(ETag); // 多个值同名头出现多次时 string[] values response.GetHeaderValues(Set-Cookie); // 内容头同理 string? contentType response.GetContentHeaderValue(Content-Type); string[] contentHeaders response.GetContentHeaderValues(Content-Encoding);抛出错误异常ResponseThrowExtension.cs 提供了ThrowIfError()它会根据ResponseStatus生成对应异常并抛出Aborted→HttpRequestException(Request aborted, ErrorException)Error→ 返回原始ErrorExceptionTimedOut→TimeoutException(Request timed out, ErrorException)该映射逻辑见 RestResponseBase.cs 的GetException()方法var response await client.ExecuteAsync(request, cancellationToken); var checked response.ThrowIfError(); // 失败时抛出成功时原样返回这在希望把异常处理交给调用方的中间层代码中非常实用。七、错误场景的判定要点与测试佐证文档强调Execute前缀的调用在服务器返回错误时不会抛异常而是把错误信息放进响应对象方便调用方检查参见 execute.md 的 Beware of errors 提示。因此判断失败需要组合多个信号传输层/取消问题看ResponseStatus是否为TimedOut、Aborted、Error以及ErrorMessage/ErrorException是否有值HTTP 层问题看IsSuccessfulStatusCode与StatusCode/StatusDescription反序列化问题泛型响应中Data null。仓库中的测试也印证了这一模型例如 ErrorMessageTests.cs 中直接断言response.ResponseStatus.Should().Be(ResponseStatus.Error)验证了传输错误会反映到ResponseStatus上。GetException()的实现也说明只有在ResponseStatus明确为错误状态时才产生异常这也是ThrowIfError只在真正失败时抛出的原因。八、小结非泛型Execute{Method}Async返回RestResponse泛型版本返回RestResponseT额外带DataIsSuccessful是HTTP 成功 传输完成的双重判定是业务代码的首选判断入口ResponseStatus的Completed不代表业务成功必须结合IsSuccessfulStatusCode一起看响应头、Cookie、原始字节、错误信息分别对应Headers/ContentHeaders、Cookies、RawBytes、ErrorMessage/ErrorException属性需要把错误转为异常时可以使用ThrowIfError()扩展方法。建议进一步阅读 execute.md如何发起请求、error-handling.md错误处理策略以及 serialization.mdData反序列化机制配合 RestResponse.cs 与 RestResponseBase.cs 的源码即可完整掌握 RestSharp 的响应处理链路。【免费下载链接】RestSharpSimple REST and HTTP API Client for .NET项目地址: https://gitcode.com/gh_mirrors/re/RestSharp创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考