增加使用说明
# ApiClient ʹÓÃ˵Ã÷
±¾ÎĽéÉÜ `ApiClient` µÄ¹¦ÄÜÓëÓ÷¨£¬º¸ÇÁ¬½Ó¡¢µ÷Óá¢ÈÏÖ¤¡¢ÖØÊÔ¡¢¿É¹Û²âÐÔÓëÔÚ ASP.NET Core Razor Pages Öеɽ¨Òé¡£
## 1. ¸ÅÊö
- ×÷ÓãºÃæÏòÓ¦ÓÃµÄ RPC ¿Í»§¶Ë£¬±£³Öµ½·þÎñ¶ËµÄ³¤Á¬½Ó£¬Ö§³ÖÇëÇó-ÏìÓ¦Óë·þÎñ¶Ëµ¥ÏòÍÆËÍ¡£
- ´«Ê䣺Tcp / Http / WebSocket£¨ÓÉ·þÎñ¶ËÓëµØÖ·¾ö¶¨£©¡£
- ¸ºÔØ£ºÖ§³ÖµØÖ·ÁбíÓëÁ¬½Ó³Ø£¨¸ßÍÌÍ£©»òµ¥Á¬½Ó£¨µÍʱÑÓ£©¡£
## 2. ¿ìËÙ¿ªÊ¼
```csharp
var client = new ApiClient("tcp://127.0.0.1:12345");
client.Log = XTrace.Log; // ¿ÉÑ¡
client.Open();
var hello = await client.InvokeAsync<string>("demo/hello", new { name = "world" });
Console.WriteLine(hello);
client.Close("done");
```
- Ö¸¶¨¶à¸öµØÖ·£¨¶ººÅ/·ÖºÅ·Ö¸ô£©ÒÔ×ö¼òµ¥µÄ¸ºÔØÓëÇл»£º`new ApiClient("tcp://a:1234,tcp://b:1234")`¡£
- Http ³¡¾°¿ÉÖ±½ÓʹÓà `ApiHttpClient`£º`new ApiHttpClient("http://host:port")`¡£
## 3. Á¬½ÓÓ뼯Ⱥ
- `Servers`£º·þÎñ¶ËµØÖ·¼¯ºÏ¡£
- `UsePool`£ºÊÇ·ñʹÓÃÁ¬½Ó³Ø£»true Ϊ¶àÁ¬½Ó£¨¸ßÍÌÍ£©£¬false Ϊµ¥Á¬½Ó£¨µÍʱÑÓ£©¡£
- `Local`£º¶à IP »·¾³Ï°󶨱¾µØµØÖ·¡£
- `Cluster`£ºÄÚ²¿Ê¹Óà `ClientSingleCluster` »ò `ClientPoolCluster` ¹ÜÀí `ISocketClient`¡£
## 4. Ô¶³Ìµ÷ÓÃ
- `InvokeAsync<TResult>(action, args, ct)`£ºÒì²½ÇëÇó-ÏìÓ¦¡£
- `Invoke<TResult>(action, args)`£ºÍ¬²½×èÈûµÈ´ý£¨ÄÚ²¿´´½¨³¬Ê±ÁîÅÆ£©¡£
- `InvokeOneWay(action, args, flag=0)`£ºµ¥Ïò·¢ËÍ£¬²»µÈ´ýÓ¦´ð¡£
- ·þÎñ¶ËÖ÷¶¯ÍÆËÍ£º¶©ÔÄ `Received` ʼþ½ÓÊÕÀ´×Ô·þÎñ¶ËµÄ֪ͨÏûÏ¢¡£
## 5. ÈÏÖ¤Óë Token
- `Token`£ºÈôÉèÖ㬵÷ÓÃʱ»á×Ô¶¯×¢Èëµ½²ÎÊý¼¯ºÏ£¨¼ü `Token`£©¡£
- ×Öµä²ÎÊý£ºÔµØ×¢È룻¶ÔÏó²ÎÊý£º³¢ÊÔдÈëÊôÐÔ `Token`£¬·ñÔòת»»³É×Öµäºó×¢Èë¡£
- Á¬½Ó½¨Á¢»ò¶ÏÏßÖØÁ¬ºó£¬¿Í»§¶Ë»á´¥·¢ `OnNewSession`£¬Ä¬ÈÏÒì²½µ÷Óà `OnLoginAsync(client, force=true)`£¬¿ÉÖØÐ´ÊµÏֵǼ¡£
- ÏÔʽµÇ¼£º`await client.LoginAsync()` »á¶Ô¼¯ÈºÖÐÁ¬½ÓÖ´ÐеǼ¡£
## 6. ´íÎóÓëÖØÊÔ
- 401£¨Unauthorized£©£º¿ò¼Ü×Ô¶¯µ÷Óà `OnLoginAsync(force=true)`£¬²¢ÔÚͬһÁ¬½ÓÉÏÖØ·¢Ò»´Î£¬²»¼ÆÈëÖØÊÔ´ÎÊý¡£
- ¿ÉÑ¡ÖØÊÔ£º
- `IRetryPolicy? RetryPolicy` + `int MaxRetries`£¨Ä¬ÈÏ 0£©ÓÃÓÚ¶Ô·Ç 401 Òì³£½øÐÐÓÐÏÞ´ÎÖØÊÔ¡£
- ²ßÂÔ¿É¿ØÖÆÊÇ·ñµÈ´ý¡¢µÈ´ýʱ³¤¡¢ÊÇ·ñÔÚÖØÊÔǰÇл»Á¬½Ó¡£
- ³¬Ê±£º`Timeout`£¨ºÁÃ룩¡£µ±´¥·¢³¬Ê±£¬»áÒÔ¼ò¶ÌÏûÏ¢Å׳ö `TaskCanceledException`¡£
## 7. ±à½âÂëÓëÐòÁл¯
- `Encoder`£ºÄ¬ÈÏ `JsonEncoder`¡£
- `JsonHost`£º×Ô¶¨Òå JSON ÐòÁл¯ÐÐΪ£¨Èç´óСд¡¢ÈÕÆÚ¸ñʽ¡¢ºöÂÔ¿ÕÖµµÈ£©¡£
- `EncoderLog`£º±àÂëÆ÷ÈÕÖ¾£¨¿É¶¨Ïòµ½ `XTrace.Log`£©¡£
## 8. ¿É¹Û²âÐÔÓëͳ¼Æ
- ÈÕÖ¾£º`ILog Log`¡¢`ILog SocketLog`¡£
- ×·×Ù£º`ITracer? Tracer`¡£`client.Tracer` µÄµ×²ã Socket Trace ÊÜÈÕÖ¾¼¶±ð¿ØÖÆ¡ª¡ª½öµ±ÈÕÖ¾¼¶±ðΪ Debug ʱ´ò¿ª£¬ÒÔ¼õÉÙ³£¹æÔËÐÐÆÚ¼äµÄÂñµãÁ¿Ó뿪Ïú¡£
- Âýµ÷Óãº`SlowTrace`£¨ºÁÃ룩£¬³¬¹ýãÐÖµÊä³öÂýµ÷ÓÃÈÕÖ¾¡£
- ͳ¼Æ£º`ICounter? StatInvoke`£¬ÉèÖà `StatPeriod`£¨Ã룩ºóÖÜÆÚÐÔÊä³öµ÷ÓÃͳ¼Æ¡£
## 9. WebSocket / Http Óë¹ÜÏß
- µ±µØÖ·Îª WebSocket ʱ£¬¿Í»§¶Ë¹ÜÏß»á×¢Èë `WebSocketClientCodec` ²¢Çå¿ÕĬÈÏ´¦ÀíÆ÷£¬¿ªÆô»ùÓÚÏûÏ¢°üµÄͨÐÅ¡£
- Http ¿Í»§¶Ë½¨ÒéʹÓà `ApiHttpClient`£¬ÆäÔÚ `Encoder` Óë Filter£¨Èç `TokenHttpFilter`£©·½Ãæ¸üÌù½ü Http ÓïÒå¡£
## 10. ×ÊÔ´ÊÍ·Å
- `Close(reason)`£º¹Ø±Õ¼¯ÈºÓëÁ¬½Ó£¬ÊͷŶ¨Ê±Æ÷¡£
- `Dispose()`£ºÎö¹¹Ê±×Ô¶¯¹Ø±Õ£¨GC£©»òÏÔʽÊÍ·Å£¨Dispose£©¡£
## 11. ÔÚ ASP.NET Core Razor Pages ÖеÉ
- ×¢²áΪµ¥Àý²¢ÔÚÆô¶¯Ê± Open£º
```csharp
builder.Services.AddSingleton(sp =>
{
var cli = new ApiClient("tcp://127.0.0.1:12345")
{
Log = XTrace.Log,
Token = "your-token",
UsePool = false,
};
cli.Open();
return cli;
});
```
- ÔÚ `PageModel` ÖÐʹÓãº
```csharp
public class IndexModel : PageModel
{
private readonly ApiClient _client;
public IndexModel(ApiClient client) => _client = client;
public async Task OnGet()
{
var info = await _client.InvokeAsync<IDictionary<string, object>>("api/info");
ViewData["ServerInfo"] = info;
}
}
```
- ×¢Ò⣺
- ±£³Öµ¥ÀýÓ볤Á¬½Ó£¬±ÜÃâÿ´ÎÇëÇóн¨Á¬½Ó¡£
- ½áºÏÓ¦ÓÃÈÕÖ¾¼¶±ð¿ØÖÆÊÇ·ñ¿ªÆôµ×²ã Trace¡£
## 12. ³£¼ûÎÊÌâ
- Q£ºÈçºÎÖ¸¶¨Ê¹Óñ¾»úÄ³Íø¿¨µØÖ·£¿A£ºÉèÖà `Local`¡£
- Q£ºÈçºÎƽ»¬Çл»·þÎñ¶ËµØÖ·£¿A£ºµ÷Óà `SetServer(newUris)`£¬ÄÚ²¿»áÔÚÏ´λñÈ¡Á¬½ÓʱÉúЧ¡£
- Q£ºÈçºÎ½ÓÊÕ·þÎñ¶ËÖ÷¶¯ÏûÏ¢£¿A£º¶©ÔÄ `Received` ʼþ¡£
|