{"id":18300784,"url":"https://github.com/stratosblue/keenconveyance","last_synced_at":"2025-04-09T09:31:54.476Z","repository":{"id":206501635,"uuid":"717091532","full_name":"stratosblue/KeenConveyance","owner":"stratosblue","description":"A `Asp.Net Core Controller` service call framework based on `interface`. 基于 `interface` 的 `Asp.Net Core Controller` 服务调用框架。","archived":false,"fork":false,"pushed_at":"2024-12-04T15:00:10.000Z","size":192,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-02-15T03:41:47.238Z","etag":null,"topics":["aspnet-core","aspnetcore","client","http","rpc","rpc-framework"],"latest_commit_sha":null,"homepage":"","language":"C#","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/stratosblue.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE.txt","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2023-11-10T14:39:09.000Z","updated_at":"2024-12-04T15:01:20.000Z","dependencies_parsed_at":"2023-11-13T04:25:17.880Z","dependency_job_id":"2bf98db1-c2c0-4c35-80bd-0fb12a47af25","html_url":"https://github.com/stratosblue/KeenConveyance","commit_stats":null,"previous_names":["stratosblue/keenconveyance"],"tags_count":10,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/stratosblue%2FKeenConveyance","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/stratosblue%2FKeenConveyance/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/stratosblue%2FKeenConveyance/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/stratosblue%2FKeenConveyance/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/stratosblue","download_url":"https://codeload.github.com/stratosblue/KeenConveyance/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248012420,"owners_count":21033193,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["aspnet-core","aspnetcore","client","http","rpc","rpc-framework"],"created_at":"2024-11-05T15:13:22.246Z","updated_at":"2025-04-09T09:31:54.455Z","avatar_url":"https://github.com/stratosblue.png","language":"C#","funding_links":[],"categories":[],"sub_categories":[],"readme":"# KeenConveyance\n\n## 1. Intro\n\nA `Asp.Net Core Controller` service call RPC framework based on `interface`. 基于 `interface` 的 `Asp.Net Core Controller` 服务调用RPC框架。\n\n - 服务端基于 `Asp.Net Core`\t的 `Controller`. 支持所有标准的 `Controller` 功能, 如 `Filter`、`Authentication`、`Authorization`等(*);\n - 客户端基于 `Microsoft.Extensions.Http` 和 `SourceGenerator`. 无运行时动态代码生成, 支持 `Microsoft.Extensions.Http` 丰富的拓展 (`Polly`、`链路追踪`等);\n - 数据交换格式易拓展, 不局限于 `Json`, 可拓展为任意编码如: `MemoryPack`、`MessagePack` 等;\n - 动态 `Controller` 选择. 支持选择指定类型注册为 `Controller` 并暴露 `HttpAPI`;\n - 基于约定的客户端代码生成. 不依赖类库共享;\n - 目标框架 `net6.0`+;\n\n### NOTE!!!\n - 虽然支持所有标准的 `Controller` 功能且执行其流程, 但框架并非按照 `Controller` 定义进行请求, 框架的请求中会忽略 `[FromQuery]`、`[FromRoute]` 等定义直接使用 `ModelBinder` 从 `Body` 进行绑定;\n\t- 即: 如果请求由框架发起, 则依赖原始 `HttpContext`\t信息的功能可能不能正常工作, 例如请求的 `Query`、`Path` 中不包含 `Action` 的信息;\n - 方法参数建议使用简单类型或 `DTO`: 除 `CancellationToken` 外, 客户端会将方法参数都序列化后传递给服务端，服务端从 `Body` 进行绑定, 对一些特殊的参数不支持如 `IFormFile` 等;\n - 框架对接口定义的 `命名空间`、`方法名称`、`参数类型`、`参数顺序` 强依赖, 需要保证客户端与服务端接口定义一致;\n \n## 2. 快速开始\n\n### 2.1 服务端\n - 新建 `Asp.Net Core Web API` 项目, 并引用包:\n```xml\n\u003cItemGroup\u003e\n  \u003cPackageReference Include=\"KeenConveyance.AspNetCore\" Version=\"1.0.0-*\" /\u003e\n\u003c/ItemGroup\u003e\n```\n\n - 新建 `IApplicationService` 接口用于标记服务, 以便后续筛选 (非强制要求)\n```C#\npublic interface IApplicationService\n{ }\n```\n\n - 配置 `KeenConveyance` 服务\n```C#\nservices.AddKeenConveyance()\n        .ConfigureService(options =\u003e\n        {\n            //筛选所有派生自 IApplicationService 的类型作为 Controller\n            options.ControllerSelectPredicate = typeInfo =\u003e typeInfo.IsAssignableTo(typeof(IApplicationService));\n        });\n```\n\n - 在请求管道中启用 `KeenConveyance`\n```C#\n// 在 MapControllers 之前 UseAuthorization 之后\napp.UseKeenConveyance();\n```\n\n - 定义服务接口并实现服务 (或使现有 `Controller` 派生自服务接口), 如:\n```C#\npublic interface ISampleService : IApplicationService\n{\n    public Task\u003cstring\u003e EchoAsync(string value, CancellationToken cancellationToken);\n}\n\n[Route(\"[controller]\")]\npublic class SampleService : ISampleService\n{\n    [HttpGet]\n    public Task\u003cstring\u003e EchoAsync(string value, CancellationToken cancellationToken)\n    {\n        var echo = new string(value.AsEnumerable().Reverse().ToArray());\n        return Task.FromResult(echo);\n    }\n}\n```\n\n-------\n\n### 2.2 客户端\n - 新建任意类型项目 (需要 `DI` 支持, 可能需要手动引入), 并引用包:\n```xml\n\u003cItemGroup\u003e\n  \u003cPackageReference Include=\"KeenConveyance\" Version=\"1.0.0-*\" /\u003e\n\u003c/ItemGroup\u003e\n```\n Note: 项目直接引用而不要间接引用!\n\n - 配置 `KeenConveyance` 服务\n```C#\nservices.AddKeenConveyance(options =\u003e\n        {\n            //var xxxSerializer = 自定义的序列化器;\n            //options.DefaultObjectSerializer = xxxSerializer; //设置默认序列化器\n            //options.ObjectSerializers.Add(xxxSerializer); //添加到可用序列化器\n        })\n        .ConfigureClient(builder =\u003e\n        {\n            //客户端全局配置\n            builder.GlobalOptions(options =\u003e\n            {\n                //options.ObjectSerializer = xxx;   //配置客户端全局使用的序列化器\n                //options.HttpRequestMessageConstructor = xxx;  //配置客户端全局使用的HttpRequestMessage构造器\n                //options.ServiceAddressProvider = xxx; //配置客户端全局使用的服务地址提供器\n                //options.PrePreparePayloadData = true; //配置客户端请求时预准备请求数据，以确保Http请求包含有效的 Content-Length 头\n                //options.BufferInitialCapacity = 1024; //配置客户端预准备请求数据时的Buffer初始化大小\n            });\n\n            //配置客户端\n            //必须在此调用 BeginSetupClients 方法，并链式调用 AddClient 使用服务接口定义添加客户端, 并在最终调用 CompleteClientsSetup 方法\n            builder.BeginSetupClients()\n                   .AddClient\u003cISampleService\u003e(httpClientBuilder =\u003e\n                   {\n                       //配置服务地址\n                       httpClientBuilder.ConfigureServiceAddress(\"http://127.0.0.1:5225\");  //必须配置客户端的服务地址\n\n                       // 在此进行 ISampleService 的 HttpClient 配置\n\n                       httpClientBuilder.ConfigureOptions(options =\u003e\n                       {\n                           //配置应用于当前客户端的配置\n                       });\n                   })\n                   .CompleteClientsSetup();  //必须在最后调用 CompleteClientsSetup 方法，提示未找到此方法可尝试手动using当前项目的根命名空间\n        });\n```\n\n-------\n\n至此已完成所有配置，从 `DI` 容器中直接获取 `ISampleService` 实例并调用方法即可\n\n-------\n\n### 3. 自定义数据交换格式\n\n框架默认使用 `System.Text.Json` 进行数据交换，通过实现自定义的 `IObjectSerializer` 来自定义数据交换格式;\n\n- 可参考测试代码对 `MemoryPack` 的支持;\n\n-------\n\n## 其他\n\n - 客户端代码生成在当前项目的根命名空间下，提示未找到 `CompleteClientsSetup` 方法可以手动 `using` 当前项目的根命名空间进行尝试;\n - 生成的客户端代码都已标记为 `partial` 类型, 可声明对应的 `partial` 类，并重写方法来进行自定义操作, 服务的代理类型为格式为 `{ServiceName}ProxyClient` (如 `ISampleService` 的代理类型为 `ISampleServiceProxyClient`) :\n   ```C#\n    internal static partial class GeneratedClient\n    {\n        private partial class ISampleServiceProxyClient\n        {\n            public override Task\u003cstring\u003e EchoAsync(string value, CancellationToken cancellationToken)\n            {\n                //进行请求前后的自定义操作\n                return base.EchoAsync(value, cancellationToken);\n            }\n        }\n    }\n   ```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fstratosblue%2Fkeenconveyance","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fstratosblue%2Fkeenconveyance","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fstratosblue%2Fkeenconveyance/lists"}