脚手架 | Silky微服务框架在线文档

模板简介

Silky 框架提供官方项目模板 Silky.App.Template，通过 dotnet new silky.app 命令生成完整的分层业务应用脚手架，包含应用层、领域层、基础设施层与主机层，无需手动搭建项目结构。

安装模板

dotnet new install Silky.App.Template

安装后通过 dotnet new silky.app -h 查看全部参数：

PS> dotnet new silky.app -h
Silky App (C#)
作者: Liuhll

模板选项:
  -t, --param:type <param:type>  主机类型（见下表）                   默认: generalhost
  -r, --rpcport <rpcport>        RPC 监听端口                         默认: 2200
  -do, --dockersupport           生成 Docker/docker-compose 文件      默认: true
  -e, --env <env>                DOTNET_ENVIRONMENT 默认值             默认: Development
  -in, --infrastr                仅生成中间件编排文件（不含业务代码）  默认: false
  -p:i, --includeinfr            业务代码与中间件编排文件一并生成     默认: false

主机类型

`-t` 值	说明	适用场景
`generalhost`	纯 RPC 后端服务（无 HTTP 暴露）	内部服务、订单、库存等
`webhost`	RPC + HTTP 双协议服务	需直接提供 REST API 的服务
`wshost`	RPC + WebSocket 服务	实时推送、消息通知服务
`gateway`	API 网关（无分层业务代码）	入口网关，聚合 Swagger、JWT 鉴权、HealthCheck Dashboard

常用命令示例

# 创建通用主机微服务（纯 RPC，后端服务推荐）
dotnet new silky.app -t generalhost -n Silky.OrderService

# 创建 Web 主机微服务（HTTP + RPC）
dotnet new silky.app -t webhost -n Silky.ProductService

# 创建 WebSocket 微服务
dotnet new silky.app -t wshost -n Silky.NotifyService

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

# 创建时自定义 RPC 端口
dotnet new silky.app -t generalhost -r 2300 -n Silky.InventoryService

# 创建时不包含 Docker 文件
dotnet new silky.app -t generalhost -do false -n Silky.ReportService

# 仅生成中间件基础设施编排文件（Zookeeper、Redis、MySQL 等 docker-compose）
dotnet new silky.app --infrastr -n infra

# 生成业务代码同时附带基础设施编排文件
dotnet new silky.app -t generalhost --includeinfr -n Silky.OrderService

# 使用 Apollo 配置中心代替本地 yaml 配置
dotnet new silky.app -t generalhost -e Apollo -n Silky.OrderService

生成的项目结构

以 dotnet new silky.app -t generalhost -n Silky.OrderService 为例：

Silky.OrderService/
├── src/
│   ├── Silky.OrderService.Application/                    # 应用层：实现应用服务接口，编排领域逻辑
│   ├── Silky.OrderService.Application.Contracts/          # 应用接口层：定义 RPC 服务接口（IXxxAppService）与 DTO
│   ├── Silky.OrderService.Database.Migrations/            # 数据库迁移项目（EF Core 迁移脚本独立隔离）
│   ├── Silky.OrderService.Domain/                         # 领域层：聚合根、实体、领域服务、仓储接口
│   ├── Silky.OrderService.Domain.Shared/                  # 领域共享层：枚举、常量、Value Object
│   ├── Silky.OrderService.EntityFrameworkCore/            # 基础设施层：EF Core DbContext、仓储实现
│   └── Silky.OrderServiceHost/                            # 主机层：程序入口、依赖注入配置
│       ├── appsettings.yaml                               # 基础配置（Serilog、SkyWalking APM）
│       ├── appsettings.Development.yaml                   # 开发环境配置（注册中心、Redis、数据库）
│       ├── appsettings.Production.yaml                    # 生产环境配置（使用 CHANGE_ME_* 占位符）
│       ├── ConfigureService.cs                            # 模块与数据库注册（IConfigureService）
│       ├── Program.cs                                     # 主机启动入口
│       ├── Dockerfile                                     # 多阶段构建镜像
│       ├── Dockerfile.publish                             # 发布专用镜像
│       └── Properties/launchSettings.json                 # 本地调试启动配置
├── infrastr/                                              # (--includeinfr 时生成) 基础设施 docker-compose
│   ├── .env
│   ├── docker-compose.zookeeper.yml
│   ├── docker-compose.redis.yml
│   ├── docker-compose.mysql.yml
│   ├── docker-compose.skywalking.yml
│   └── docker-compose.apollo.yml
├── .env
├── .dockerignore
├── .gitignore
├── common.props
├── Silky.OrderService.sln
├── Silky.OrderService.DockerCompose.sln
├── docker-compose.yml                                     # 服务镜像构建与运行编排
├── docker-compose.dcproj
└── docker-compose.publish.yml

gateway 类型的差异

-t gateway 不包含业务分层项目，只生成网关主机，且 docker-compose.yml 自动包含 HTTP 端口暴露：

Silky.Gateway/
├── src/
│   └── Silky.GatewayHost/
│       ├── appsettings.yaml
│       ├── appsettings.Development.yaml   # 无 connectionStrings / plugInSource
│       ├── ConfigureService.cs
│       ├── Program.cs
│       ├── Startup.cs                     # 注册 Swagger 聚合、JWT、Dashboard、HealthChecks
│       ├── Dockerfile
│       ├── Dockerfile.publish
│       └── Properties/launchSettings.json
├── .env
├── .dockerignore
├── .gitignore
├── common.props
├── Gateway.sln
├── Gateway.DockerCompose.sln
├── docker-compose.yml                     # 含 ports: "${HTTP_PORT:-80}:80"
├── docker-compose.dcproj
└── docker-compose.publish.yml

--infrastr 模式

仅生成中间件基础设施编排文件，不包含任何业务代码，适合统一管理开发环境依赖：

dotnet new silky.app --infrastr -n infra

生成：

infra/
├── .dockerignore
├── .env
├── .gitignore
├── common.props
├── delete-bin-obj-folders.bat
├── delete-bin-obj-folders.js
├── docker-compose.publish.yml
└── infrastr/
    ├── .env
    ├── docker-compose.zookeeper.yml   # 6 节点 Zookeeper 集群
    ├── docker-compose.redis.yml       # Redis 主从
    ├── docker-compose.mysql.yml       # MySQL 8
    ├── docker-compose.skywalking.yml  # SkyWalking APM
    ├── docker-compose.apollo.yml      # Apollo 配置中心（可选）
    └── sql/                           # Apollo 初始化 SQL

分层职责说明

层	项目后缀	主要职责
应用接口层	`.Application.Contracts`	定义 `IXxxAppService` 接口、入参/出参 DTO，供跨服务 RPC 调用引用
应用层	`.Application`	实现接口，编排领域服务，处理事务
领域共享层	`.Domain.Shared`	枚举、常量、Value Object 等多服务共享类型
领域层	`.Domain`	聚合根、实体、领域服务、仓储接口
基础设施层	`.EntityFrameworkCore`	EF Core DbContext、仓储实现、MySQL Provider
迁移层	`.Database.Migrations`	EF Core 迁移脚本，单独项目隔离迁移依赖
主机层	`Host`	程序入口、Host 配置、DI 注册、Dockerfile

配置说明

凭据占位符

模板生成的配置文件中，以 CHANGE_ME_ 开头的值为必须替换的占位符：

占位符	含义
`CHANGE_ME_RPC_TOKEN`	所有 Silky 节点间通信共享 Token，集群内所有服务必须保持一致
`CHANGE_ME_ZK_PASSWORD`	Zookeeper Digest 认证密码
`CHANGE_ME_REDIS_PASSWORD`	Redis 连接密码（appsettings 与 infrastr/docker-compose.redis.yml 需保持一致）
`CHANGE_ME_DB_PASSWORD`	MySQL 连接密码（appsettings 与 infrastr/docker-compose.mysql.yml 需保持一致）

各主机类型配置差异

配置项	generalhost	webhost	wshost	gateway
`rpc` + `registrycenter`	✅	✅	✅	✅
`distributedCache` (Redis)	✅	✅	✅	✅
`connectionStrings`	✅	✅	✅	❌
`plugInSource` (EfCoreModule)	✅	✅	✅	❌
`docker-compose.yml` ports	❌	❌	❌	✅ (`:80`)

Apollo 配置中心

使用 -e Apollo 参数时，生成 appsettings.Apollo.yaml 替代 appsettings.Development.yaml 和 appsettings.Production.yaml：

apollo:
  appId: "silkyapp"
  cluster: default
  metaServer: "http://127.0.0.1:8080/"
  #  secret: "<your-apollo-secret>"
  namespaces:
    - application
    - TEST1.silkyapp
  env: DEV
  meta:
    DEV: "http://127.0.0.1:8080/"
    PRO: "http://127.0.0.1:8080/"

升级模板

dotnet new update Silky.App.Template