快速开始 | Silky微服务框架在线文档

silky 框架简介

silky 是一个基于 .NET 平台构建的微服务开发框架，专注于 RPC 通信与微服务治理两大核心能力。它遵循 .NET 生态的主流编程模型，允许开发者以极少量的代码将普通的 .NET 主机应用转变为具有服务注册、服务发现、远程调用、分布式事务等能力的微服务应用。

silky 的核心优势

优势	说明
接口即服务	标注 `[ServiceRoute]` 特性的接口自动生成 HTTP WebAPI 及 RPC 服务端点，无需手写 Controller
本地透明调用	通过依赖注入直接使用接口，框架在运行时自动生成动态代理，屏蔽 RPC 细节，与本地调用体验一致
多种主机类型	支持 Web 主机（对外暴露 HTTP）、通用主机（仅 RPC）、WebSocket 主机、网关主机，满足不同场景需求
多注册中心	内置支持 Zookeeper、Nacos、Consul，切换注册中心仅需修改一行配置
内置服务治理	开箱即用的负载均衡、熔断、重试、限流、服务降级，基于 Polly 实现
TCC 分布式事务	框架级别的 TCC 事务支持，通过拦截器+Redis 日志保证跨服务数据一致性
高度集成 .NET 生态	完全兼容 ASP.NET Core 中间件体系、DI 容器、配置系统、日志框架（含 Serilog）

说明：silky 并非"全家桶"式框架，其核心理念是在 .NET 原生模型上以最小侵入的方式叠加微服务能力。开发者可按需引入各功能包，对现有 ASP.NET Core 知识复用率高。

必要前提

(必须) 安装 .NET 6 SDK 或更高版本（支持 .NET 6 / 7 / 8 / 9 / 10）。
(必须) 您可以使用 Visual Studio 2022+ 或 JetBrains Rider 作为开发工具。
(必须) 准备一个可用的服务注册中心（支持 Zookeeper、Nacos 或 Consul，三选一）。
(必须) 使用 Redis 服务作为分布式缓存服务。

使用项目模板快速初始化（推荐）

silky 提供了官方项目模板 silky.app，可以跳过手动配置步骤，一键生成标准项目结构：

# 安装模板
dotnet new install Silky.App.Template

# 创建网关
dotnet new silky.app -t gateway -n Silky.Gateway

# 创建通用主机微服务
dotnet new silky.app -t generalhost -n Silky.Demo

# 创建 Web 主机微服务
dotnet new silky.app -t webhost -n Silky.Demo

如需手动搭建，请继续阅读以下步骤。

使用Web主机构建微服务应用

开发者可以通过 .NET 平台提供的 Web 主机来构建 silky 微服务应用。

使用 Web 主机构建的 silky 微服务应用同时具备两种能力：

作为 RPC 服务提供者，与集群内其他微服务通过 SilkyRPC 通信；
提供 HTTP 服务，应用服务方法（服务条目）自动生成 WebAPI，可通过浏览器或网关直接访问。

我们通过如下步骤快速构建一个使用 Web 主机构建的 silky 微服务应用。

步骤一：创建项目并安装包

通过 Rider 或 Visual Studio 创建一个空的 ASP.NET Core Web 应用项目，然后安装 Silky.Agent.Host 包：

PM> Install-Package Silky.Agent.Host -Version 3.9.2

Silky.Agent.Host 是 silky 的聚合包，包含了构建微服务主机所需的所有依赖（RPC、服务治理、注册中心适配器、缓存、分布式事务等）。

步骤二：在 `Program.cs` 中构建 silky 主机

using Microsoft.AspNetCore.Hosting;
using Microsoft.Extensions.Hosting;

namespace Silky.Sample
{
    public class Program
    {
        public static Task Main(string[] args)
        {
            return CreateHostBuilder(args).Build().RunAsync();
        }

