增加使用说明
大石头 authored at 2025-09-21 21:43:58
3.81 KiB
NewLife.Remoting
# 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` ʼþ¡£