一、概述WebAPI通讯模块实现了基于HTTP/HTTPS协议的RESTful API客户端功能支持GET、POST等多种HTTP方法提供JSON数据序列化/反序列化、Bearer Token认证、表单提交等功能。二、通讯报文原理2.1 HTTP协议基础WebAPI通讯基于HTTP/HTTPS协议采用请求-响应模式客户端 → HTTP请求 → 服务器 服务器 → HTTP响应 → 客户端2.2 HTTP请求报文结构POST /api/resource HTTP/1.1 Host: example.com Content-Type: application/json Authorization: Bearer eyJhbGciOiJIUzI1NiIs... Content-Length: 123 {key:value,data:123}请求报文组成请求行方法POST/GET、URL路径、HTTP版本请求头Content-Type、Authorization等请求体JSON数据、表单数据等2.3 HTTP响应报文结构HTTP/1.1 200 OK Content-Type: application/json Content-Length: 456 {status:success,result:{data:456}}响应报文组成状态行HTTP版本、状态码200/401/500等、状态描述响应头Content-Type、Content-Length等响应体JSON数据、错误信息等2.4 JSON数据格式请求JSON示例{userName:admin,password:123456,deviceCode:DEVICE001}响应JSON示例{code:200,message:success,data:{token:eyJhbGciOiJIUzI1NiIs...,expireTime:2026-12-31T23:59:59}}2.5 Bearer Token认证流程1. 客户端发送登录请求用户名密码 2. 服务器验证并返回Token 3. 客户端保存Token 4. 后续请求携带Token: Authorization: Bearer {token} 5. 服务器验证Token后返回数据2.6 OAuth2表单提交使用application/x-www-form-urlencoded格式POST /oauth/token HTTP/1.1 Content-Type: application/x-www-form-urlencoded grant_typepasswordusernameadminpassword123456client_idmyapp三、调用的库和方法3.1 核心库RestSharp库版本通过NuGet包管理作用简化HTTP客户端操作命名空间RestSharp主要类RestClientHTTP客户端负责发送请求RestRequestHTTP请求封装IRestResponseHTTP响应接口MethodHTTP方法枚举GET/POST/PUT/DELETENewtonsoft.Json库版本JSON.NET作用JSON序列化/反序列化命名空间Newtonsoft.Json主要方法JsonConvert.SerializeObject()对象→JSON字符串JsonConvert.DeserializeObject()JSON字符串→对象3.2 核心类WebApiHelper3.2.1 HttpPost 方法功能发送JSON格式POST请求方法签名publicstaticIRestResponseHttpPostT(stringurl,Tbody)参数说明url请求的API地址body请求体对象泛型会被序列化为JSON实现代码publicstaticIRestResponseHttpPostT(stringurl,Tbody){// 创建HTTP客户端RestClientclientnewRestClient(url);client.Timeout5000;// 创建请求RestRequestrequestnewRestRequest(Method.POST);request.AddHeader(Content-Type,application/json);request.AddJsonBody(body,application/json);// 生成请求JSON用于日志stringrequestJsonJsonConvert.SerializeObject(body,Formatting.Indented);// 执行请求IRestResponseresponseclient.Execute(request);// 触发JSON回调事件RaiseJsonDataEvent(requestJson,response.Content);returnresponse;}调用示例varrequestDatanew{userNameadmin,password123456};varresponseWebApiHelper.HttpPost(https://api.example.com/login,requestData);3.2.2 HttpPostBearerToken 方法功能发送带Bearer Token的POST请求方法签名publicstaticIRestResponseHttpPostBearerTokenT(stringurl,stringtoken,Tbody)参数说明url请求的API地址tokenBearer Token字符串body请求体对象实现代码publicstaticIRestResponseHttpPostBearerTokenT(stringurl,stringtoken,Tbody){RestClientclientnewRestClient(url);client.Timeout5000;RestRequestrequestnewRestRequest(Method.POST);request.AddHeader(Content-Type,application/json);request.AddHeader(Authorization,$Bearer{token});request.AddJsonBody(body,application/json);stringrequestJsonJsonConvert.SerializeObject(body,Formatting.Indented);IRestResponseresponseclient.Execute(request);RaiseJsonDataEvent(requestJson,response.Content);returnresponse;}调用示例varrequestDatanew{deviceIdDEVICE001,timestampDateTime.Now.ToString()};varresponseWebApiHelper.HttpPostBearerToken(https://api.example.com/api/data,eyJhbGciOiJIUzI1NiIs...,requestData);3.2.3 HttpPost (表单提交) 方法功能发送表单格式POST请求OAuth2等场景方法签名publicstaticIRestResponseHttpPost(stringurl,Dictionarystring,stringpara)参数说明url请求的API地址para表单参数字典实现代码publicstaticIRestResponseHttpPost(stringurl,Dictionarystring,stringpara){RestClientclientnewRestClient(url);client.Timeout5000;RestRequestrequestnewRestRequest(Method.POST);request.AddHeader(Content-Type,application/x-www-form-urlencoded);// 构建表单数据字符串StringBuilderformDatanewStringBuilder();foreach(stringkeyinpara.Keys){if(formData.Length0){formData.Append();}formData.Append(${Uri.EscapeDataString(key)}{Uri.EscapeDataString(para[key])});}request.AddParameter(application/x-www-form-urlencoded,formData.ToString(),ParameterType.RequestBody);// 生成请求JSON用于日志stringrequestJsonJsonConvert.SerializeObject(para,Formatting.Indented);IRestResponseresponseclient.Execute(request);RaiseJsonDataEvent(requestJson,response.Content);returnresponse;}调用示例varformDatanewDictionarystring,string{{grant_type,password},{username,admin},{password,123456},{client_id,myapp}};varresponseWebApiHelper.HttpPost(https://api.example.com/oauth/token,formData);3.2.4 HttpGet 方法功能发送GET请求方法签名publicstaticIRestResponseHttpGetT(stringurl)参数说明url请求的API地址可包含查询参数实现代码publicstaticIRestResponseHttpGetT(stringurl){RestClientclientnewRestClient(url);client.Timeout5000;RestRequestrequestnewRestRequest(Method.GET);returnclient.Execute(request);}调用示例varresponseWebApiHelper.HttpGetobject(https://api.example.com/api/users?page1size10);3.2.5 FormatJson 方法功能格式化JSON字符串美化输出方法签名publicstaticstringFormatJson(stringjson)实现代码publicstaticstringFormatJson(stringjson){try{objectobjJsonConvert.DeserializeObject(json);returnJsonConvert.SerializeObject(obj,Formatting.Indented);}catch{returnjson;}}3.3 事件机制OnJsonDataReceived 事件功能当收到HTTP响应时触发用于UI显示请求/响应数据事件定义publicstaticeventActionstring,stringOnJsonDataReceived;事件参数string requestJson请求JSON字符串string responseJson响应JSON字符串触发位置所有HTTP方法执行后都会触发此事件使用示例// 在ViewModel中订阅事件WebApiHelper.OnJsonDataReceived(request,response){// 更新UI显示请求和响应RequestJsonWebApiHelper.FormatJson(request);ResponseJsonWebApiHelper.FormatJson(response);};四、数据流程4.1 完整的API调用流程用户操作 ↓ ViewModel调用WebApiHelper方法 ↓ 创建RestClient和RestRequest ↓ 设置请求头Content-Type、Authorization等 ↓ 序列化请求数据为JSON ↓ 发送HTTP请求 ↓ 接收HTTP响应 ↓ 触发OnJsonDataReceived事件 ↓ UI更新显示请求/响应数据4.2 Bearer Token认证流程1. 获取Token HttpPost(loginUrl, loginData) → Token 2. 保存Token 存储到ViewModel或配置文件 3. 使用Token访问API HttpPostBearerToken(apiUrl, token, data) → Data 4. Token过期处理 捕获401错误 → 重新获取Token → 重试请求五、错误处理5.1 常见HTTP状态码状态码含义处理方式200成功正常处理响应数据400请求错误检查请求参数格式401未授权重新登录获取Token403禁止访问检查权限配置404资源不存在检查API URL500服务器错误联系API提供方5.2 异常处理示例try{varresponseWebApiHelper.HttpPost(url,data);if(response.StatusCodeSystem.Net.HttpStatusCode.OK){// 成功处理varresultJsonConvert.DeserializeObjectResponseModel(response.Content);}elseif(response.StatusCodeSystem.Net.HttpStatusCode.Unauthorized){// 401未授权重新登录ShowErrorMessage(Token已过期请重新登录);}else{// 其他错误ShowErrorMessage($请求失败{response.StatusCode});}}catch(Exceptionex){// 网络异常或JSON解析错误ShowErrorMessage($请求异常{ex.Message});}六、性能优化6.1 超时设置client.Timeout5000;// 5秒超时6.2 连接池复用建议创建单例RestClient实例避免频繁创建/销毁。6.3 异步调用对于耗时API调用使用异步方法避免阻塞UI线程awaitTask.Run((){varresponseWebApiHelper.HttpPost(url,data);});七、安全性7.1 HTTPS通信生产环境必须使用HTTPS加密传输。7.2 Token存储不要在日志中输出完整Token建议使用安全存储如Windows Credential Manager7.3 敏感数据加密密码等敏感数据在传输前应加密处理。八、总结WebAPI通讯模块提供了完整的HTTP客户端功能多种HTTP方法支持GET、POST等常用方法认证支持Bearer Token、OAuth2表单认证JSON处理自动序列化/反序列化事件机制请求/响应数据实时通知错误处理完善的异常捕获和状态码处理该模块可广泛应用于对接各类RESTful API服务如云平台、IoT平台、AI服务等场景。