        private static IHostBuilder CreateHostBuilder(string[] args) =>
            Host.CreateDefaultBuilder(args)
                .ConfigureSilkyWebHostDefaults(webBuilder =>
                {
                    webBuilder.UseStartup<Startup>();
                });
    }
}

步骤三：在 `Startup.cs` 中配置服务和中间件

using Microsoft.AspNetCore.Builder;
using Microsoft.AspNetCore.Hosting;
using Microsoft.Extensions.Configuration;
using Microsoft.Extensions.DependencyInjection;
using Microsoft.Extensions.Hosting;
using Silky.Http.Core;

namespace Silky.Sample
{
    public class Startup
    {
        public Startup(IConfiguration configuration)
        {
            Configuration = configuration;
        }

        public IConfiguration Configuration { get; }

        public void ConfigureServices(IServiceCollection services)
        {
            services.AddSilkyHttpCore()  // 注册 Silky HTTP 核心服务
                .AddSwaggerDocuments()   // 注册 Swagger 文档
                .AddRouting();
        }

        public void Configure(IApplicationBuilder app, IWebHostEnvironment env)
        {
            if (env.IsDevelopment())
            {
                app.UseDeveloperExceptionPage();
                app.UseSwaggerDocuments();  // 开发环境开启 Swagger
            }

            app.UseRouting();

            app.UseEndpoints(endpoints => 
            { 
                endpoints.MapSilkyRpcServices();  // 映射 Silky 服务条目路由
            });
        }
    }
}

步骤四：更新配置文件

silky 推荐使用 yaml 格式进行配置（也支持 json、yml）。将 appsettings.json 替换或补充为 appsettings.yaml：

silky 支持 Zookeeper、Nacos 和 Consul 三种注册中心，通过 registryCenter.type 配置项进行切换。

使用 Zookeeper 作为注册中心（appsettings.yaml）：

registryCenter:
  type: Zookeeper
  connectionStrings: 127.0.0.1:2181,127.0.0.1:2182,127.0.0.1:2183

distributedCache:
  redis:
    isEnabled: true
    configuration: 127.0.0.1:6379,defaultDatabase=0,password=qwe!P4ss

rpc:
  token: ypjdYOzNd4FwENJiEARMLWwK0v7QUHPW
  port: 2200

使用 Nacos 作为注册中心：

registryCenter:
  type: Nacos
  connectionStrings: http://127.0.0.1:8848

distributedCache:
  redis:
    isEnabled: true
    configuration: 127.0.0.1:6379,defaultDatabase=0,password=qwe!P4ss

rpc:
  token: ypjdYOzNd4FwENJiEARMLWwK0v7QUHPW
  port: 2200

使用 Consul 作为注册中心：

registryCenter:
  type: Consul
  connectionStrings: http://127.0.0.1:8500

distributedCache:
  redis:
    isEnabled: true
    configuration: 127.0.0.1:6379,defaultDatabase=0,password=qwe!P4ss

rpc:
  token: ypjdYOzNd4FwENJiEARMLWwK0v7QUHPW
  port: 2200

提示：rpc.token 用于保护 RPC 通道，集群内所有服务必须使用相同的 token 值。

将配置文件属性的复制到输出目录设置为 始终复制 或 如果较新则复制。

步骤五：启动基础服务

silky 的示例项目提供了各种基础服务的 docker-compose 编排文件，包含 Zookeeper、Nacos、Consul 和 Redis。

# 创建 docker 网络
docker network create silky_service_net

# 启动 Zookeeper 和 Redis
docker-compose -f docker-compose.zookeeper.yml -f docker-compose.redis.yml up -d

步骤六：规划微服务模块结构

silky 推荐按照 DDD 分层架构组织微服务代码，一个标准模块包含以下层：

层	说明
应用接口层（`.Application.Contracts`）	定义服务接口（`IXxxAppService`）和 DTO，打包为独立 NuGet 包供其他微服务引用
应用层（`.Application`）	实现服务接口，协调领域逻辑
领域层（`.Domain`）	核心业务逻辑，可引用其他微服务的应用接口层实现透明 RPC 调用
基础设施层（`.EntityFrameworkCore` 等）	数据访问，可集成 EFCore、MassTransit 等 ORM
主机层（`Host`）	依赖应用层，负责应用托管

