后端API设计【免费下载链接】RestSharpSimple REST and HTTP API Client for .NET项目地址https://gitcode.com/gh_mirrors/re/RestSharp点击查看免费下载导读本文以 RestSharp v1.13 官方文档 usage/request.md 为骨架系统讲解如何构建一个RestRequest实例包括创建请求、添加各类参数Header、GetOrPost、QueryString、UrlSegment、Cookie、使用AddObject/AddObjectStatic批量映射对象属性、构造 JSON / XML / 字符串请求体以及上传文件等完整流程。读完本文你将掌握 RestSharp 请求构建的每一种参数类型的语义、行为差异与底层实现能够直接编写可运行的 REST 客户端代码。创建请求从 resource 到 MethodRestSharp 中所有请求都围绕RestRequest展开。使用RestClient发起请求之前必须先创建一个请求实例var request new RestRequest(resource); // resource 是相对于客户端 BaseUrl 的子路径resource是客户端基础地址的子路径。从源码可见RestRequest的默认构造函数将方法设为Method.Get见 RestRequest.cs因此默认请求类型是 GET。你可以通过设置Method属性覆盖也可以直接用构造函数重载指定var request new RestRequest(resource, Method.Post);构造函数签名对应源码中的RestRequest(string? resource, Method method Method.Get)见 RestRequest.cs。此外还有接受Uri的重载若传入绝对 URI则以AbsoluteUri作为 resource若为相对 URI则取其OriginalString见 RestRequest.cs。一个值得注意的细节当resource字符串中带有查询串如search?foobar时构造函数会自动解析该查询串并转换为QueryParameter加入请求同时把Resource还原为不含查询串的部分见 RestRequest.cs。请求创建后就可以向它添加各类参数。RestSharp 支持的参数类型与用途如下表参数类型添加方式作用位置说明HeaderParameterAddHeaderHTTP 头随请求发送的请求头GetOrPostParameterAddParameterURL 或请求体按 HTTP 方法决定去向QueryParameterAddQueryParameterURL 查询串始终追加到 URLUrlSegmentParameterAddUrlSegmentURL 路径占位符替换{placeholder}CookieAddCookieCookie 头请求级 CookieBodyParameter / JsonParameter / XmlParameterAddJsonBody/AddXmlBody/AddStringBody/AddBody请求体请求正文Request headers请求头Header 参数以参数名为头名、参数值为头值作为 HTTP 头随请求发送。常用的添加方法有三个AddHeader(string name, string value); AddHeaderT(string name, T value); // value 会被转换为字符串 AddOrUpdateHeader(string name, string value); // 已存在同名头时直接替换用法示例var request new RestRequest(/path).AddHeader(X-Key, someKey);从源码看AddHeader(string, string)内部创建HeaderParameter见 RestRequestExtensions.Headers.csAddOrUpdateHeader则通过AddOrUpdateParameter替换同名已有参数见 RestRequestExtensions.Headers.cs。泛型重载AddHeaderT要求T : struct值会按指定的 culture默认InvariantCulture格式化为字符串见 RestRequestExtensions.Headers.cs。若需要批量添加还有AddHeaders/AddOrUpdateHeaders它们会先检查是否存在重复键大小写不敏感有重复则抛出ArgumentException见 RestRequestExtensions.Headers.cs。RestSharp 在调用资源时会自动区分请求头与内容头content headers。你也可以把 Header 参数加在客户端上这样每次请求都会带上——非常适合鉴权头等公共头client.AddDefaultHeader(string name, string value);源码中AddDefaultHeader实现在 RestClient.Extensions.Params.cs它同样以HeaderParameter加入客户端默认参数集合。:::warning 避免手动设置 Content-Type 头 RestSharp 默认会使用正确的内容类型。除非你非常确定需要否则不要手动给请求添加Content-Type头如需自定义内容类型请直接设置到 body 参数 本身。 :::Get or Post parameters默认参数类型GetOrPostParameter是 RestSharp 的默认参数类型通过AddParameter添加request .AddParameter(name1, value1) .AddParameter(name2, value2);GetOrPost的行为随 HTTP 方法而变化GET 请求参数追加到 URL形如url?name1value1name2value2POST / PUT 请求取决于请求是否携带文件无文件时参数以name1value1name2value2的形式作为请求体发送Content-Type 为application/x-www-form-urlencoded有文件时发送multipart/form-data请求每个参数以如下形式出现在 multipart 中Content-Type: text/plain; charsetutf-8 Content-Disposition: form-data; nameparameterName ParameterValue两种情况下参数名与参数值默认都会被 URL 编码除非显式指定不编码request.AddParameter(name, Væ üé, false); // 不编码 value在 multipart 表单调用中有时需要覆盖参数默认的内容类型可通过设置参数对象的ContentType属性实现。下面的代码创建一个值为 JSON 的 POST 参数并指定适当的内容类型var parameter new GetOrPostParameter(someJson, {\attributeFormat\:\pdf\}) { ContentType application/json }; request.AddParameter(parameter);当请求使用 multipart 内容时该参数将携带指定内容类型发送Content-Type: application/json; charsetutf-8 Content-Disposition: form-data; namesomeJson {attributeFormat:pdf}GetOrPost参数同样可以注册为客户端默认参数从而附加到该客户端发起的每个请求client.AddDefaultParameter(foo, bar);其行为与请求级参数完全一致只是作用于全部请求。Query string查询串参数QueryString与GetOrPost类似但无论请求方法是什么始终把参数以url?name1value1name2value2形式追加到 URL。示例var client new RestClient(https://search.me); var request new RestRequest(search) .AddParameter(foo, bar); var response await client.GetAsyncSearchResponse(request);该代码会向https://search.me/search?foobar发送 GET 请求。对于 POST 风格的请求则需要显式添加查询串参数request.AddQueryParameter(foo, bar);AddQueryParameter内部创建QueryParameterencode参数默认为true见 RestRequestExtensions.Query.cs。有时需要禁止 RestSharp 对查询串参数编码将encode参数设为false即可request.AddQueryParameter(foo, bar/fox, false);与前述类型一致查询串参数也可注册为客户端默认参数client.AddDefaultQueryParameter(foo, bar);上面这行代码会使该客户端实例发起的所有请求都在查询串中携带foobar。其底层实现在 RestClient.Extensions.Params.cs以QueryParameter形式加入默认参数集合。Using AddObject把对象属性批量映射为参数如果你有一组参数需要一次性添加可以先把它们收集进一个对象再调用AddObjectvar params new { status 1, priority high, ids new [] { 123, 456 } }; request.AddObject(params);它等价于request.AddParameter(status, 1); request.AddParameter(priority, high); request.AddParameter(ids, 123,456);注意AddObject只支持基本类型primitive属性也支持如上所示的基本类型集合。从源码看AddObject通过反射获取对象属性然后逐个调用AddParameter(prop.Name, prop.Value, prop.Encode)见 RestRequestExtensions.Object.cs。它还有可选参数includedProperties用于指定只提取哪些属性。如果需要覆盖属性名或格式可以使用RequestProperty特性public class RequestModel { // 覆盖名称与格式 [RequestProperty(Name from_date, Format d)] public DateTime FromDate { get; set; } } // 添加到请求 request.AddObject(new RequestModel { FromDate DateTime.Now });此时请求会得到一个名为from_date的 GET 或 POST 参数值为当前日期的短日期格式。RequestPropertyAttribute定义在 ObjectParser.cs支持Name重命名、FormatDateTime/数值格式化字符串、ArrayQueryType数组序列化方式默认CommaSeparated可设为ArrayParameters以生成name[]形式、Encode是否编码默认true四个属性。Using AddObjectStatic预编译表达式的高性能版本AddObjectStaticT(...)使用预编译表达式来获取属性值与每次调用都走反射的AddObject相比它会把“从类型T的对象中取属性”的函数缓存起来因此快得多。AddObjectStatic支持自定义参数名与格式也支持传入属性名单指定哪些属性需要作为参数——当类型T含有不需要随 HTTP 调用发送的属性时这一选项非常有用。其核心实现依赖PropertyCacheT在 RestRequestExtensions.Object.cs 中调用PropertyCacheT.GetParameters(obj, includedProperties)而PropertyCache.Populator使用System.Linq.Expressions将属性 getter 编译为FuncT, object委托并缓存见 PropertyCache.Populator.cs同时根据属性类型IFormattable、IConvertible、IEnumerable等选择不同的转换与序列化路径CSV 拼接或数组参数。使用自定义参数名或格式时同样借助RequestProperty特性。示例class TestObject { [RequestProperty(Name some_data)] public string SomeData { get; set; } [RequestProperty(Format d)] public DateTime SomeDate { get; set; } [RequestProperty(Name dates, Format d)] public DateTime[] DatesArray { get; set; } public int Plain { get; set; } public DateTime[] PlainArray { get; set; } }URL segment parameter路径占位符替换与GetOrPost不同URL segment 参数用于替换请求 URL 中的占位符var request new RestRequest(health/{entity}/status) .AddUrlSegment(entity, s2);请求执行时RestSharp 会把 URL 中的任何{placeholder}与同名不含{}参数匹配并替换为参数值因此上面的代码最终请求 URL 为health/s2/status。从源码看AddUrlSegment创建UrlSegmentParameter并通过AddOrUpdateParameter添加同名占位符可覆盖encode默认true见 RestRequestExtensions.Url.cs。泛型重载AddUrlSegmentT同样支持指定 culture 格式化值见 RestRequestExtensions.Url.cs。URL segment 参数同样可以作为客户端默认参数添加client.AddDefaultUrlSegment(foo, bar);底层实现在 RestClient.Extensions.Params.cs会为客户端所有请求的 URL 占位符填充该值。Cookies请求级与客户端级 Cookie使用AddCookie方法即可向请求添加 Cookierequest.AddCookie(foo, bar);两个参数的形式会把域解析推迟到执行时刻——Cookie 域从请求 URL 推断。如果需要显式指定路径和域使用四个参数的重载request.AddCookie(foo, bar, /path, example.com);RestSharp 会把请求中的 Cookie 作为 Cookie 头发送然后从响应中提取匹配的 Cookie。你可以通过RestResponse.Cookies属性类型为CookieCollection观察和提取响应 Cookie见 RestResponseBase.cs。在请求级别存在一个CookieContainer实例。你可以把预先填充好的容器赋给request.CookieContainer也可以让容器在执行时自动创建。四参数AddCookie重载会立即填充容器而两参数形式先把 Cookie 存入PendingCookies列表见 RestRequest.cs直到请求执行时才解析。执行时RestSharp 会从容器中取出全部 Cookie 生成 Cookie 头而不是直接使用容器本身——因为 Cookie 容器通常配置在HttpClientHandler级别同一客户端发起的多个请求之间会共享 Cookie这在多数场景下是有害的。如果你的用例确实需要在客户端实例的各请求之间共享 Cookie可以使用客户端级别的CookieContainer它必须通过 options 属性提供。你可以使用容器 API 向其中添加 Cookie但响应 Cookie 不会自动加入容器需要时可以在代码中从响应的Cookies属性取出再手动添加到通过IRestClient.Options.CookieContainer属性访问的客户端级容器。Request Body 请求体RestSharp 支持多种添加请求体的方式AddJsonBody—— JSON 负载AddXmlBody—— XML 负载AddStringBody—— 预序列化负载官方推荐使用AddJsonBody或AddXmlBody而不是带BodyParameter的AddParameter——前两者会设置正确的请求类型并替你完成序列化工作。当发起POST、PUT或PATCH请求并添加了GetOrPost参数时RestSharp 默认会把它们作为 URL 编码的表单请求体发送当请求同时有文件时则发送multipart/form-data请求。你也可以通过把AlwaysMultipartFormData属性设为true强制 RestSharp 以multipart/form-data发送请求体对应源码属性定义见 RestRequest.cs。如有需要可以指定自定义的请求体内容类型——contentType参数在所有添加请求体的重载中均可使用。注意无法添加客户端级别的默认请求体参数。String body字符串请求体如果你有预序列化的负载例如一段 JSON 字符串可以用AddStringBody将其作为请求体参数添加。必须指定内容类型以便远端端点知道如何处理请求体。例如const json { \data\: { \foo\: \bar\ } }; request.AddStringBody(json, ContentType.Json);AddStringBody(string, ContentType)直接创建BodyParameter见 RestRequestExtensions.Body.cs还有接受DataFormat的重载会由ContentType.FromDataFormat推导内容类型见 RestRequestExtensions.Body.cs。JSON bodyJSON 请求体调用AddJsonBody时RestSharp 会为你完成以下工作指示 RestClient 在发起请求时把对象参数序列化为 JSON将内容类型设置为application/json将请求体的内部数据类型设置为DataType.Json。示例var param new MyClass { IntData 1, StringData test123 }; request.AddJsonBody(param);可以通过contentType参数覆盖默认内容类型request.AddJsonBody(param, text/x-json);如果向AddJsonBody传入预序列化的字符串它会原样发送。AddJsonBody会检测参数是否为字符串若是则作为带 JSON 内容类型的字符串请求体添加。本质上这意味着使用AddJsonBody时顶层字符串不会被序列化为 JSON。要解决此问题可以使用带forceSerialize参数的AddJsonBody重载强制把字符串序列化为 JSONconst string payload requestBody: { content: { application/json: { schema: { type: string } } } },; request.AddJsonBody(payload, forceSerialize: true); // 字符串会被序列化 request.AddJsonBody(payload); // 字符串不会被序列化原样发送从源码可以看到这一分支逻辑AddJsonBodyT(T obj, ...)中若obj is string str则走AddStringBody(str, DataFormat.Json)否则创建JsonParameter见 RestRequestExtensions.Body.cs而带forceSerialize的重载在forceSerialize: true时直接创建JsonParameter见 RestRequestExtensions.Body.cs。XML bodyXML 请求体调用AddXmlBody时RestSharp 会为你完成以下工作指示 RestClient 在发起请求时把对象参数序列化为 XML将内容类型设置为application/xml将请求体的内部数据类型设置为DataType.Xml。源码实现在 RestRequestExtensions.Body.cs其中AddXmlBodyT还接受可选参数xmlNamespace用于指定 XML 命名空间。:::warning 不要把 XML 字符串传给AddXmlBody那样不会生效 :::Uploading files上传文件使用RestRequest的AddFile函数即可向请求添加文件。主函数接受FileParameter参数request.AddFile(fileParameter);你可以用FileParameter.Create接受字节数组或FileParameter.FromFile从磁盘加载文件实例化文件参数见 FileParameter.cs。FromFile会校验文件是否存在不存在时抛出FileNotFoundExceptionCreate的字节数组重载内部把字节写入MemoryStream再返回流。还有多个封装了FileParameter创建的扩展函数// 从磁盘添加文件 AddFile(parameterName, filePath, contentType); // 添加字节数组 AddFile(parameterName, bytes, fileName, contentType); // 添加 getFile 函数返回的流 AddFile(parameterName, getFile, fileName, contentType);这三个重载的签名与源码一一对应见 RestRequestExtensions.File.cs磁盘路径重载调用FileParameter.FromFile字节与流重载调用FileParameter.Create。请记住AddFile会设置所有必要的头因此不要手动设置内容头。你还可以为AddFile调用提供文件上传选项选项如下DisableFilenameEncoding默认false设为true时RestSharp 不会对Content-Disposition头中的文件名进行编码DisableFilenameStar默认true设为true时RestSharp 不会向Content-Disposition头添加filename*参数。FileParameterOptions类定义见 FileParameter.cs两个选项默认值分别为false与true。选项使用示例var options new FileParameterOptions { DisableFilenameEncoding true, DisableFilenameStar false }; request.AddFile(file, filePath, options: options);上面代码中的选项组合通常有助于上传文件名含非 ASCII 字符的文件——DisableFilenameEncoding true避免对文件名做百分号编码DisableFilenameStar false允许添加filename*参数使服务器能正确识别带非 ASCII 字符的原始文件名。延伸阅读请求执行与响应处理见 usage/execute.md 与 usage/response.md客户端配置与基础用法见 usage/client.md 与 usage/basics.md序列化与内容类型见 advanced/serialization.md相关核心源码RestRequest.cs、RestRequestExtensions.Body.cs、RestRequestExtensions.File.cs、PropertyCache.Populator.cs、ObjectParser.cs赞分享后端API设计【免费下载链接】RestSharpSimple REST and HTTP API Client for .NET项目地址https://gitcode.com/gh_mirrors/re/RestSharp点击查看免费下载相关推荐Litestar HTTP 请求体处理实战data 参数、Body 注解、文件上传与请求体大小限制Litestar HTTP 请求体处理实战data 参数、Body 注解、文件上传与请求体大小限制 本文围绕 Litestar 官方的 Request 文档后端Web框架TypeSpec HTTP 库 Multipart 请求完整指南从 multipartBody 到 HttpPart 文件上传TypeSpec HTTP 库 Multipart 请求完整指南从 multipartBody 到 HttpPart 文件上传 导读 本文以 TypeSp编程语言编译器后端终极指南如何用Alamofire轻松构建iOS网络请求终极指南如何用Alamofire轻松构建iOS网络请求 Alamofire是一个用于iOS和macOS的网络库提供了RESTful API的封装和SDK帮网络通信后端上一篇AriaNg终极配置指南3步快速搭建现代化下载管理平台下一篇命令行上传Zenodo大文件的终极解决方案zenodo-upload创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考