Admin
  • 推广您的产品

新建App接口项目 ​

项目介绍与应用场景 ​

ZhonTai.Template.App 模板用于快速创建基于 .NET 的后端接口项目，支持多模块分布式架构和单体应用两种开发模式。通过该模板，你可以一键生成结构清晰、配置规范的服务端项目，并内置了身份认证、权限控制、数据过滤、远程调用（gRPC/HTTP）等基础能力。

通过模板创建的项目，其框架核心功能（权限、日志、数据过滤、远程调用等）均引用自平台统一维护的 NuGet 包，而非直接内嵌源码。当平台发布新功能或修复后，你只需在项目中更新对应的 NuGet 包版本，即可获得最新能力，无需重新生成项目或手动合并代码，真正做到“一次生成，持续升级”。

模板提供三种项目类型来匹配不同的职责边界：

类型角色定位何时使用
平台端 sys系统核心与权限管理中心需要统一管理用户、角色、权限、日志时，作为整个系统的基座优先创建
业务端 app专注具体业务处理的模块当业务复杂需拆分为多个独立服务（如订单、商品、CMS），且依赖平台端的权限与用户信息时
用户端 mem面向终端用户/会员的接口开发移动端、Web前端等C端应用时，需登录与数据隔离，但不涉及后台功能权限管理

核心应用场景举例

  • 分布式微服务：平台端提供统一的 gRPC 服务，业务端和用户端通过 gRPC 远程获取用户、权限、日志信息，各自连接独立数据库，实现团队并行开发与独立部署。
  • 单体敏捷开发：将权限库合并至业务库（--merge-db），在一个项目中完成全部功能，适合中小型项目快速交付。
  • 会员端快速搭建：用户端项目省去复杂的功能权限，只保留登录与数据权限，适合搭建轻量级用户中心或小程序接口。

下面将从安装模板开始，详细说明各类型项目的创建方法与最佳实践。

安装或升级模板 ​

cs
dotnet new install ZhonTai.Template.App

升级模板命令和安装模板命令相同

注意

如果已安装ZhonTai.Template模板，需要先卸载ZhonTai.Template旧模板再安装ZhonTai.Template.App新模板，避免模板短名称MyApp冲突

cs
dotnet new uninstall ZhonTai.Template

安装指定版本 ​

cs
dotnet new install ZhonTai.Template.App::10.1.0

查看帮助 ​

cs
dotnet new MyApp -h
[模板选项]
-at, --app-type <app|mem|sys>         
  根据项目需求选择不同的类别
  类型: choice
    sys  包含Admin权限管理接口，适用于系统拓展或单体项目开发，具备登录、数据权限和功能权限限制。
    app  不含Admin权限管理接口，需要Grpc和Http远程通讯，适用于业务模块项目开发，具备登录、数据权限和功能权限限制。
    mem  不含Admin权限管理接口，适用于用户端或会员端开发，不依赖Admin接口，需要Grpc和Http远程通讯，
         具备登录、数据权限限制，无功能权限限制。
  默认: app
-ac, --app-code <app-code>
  可选，不填默认使用app-type项目类别选项
  用于在项目中唯一标识不同的功能模块，以便于管理和区分模块项目，如 sys | biz | mem。
  类型: string
-p, --port <port>                      
  设置接口项目启动时所监听的端口号，如 18010 | 18020 | 18030。
  必需: true
  类型: int
-gp, --grpc-port <grpc-port>           
  配置GRPC远程通讯所使用的端口号，建议设置为Http端口号加1，如 18011 | 18021 | 18031。
  必需: true
  类型: int
-sk, --security-key <security-key>
  可选，不填默认使用Guid生成
  设置jwtconfig.securityKey的值，用于JWT令牌的安全验证，确保接口调用的安全性。
  启用条件: AppType == sys
  类型: string
-db, --db-type <MySql|PostgreSQL|...>  
  根据项目需求选择合适的数据库类型，支持国内外主流数据库。
  类型: choice
    MySql       MySql
    PostgreSQL  PostgreSQL
    SqlServer   SqlServer
    Oracle      Oracle
    Sqlite      Sqlite
    Firebird    Firebird
    MsAccess    MsAccess
    Dameng      达梦数据库，提供稳定可靠的数据存储和查询服务。
    ShenTong    神通数据库，具备高性能和可扩展性，满足复杂业务需求。
    KingbaseES  人大金仓数据库，提供全面的数据管理和安全保护。
    Gbase       南大通用数据库，支持大规模数据处理和分析。
    ClickHouse  ClickHouse
    QuestDb     QuestDb
    Xugu        虚谷数据库，提供灵活的数据存储和高效的查询性能。
  默认: Sqlite
-nau, --no-apiui                       
  选择此项将不使用新版接口文档功能，减少不必要的资源占用。
  类型: bool
  默认: false
-nts, --no-task-scheduler              
  选择此项将不集成任务调度服务，适用于无需定时任务处理的项目。
  类型: bool
  默认: false
-nc, --no-cap                          
  选择此项将不使用CAP分布式事务和事件总线功能，降低系统复杂性。
  类型: bool
  默认: false
-nt, --no-tests                        
  选择此项将不会生成测试库，适用于无需进行自动化测试的项目。
  类型: bool
  默认: false
-ns, --no-sample                       
  选择此项将不会生成默认的示例模块及其相关文件，适用于已熟悉开发流程并希望快速进入开发阶段的开发者。
  类型: bool
  默认: false
-md, --merge-db                        
  选择此项将会将admindb数据库合并到appdb中，实现数据库资源的统一管理和维护，适用于单体项目开发。
  类型: bool
  默认: false