关键设计：将应用接口层单独抽象为独立程序集，其他微服务通过引用该程序集自动获得 RPC 代理能力。

步骤七：定义和实现应用服务接口

应用接口层 安装 Silky.Rpc 包：

PM> Install-Package Silky.Rpc -Version 3.9.2

新增服务接口 IGreetingAppService，使用 [ServiceRoute] 特性标识：

using System.Threading.Tasks;
using Silky.Rpc.Routing;

[ServiceRoute]
public interface IGreetingAppService
{
    Task<string> Say(string line);
}

应用层 依赖应用接口层，并实现接口：

public class GreetingAppService : IGreetingAppService
{
    public Task<string> Say(string line)
    {
        return Task.FromResult($"Hello {line}");
    }
}

步骤八：通过 Swagger 文档在线调试

运行应用程序后，打开 swagger 在线文档，即可直接调试 API。

服务间调用

silky 提供两种方式实现微服务间通信：

方式一：接口代理（推荐）

在其他微服务中引用目标服务的应用接口层包，通过构造注入接口即可实现透明 RPC 调用，与调用本地方法体验完全一致，支持分布式事务：

public class OrderAppService : IOrderAppService
{
    private readonly IGreetingAppService _greetingAppService;  // 注入另一个微服务的接口

    public OrderAppService(IGreetingAppService greetingAppService)
    {
        _greetingAppService = greetingAppService;
    }

    public async Task<string> CreateOrder(string name)
    {
        // 直接调用，框架自动通过 RPC 路由到目标微服务实例
        var greeting = await _greetingAppService.Say(name);
        return greeting;
    }
}

方式二：模板调用（解耦场景）

通过 IInvokeTemplate 接口以服务条目 ID 或 WebAPI 路径调用远程服务，无需引用目标服务的应用接口包，适合网关层或跨团队松耦合场景（注意：不支持分布式事务）。

IInvokeTemplate 支持两种寻址方式：

寻址方式	代表方法	说明
服务条目 ID	`InvokeForObjectByServiceEntryId<T>()`	标识稳定，不随路由规则变化
WebAPI 路径	`GetForObjectAsync<T>()`、`PostForObjectAsync<T>()` 等	直观，与 Swagger 文档路由一致

public class GatewayHandler
{
    private readonly IInvokeTemplate _invokeTemplate;

    public GatewayHandler(IInvokeTemplate invokeTemplate)
    {
        _invokeTemplate = invokeTemplate;
    }

    // 方式 A：通过服务条目 ID 调用 —— 格式：{命名空间}.{接口名}.{方法名}.{参数名}:{HTTP方法}
    public async Task<string> HandleByEntryIdAsync(string name)
    {
        return await _invokeTemplate.InvokeForObjectByServiceEntryId<string>(
            "Silky.Sample.Application.Contracts.IGreetingAppService.Say.line:Get",
            name);
    }

    // 方式 B：通过 WebAPI 路径调用 —— 路径与 Swagger 文档路由一致，直观易维护
    public async Task<string> HandleByApiAsync(string name)
    {
        return await _invokeTemplate.GetForObjectAsync<string>("api/greeting/say/{line}", name);
    }
}

服务条目 ID 格式：{命名空间}.{接口名}.{方法名}.{参数名}:{HTTP方法}，可在注册中心或 Swagger 文档中查看，例如 Silky.Sample.Application.Contracts.IGreetingAppService.Say.line:Get。
WebAPI 路径：路径模板与框架路由规则生成的地址一致，{参数名} 为路径占位符，对应目标方法的参数名称。

使用.NET通用主机构建微服务应用

开发者可以通过 .NET 平台提供的通用主机来构建 silky 微服务应用。

