项目介绍与应用场景

ZhonTai.Template.App 模板用于快速创建基于 .NET 的后端接口项目，支持 多模块分布式架构 和 单体应用 两种开发模式。

通过该模板，你可以一键生成结构清晰、配置规范的服务端项目。模板内置了以下基础能力：

身份认证
权限控制
数据过滤
远程调用（gRPC / HTTP）
操作日志
多数据库配置

通过模板创建的项目，其框架核心功能（权限、日志、数据过滤、远程调用等）均引用自平台统一维护的 NuGet 包，而不是直接内嵌源码。

当平台发布新功能或修复问题后，你只需在项目中更新对应的 NuGet 包版本，即可获得最新能力，无需重新生成项目或手动合并代码，真正做到：

一次生成，持续升级。

项目类型说明

模板提供三种项目类型，用于匹配不同的职责边界。

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

核心应用场景

分布式微服务

平台端提供统一的 gRPC 服务，业务端和用户端通过 gRPC 远程获取用户、权限、日志等信息。

各服务可连接独立数据库，实现：

团队并行开发
服务独立部署
按业务模块独立扩容
权限能力统一复用

单体敏捷开发

可通过 --merge-db 将权限库合并至业务库，在一个项目中完成全部功能。

适用于：

中小型项目
快速交付场景
不需要复杂微服务拆分的系统

会员端快速搭建

用户端项目省去了复杂的功能权限，只保留登录认证与数据权限能力。

适用于快速搭建：

轻量级用户中心
小程序接口
移动端 API
C 端会员服务

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

安装或升级模板

安装模板

1	dotnet new install ZhonTai.Template.App

升级模板命令与安装模板命令相同。

注意事项

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

1	dotnet new uninstall ZhonTai.Template

安装指定版本

1	dotnet new install ZhonTai.Template.App::10.0.5

查看帮助

1	dotnet new MyApp -h

查看已安装模板

1	dotnet new list

卸载模板

1	dotnet new uninstall ZhonTai.Template.App

新建平台端项目

为什么需要平台端？

平台端是整个系统的“大脑”，负责统一管理后台基础功能，包括：

用户
角色
菜单
权限
操作日志

平台端对外提供 gRPC 服务，供业务端和用户端远程验证权限、获取用户信息。

任何需要后台权限管理的系统，都应优先创建平台端项目。

何时使用平台端？

适用于以下场景：

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

项目说明

平台端项目接口包含：

平台接口
Admin 权限管理接口

dbconfig 需要配置以下数据库：

数据库	说明
`sysdb`	业务主库
`admindb`	权限数据库
`logdb`	日志库

平台端提供以下 gRPC 服务接口：

数据权限
用户权限
操作日志

设置项目编码和端口号

平台端项目

1	dotnet new MyApp -n MyCompanyName.Module.MySys -at sys -ac sys -p 18010 -gp 18011

单体项目

1	dotnet new MyApp -n MyCompanyName.Module.MySys -at sys -ac sys -p 18010 -gp 18011

切换数据库为 MySQL

平台端项目

1	dotnet new MyApp -n MyCompanyName.Module.MySys -at sys -ac sys -p 18010 -gp 18011 -db MySql

单体项目

1	dotnet new MyApp -n MyCompanyName.Module.MySys -at sys -ac sys -p 18010 -gp 18011 -db MySql

合并权限数据库并切换为 MySQL

将权限数据库 admindb 合并到业务库 appdb 中，同时将数据库切换为 MySQL：

平台端项目

1	dotnet new MyApp -n MyCompanyName.Module.MySys -at sys -ac sys -p 18010 -gp 18011 -md true -db MySql

单体项目

1	dotnet new MyApp -n MyCompanyName.Module.MySys -at sys -ac sys -p 18010 -gp 18011 -md true -db MySql

多模块开发推荐配置

如果你已经熟悉项目结构，不需要生成模块示例，也不想增加测试库，可以使用以下配置：

平台端项目

1	dotnet new MyApp -n MyCompanyName.Module.MySys -at sys -ac sys -p 18010 -gp 18011 -nt true -ns true -db MySql

单体项目

1	dotnet new MyApp -n MyCompanyName.Module.MySys -at sys -ac sys -p 18010 -gp 18011 -nt true -ns true -db MySql

温馨提示

平台端项目端口号默认范围：18010 - 18999
单体项目端口号默认范围：16010 - 16999
gp 端口号默认范围：port + 1

新建业务端项目

为什么需要业务端？

当系统功能逐渐复杂时，如果所有代码都堆在平台端，项目会变得难以维护。

业务端项目可以将具体业务模块剥离为独立服务，例如：

订单服务
商品服务
报表服务
CMS 服务

业务端不包含 Admin 管理界面，但可以通过 gRPC 复用平台端的登录、权限与用户数据，在保持数据隔离的同时实现安全协作。

何时使用业务端？

适用于以下场景：

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

设置项目编码和端口号

1	dotnet new MyApp -n MyCompanyName.Module.MyBiz -at app -ac biz -p 19010 -gp 19011

切换数据库为 MySQL

1	dotnet new MyApp -n MyCompanyName.Module.MyBiz -at app -ac biz -p 19010 -gp 19011 -db MySql

多模块开发推荐配置

如果你已经熟悉项目结构，不需要生成模块示例，也不想增加测试库，可以使用以下配置：

1	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。
需要独立的用户端服务，并与后台管理系统物理隔离，以提升安全性。
配合平台端与业务端，为用户提供登录、信息修改、订单查询等前端接口。

设置项目编码和端口号

1	dotnet new MyApp -n MyCompanyName.Module.MyMem -at mem -ac mem -p 20010 -gp 20011

切换数据库为 MySQL

1	dotnet new MyApp -n MyCompanyName.Module.MyMem -at mem -ac mem -p 20010 -gp 20011 -db MySql

多模块开发推荐配置

如果你已经熟悉项目结构，不需要生成模块示例，也不想增加测试库，可以使用以下配置：

1	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

源码项目配置提示

使用源码项目时，请记得修改以下配置文件中的 securityKey 密钥：

1	ZhonTai.Admin.Host/ConfigCenter/jwtconfig.json

示例配置如下：

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

注意：securityKey 必须妥善保管，生产环境建议使用安全、随机且长度足够的密钥。

#中台 #中台/搭建项目框架 #中台/新建接口项目 #中台/.NET模板 #中台/分布式微服务