查看已安装模板 ​

cs
dotnet new list

卸载模板 ​

cs
dotnet new uninstall ZhonTai.Template.App

新建平台端项目 ​

为什么需要平台端？
平台端是整个系统的“大脑”，负责统一管理用户、角色、菜单、权限、操作日志等后台基础功能。它对外提供 gRPC 服务，供业务端和用户端远程验证权限、获取用户信息。任何需要后台权限管理的系统都应该先创建平台端项目。

何时使用？

  • 启动一个全新的系统时，优先创建平台端，作为权限基座。
  • 开发多模块分布式应用，平台端独立部署，其他模块通过 gRPC 依赖它。
  • 需为运营人员提供功能完整的后台管理界面（Admin）时。

项目接口包含平台接口和 Admin 权限管理接口，dbconfig需配置sysdb（业务主库）、admindb（权限数据库）、logdb（日志库），提供数据权限、用户权限及操作日志 Grpc 服务接口。

  • 设置项目编码和端口号
cs
dotnet new MyApp -n MyCompanyName.Module.MySys -at sys -ac sys -p 18010 -gp 18011
cs
dotnet new MyApp -n MyCompanyName.Module.MySys -at sys -p 16010 -gp 16011
  • 切换数据库为MySql
cs
dotnet new MyApp -n MyCompanyName.Module.MySys -at sys -ac sys -p 18010 -gp 18011 -db MySql
cs
dotnet new MyApp -n MyCompanyName.Module.MySys -at sys -ac sys -p 16010 -gp 16011 -db MySql
  • 将权限数据库admindb合并到业务库appdb中，同时切换数据库为MySql
cs
dotnet new MyApp -n MyCompanyName.Module.MySys -at sys -ac sys -p 18010 -gp 18011 -md true -db MySql
cs
dotnet new MyApp -n MyCompanyName.Module.MySys -at sys -ac sys -p 16010 -gp 16011 -md true -db MySql
  • 🔥多模块开发时，已熟悉怎么开发不想要模块示例，不想增加测试库，可以这样配置
cs
dotnet new MyApp -n MyCompanyName.Module.MySys -at sys -ac sys -p 18010 -gp 18011 -nt true -ns true -db MySql
cs
dotnet new MyApp -n MyCompanyName.Module.MySys -at sys -ac sys -p 16010 -gp 16011 -nt true -ns true -db MySql

温馨提示

平台端项目端口号默认范围：18010 - 18999，单体项目端口号默认范围：16010 - 16999

gp端口号默认范围：port + 1

新建业务端项目 ​

为什么需要业务端？
当系统功能逐渐复杂时，所有代码堆在平台端会变得难以维护。业务端项目让你可以把具体业务模块（如订单、商品、报表）剥离成独立服务，它不包含 Admin 管理界面，但通过 gRPC 复用平台端的登录、权限与用户数据，保持数据隔离的同时又能安全协作。

何时使用？

  • 平台端已就绪，需要扩展新的业务功能模块（例如从平台端拆分出“电商业务服务”）。
  • 团队并行开发：多个业务端服务可同时开发，互不干扰。
  • 需要独立部署、按业务伸缩（如订单服务负载高可单独扩容）。

下面将开始新建业务端项目

  • 设置项目编码和端口号
cs
dotnet new MyApp -n MyCompanyName.Module.MyBiz -at app -ac biz -p 19010 -gp 19011
  • 切换数据库为MySql
cs
dotnet new MyApp -n MyCompanyName.Module.MyBiz -at app -ac biz -p 19010 -gp 19011 -db MySql
  • 🔥多模块开发时，已熟悉怎么开发不想要模块示例，不想增加测试库，可以这样配置
cs
dotnet new MyApp -n MyCompanyName.Module.MyBiz -at app -ac biz -p 19010 -gp 19011 -nt true -ns true -db MySql

温馨提示

业务端项目端口号默认范围：19010 - 19999

gp端口号默认范围：port + 1

新建用户端项目 ​

为什么需要用户端？
移动 App、微信小程序、官网等 C 端应用只需要用户注册登录和个人数据管理，不需要复杂的后台角色与菜单权限控制。用户端项目去掉了功能权限限制，聚焦于“用户身份认证 + 数据权限（用户只能操作自己的数据）”，提供轻量、安全的对外 API。

何时使用？

  • 构建面向终端消费者的会员中心、小程序接口、移动端 API。
  • 需要独立的用户端服务，与后台管理系统物理隔离，保障安全。
  • 配合平台端与业务端，为用户提供登录、信息修改、订单查询等前端接口。

下面将开始新建用户端项目

  • 设置项目编码和端口号
cs
dotnet new MyApp -n MyCompanyName.Module.MyMem -at mem -ac mem -p 20010 -gp 20011
  • 切换数据库为MySql
cs
dotnet new MyApp -n MyCompanyName.Module.MyMem -at mem -ac mem -p 20010 -gp 20011 -db MySql
  • 🔥多模块开发时，已熟悉怎么开发不想要模块示例，不想增加测试库，可以这样配置
cs
dotnet new MyApp -n MyCompanyName.Module.MyMem -at mem -ac mem -p 20010 -gp 20011 -nt true -ns true -db MySql

温馨提示

会员端项目端口号默认范围：20010 - 20999

gp端口号默认范围：port + 1

温馨提示

使用源码项目记得更改ZhonTai.Admin.Host/ConfigCenter/jwtconfig.json 配置文件的 securityKey 密钥

{
  "JwtConfig": {
    //密钥，注意字符串长度不能低于 32 位
    "securityKey": "33ce0d4b3a7b11ef8563526747b33ad4",
  }
}