使用通用主机构建的微服务应用只能作为 RPC 服务提供者，无法提供 HTTP 服务，集群外部需通过网关或 Web 主机类型的微服务间接访问。这种模式适合纯后端业务服务，资源占用更少。

1-2 步骤与使用 Web 主机构建微服务应用一致。

在 Program.cs 中构建 silky 主机

using System.Threading.Tasks;
using Microsoft.Extensions.Hosting;

var hostBuilder = Host.CreateDefaultBuilder(args)
    .ConfigureSilkyGeneralHostDefaults();

await hostBuilder.Build().RunAsync();

如需注册额外服务，创建 ConfigureService 类实现 IConfigureService 接口：

public class ConfigureService : IConfigureService
{
    public void ConfigureServices(IServiceCollection services, IConfiguration configuration)
    {
        // 注册 SkyAPM 链路追踪（可选）
        services.AddSilkySkyApm();
        // 其他服务：EFCore、MassTransit 等
    }
}

4-7 步骤与使用 Web 主机构建微服务应用一致。

启动应用后，在控制台可看到相关日志，应用服务启动成功。

构建具有websocket服务能力的微服务应用

silky 支持构建具有 WebSocket 通信能力的微服务应用，除了作为 RPC 服务提供者外，还可以提供 WebSocket 服务（默认端口 3000），服务端可主动向客户端推送消息。

构建步骤与通用主机基本一致，只需替换主机构建方法：

using System.Threading.Tasks;
using Microsoft.Extensions.Hosting;

var hostBuilder = Host.CreateDefaultBuilder(args)
    .ConfigureSilkyWebSocketDefaults();

await hostBuilder.Build().RunAsync();

应用服务接口定义与普通服务一致，使用 [ServiceRoute] 标识：

using Silky.Rpc.Routing;

[ServiceRoute]
public interface ITestAppService
{
   // 可定义普通服务方法，通过 RPC 与其他微服务通信
}

在 应用层 安装 Silky.WebSocket 包：

PM> Install-Package Silky.WebSocket -Version 3.9.2

新增 TestAppService 类，继承 WsAppServiceBase 并实现 ITestAppService：

public class TestAppService : WsAppServiceBase, ITestAppService
{
    private readonly ILogger<TestAppService> _logger;

    public TestAppService(ILogger<TestAppService> logger)
    {
        _logger = logger;
    }

    // 建立 WebSocket 会话时触发
    protected override void OnOpen()
    {
        base.OnOpen();
        _logger.LogInformation("WebSocket session established");
    }

    // 收到客户端消息时触发
    protected override void OnMessage(MessageEventArgs e)
    {
        _logger.LogInformation("Received: {Message}", e.Data);
        // 可通过 Send() 向客户端推送消息
    }

    // 会话关闭时触发
    protected override void OnClose(CloseEventArgs e)
    {
        base.OnClose(e);
        _logger.LogInformation("WebSocket session closed");
    }
}

启动后，客户端通过网关以 ws[s]://gateway_host/api/test 与 WebSocket 服务握手和通信。握手时需通过 querystring 参数或请求头设置 hashkey，确保每次通信路由到同一微服务实例。

构建Silky微服务网关

网关是微服务集群对外的统一流量入口，它只作为服务消费者（不注册 RPC 服务），对外提供 HTTP 服务，对内通过 SilkyRPC 调用各微服务。

构建方式与 Web 主机一致，只需替换主机构建方法：

private static IHostBuilder CreateHostBuilder(string[] args) =>
    Host.CreateDefaultBuilder(args)
        .ConfigureSilkyGatewayDefaults(webBuilder => { webBuilder.UseStartup<Startup>(); });

网关通过引用其他微服务的应用接口层，即可获得以下能力：

自动生成聚合 Swagger 在线文档（汇聚所有微服务的 API）
统一身份认证与 JWT 鉴权
HTTP 限流
Dashboard 管理界面（服务实例监控）
微服务实例健康检查