产品及架构介绍
定义
命名空间:TouchSocket.WebApi
程序集:TouchSocket.WebApi.dll
一、说明
WebApi是通用的Rpc调用,与编程语言无关,与操作系统无关。其路由机制模仿AspNetCore,可实现很多路由机制。但是因为http兼容性错综复杂,所以目前TouchSocket的WebApi仅支持GET、POST函数。使用体验接近于AspNetCore。
二、特点
- 高性能,100个客户端,10w次调用,仅用时17s。
- 全异常反馈 。
- 支持大部分路由规则。
- 支持js、Android等调用。
三、定义服务
在服务器端中新建一个类,继承于RpcServer类(或实现IRpcServer),然后在该类中写公共方法,并用WebApi属性标签标记。
public partial class ApiServer : RpcServer
{
private readonly ILog m_logger;
public ApiServer(ILog logger)
{
this.m_logger = logger;
}
[WebApi(HttpMethodType.GET)]
public int Sum(int a, int b)
{
return a + b;
}
}
四、启动服务器
更多注册Rpc的方法请看注册Rpc服务
var service = new HttpService();
await service.SetupAsync(new TouchSocketConfig()
.SetListenIPHosts(7789)
.ConfigureContainer(a =>
{
a.AddConsoleLogger();
a.AddRpcStore(store =>
{
store.RegisterServer<ApiServer>();//注册服务
});
})
.ConfigurePlugins(a =>
{
a.UseCheckClear();
a.UseWebApi();
//此插件是http的兜底插件,应该最后添加。作用是当所有路由不匹配时返回404.且内部也会处理Option请求。可以更好的处理来自浏览器的跨域探测。
a.UseDefaultHttpServicePlugin();
}));
await service.StartAsync();
Console.WriteLine("以下连接用于测试webApi");
Console.WriteLine($"使用:http://127.0.0.1:7789/ApiServer/Sum?a=10&b=20");
五、规则
5.1 Get规则
使用Get
进行请求时,服务方法可以声明多个参数,但 是每个参数都必须是简单类型(例如:int、string、DateTime等)。
[WebApi(HttpMethodType.GET)]
public int Get(int a)
{
return a;
}
[WebApi(HttpMethodType.GET)]
public int Sum(int a, int b)
{
return a + b;
}
5.2 Post规则
使用Post
进行请求时,服务方法可以声明多个参数,但是当参数是基础类型或者字符串类型时,它也会来源于Query
参数。
同时,有且只有当最后一个参数为其他类型时,才会从Body
解析。
例如:
以下参数依然来自Query
,Body
为空也可以。
[WebApi(HttpMethodType.Post)]
public int Sum(int a, int b)
{
return a + b;
}
当最后一个参数为其他类型时,它将会从Body
解析。
例如:
以下参数,前两个来自Query
,MyClass
将从Body
解析。
[WebApi(HttpMethodType.Post)]
public int Sum(int a, int b, MyClass myClass)
{
return a + b;
}
5.3 路由规则
框架的路由规则比较简单,默认情况下,以服务的名称+方法名称作为路由。
例如下列:
将会以/ApiServer/Sum
为请求url(不区分大小写)。
public class ApiServer : RpcServer
{
[WebApi(HttpMethodType.GET)]
public int Sum(int a, int b)
{
return a + b;
}
}
当需要定制路由消息时,可用[api]
替代服务名,[action]
替代方法名。
例如下列:
将会以user/ApiServer/test/Sum
为请求url(不区分大小写)。
[Router("/user/[api]/test/[action]")]
public class ApiServer : RpcServer
{
[WebApi(HttpMethodType.GET)]
public int Sum(int a, int b)
{
return a + b;
}
}
Router
特性不仅可以用于服务,也可以用于方法。而且可以多个使用。
六、调用上下文
框架中,每个请求都会产生一个调用上下文(ICallContext),这个上下文可以获取到当前请求 的客户端、服务、方法、参数等。
通用调用上下文可以参阅通用Rpc调用上下文。
下列将介绍WebApi
的专用调用上下文。
首先,在服务方法中,只要有参数类型为IWebApiCallContext
(或者ICallContext
),框架会自动注入当前调用上下文。
例如:
[WebApi(HttpMethodType.GET)]
public int SumCallContext(IWebApiCallContext callContext, int a, int b)
{
return a + b;
}
调用上下文的位置没有限制,但是建议在方法参数的最前面,这样即使对Post
,也不会有额外的判断压力。
6.1 获取当前客户端信息
一般来说,调用上下文的Caller
就是实际通信的客户端,也就是HttpSessionClient
。
if (callContext.Caller is IHttpSessionClient httpSessionClient)
{
Console.WriteLine($"IP:{httpSessionClient.IP}");
Console.WriteLine($"Port:{httpSessionClient.Port}");
Console.WriteLine($"Id:{httpSessionClient.Id}");
}
6.2 获取HttpContext
WebApi
的调用上下文,除了Caller
,还有HttpContext
。
//http内容
var httpContext = callContext.HttpContext;
//http请求
var request = httpContext.Request;
//http响应
var response = httpContext.Response;
当获取到HttpContext
后,就可以做HttpService
的所有功能。例如:读取请求头,修改响应头,修改响应内容,修改响应状态码、响应WebSocket连接等。具体可以参考创建HttpService和WebSocketService。
七、调用服务
7.1 直接调用
直接调用,则是不使用任何代理,直接Call Rpc,使用比较简单,浏览器也能直接调用实现。
【Url请求】
http://127.0.0.1:7789/ApiServer/Sum?a=10&b=20
7.2 框架HttpClient调用
框架内置的HttpClient
,可以参考HttpClient的使用,此处做一个简单使用示例。
var client = new HttpClient();
await client.ConnectAsync("127.0.0.1:7789");
string responseString = await client.GetStringAsync("/ApiServer/Sum?a=10&b=20");
7.3 内置WebApiClient调用
内置WebApi
的客户端和HttpClient
基本一致,但是封装了一些Rpc
的调用接口,可以更加方便的执行一些操作。
【创建WebApi客户端】
var client = new WebApiClient();
await client.SetupAsync(new TouchSocketConfig()
.SetRemoteIPHost("127.0.0.1:7789")
.ConfigurePlugins(a =>
{
a.Add<MyWebApiPlugin>();
}));
await client.ConnectAsync();
【GET调用】
在使用GET
进行调用时,其InvokeKey
的规则是:
- 使用
GET
开头。 :
之后追加url
路由。- 其余参数按照字符串填充规则,依次排序。
例如:
int sum1 = client.InvokeT<int>("GET:/ApiServer/Sum?a={0}&b={1}", null, 10, 20);
Console.WriteLine($"Get调用 成功,结果:{sum1}");
【POST调用】
在使用POST
进行调用时,其InvokeKey
的规则是:
- 使用
POST
开头。 :
之后追加url
路由。- 其余参数按照字符串填充规则,依次排序。
- 最后一个参数,如果为
Body
,则使用类
填充。
例如:
int sum2 = client.InvokeT<int>("POST:/ApiServer/TestPost", null, new MyClass() { A = 10, B = 20 });
Console.WriteLine($"Post调用成功,结果:{sum2}");
7.4 Dotnet自带HttpClient调用
Dotnet自带HttpClient则是通过连接池的方式访问。详情看HttpClient
【创建客户端】
var client = new WebApiClientSlim(new System.Net.Http.HttpClient());
await client.SetupAsync(new TouchSocketConfig()
.SetRemoteIPHost("http://127.0.0.1:7789"));
【调用】
int sum1 = client.InvokeT<int>("GET:/ApiServer/Sum?a={0}&b={1}", null, 10, 20);
Console.WriteLine($"Get调用成功,结果:{sum1}");
int sum2 = client.InvokeT<int>("POST:/ApiServer/TestPost", null, new MyClass() { A = 10, B = 20 });
Console.WriteLine($"Post调用成功,结果:{sum2}");
按照微软建议,HttpClient
应该保证整个程序中单实例使用,所以可以在WebApiClientSlim
构造函数中传入已存在的对象。
WebApiClientSlim
仅在net6.0+,net481可用。
7.5 生成代理调用
使用WebApi客户端进行调用时,其使用规则相较比较复杂的。但是在实际使用时,基本上是不需要手动书写调用代码的。下面将介绍代理生成调用。
在服务器端,注册完服务后,就可以生成客户端调用代码了。详细的操作可以查看服务端代理生成
a.UseWebApi()
.ConfigureRpcStore(store =>
{
store.RegisterServer<ApiServer>();//注册服务
#if DEBUG
//下列代码,会生成客户端的调用代码。
var codeString = store.GetProxyCodes("WebApiProxy", typeof(WebApiAttribute));
File.WriteAllText("../../../WebApiProxy.cs", codeString);
#endif
});