系统架构

Fastdotnet 采用现代化的分层架构和模块化设计，支持多端应用和插件化扩展。

🏗️ 整体架构

┌─────────────────────────────────────────────────────┐
│                   客户端层 (Clients)                  │
├──────────────┬──────────────┬──────────┬────────────┤
│  Web 管理端   │  Web 应用端  │ 桌面端    │ 移动端      │
│  (Admin)     │  (App)       │(待开发)  │ (待开发)    │
└──────────────┴──────────────┴──────────┴────────────┘
                        ↓ HTTP/WebSocket
┌─────────────────────────────────────────────────────┐
│                 API 网关层 (Gateway)                  │
│         Fastdotnet.WebApi + 插件动态路由              │
└─────────────────────────────────────────────────────┘
                        ↓
┌─────────────────────────────────────────────────────┐
│                业务服务层 (Services)                  │
│  用户服务 | 权限服务 | 业务服务 | 插件服务            │
└─────────────────────────────────────────────────────┘
                        ↓
┌─────────────────────────────────────────────────────┐
│              数据访问层 (Data Access)                 │
│          SqlSugar ORM + 多数据库支持                  │
└─────────────────────────────────────────────────────┘
                        ↓
┌─────────────────────────────────────────────────────┐
│                数据存储层 (Storage)                   │
│   SQL Server | PostgreSQL | MySQL | SQLite | 达梦    │
└─────────────────────────────────────────────────────┘

🎯 多端架构设计

前端项目划分

Fastdotnet 的前端按照使用场景分为管理端和应用端：

1. 管理端 (Admin)

项目位置: Web/fastdotnet-admin

特点:

面向系统管理员和运营人员
提供系统配置、用户管理、权限控制等功能
功能完整，界面复杂
端口: http://localhost:18888

适用场景:

后台管理系统
数据管理
系统配置
用户权限管理

2. 应用端 (App)

项目位置:

Web 应用端: Web/fastdotnet-app（端口: 18887）
桌面端: 待开发
移动端: 待开发

特点:

面向最终用户
界面简洁，注重用户体验
功能聚焦于核心业务
支持多平台（Web、桌面、移动）

适用场景:

用户前台页面
业务操作界面
数据展示
移动端应用

开发路线图

阶段 1 (当前) ✅
└── Web 管理端 (fastdotnet-admin)
└── Web 应用端 (fastdotnet-app)

阶段 2 (规划中) 📋
└── 桌面端应用 (Avalonia) ✅ 已确定
└── 移动端应用 (技术栈待考量)

阶段 3 (未来) 🔮
└── 小程序
└── H5 轻应用

🔐 API 作用域设计

为了区分不同端的 API 访问权限，Fastdotnet 引入了 API 作用域机制。

ApiUsageScopeEnum

定义在 Fastdotnet.Core.Enum.ApiUsageScopeEnum：

csharp

public enum ApiUsageScopeEnum
{
    /// <summary>
    /// Admin管理端专用
    /// </summary>
    AdminOnly = 1,

    /// <summary>
    /// App用户端专用
    /// </summary>
    AppOnly = 2,

    /// <summary>
    /// 两端通用
    /// </summary>
    Both = 3
}

ApiUsageScopeAttribute

通过特性标记 API 的作用域：

csharp

using Fastdotnet.Core.Attributes;
using Fastdotnet.Core.Enum;

[ApiController]
[Route("api/[controller]")]
[ApiUsageScope(ApiUsageScopeEnum.AdminOnly)]  // 仅管理端可访问
public class SystemConfigController : ControllerBase
{
    // ...
}

[ApiController]
[Route("api/[controller]")]
[ApiUsageScope(ApiUsageScopeEnum.AppOnly)]  // 仅应用端可访问
public class UserProfileController : ControllerBase
{
    // ...
}

[ApiController]
[Route("api/[controller]")]
[ApiUsageScope(ApiUsageScopeEnum.Both)]  // 两端都可访问
public class CommonDataController : ControllerBase
{
    // ...
}

作用域验证中间件

框架会自动验证 API 的作用域，确保：

管理端请求只能访问标记为 AdminOnly 或 Both 的 API
应用端请求只能访问标记为 AppOnly 或 Both 的 API
未标记的 API 默认为 Both（两端通用）

最佳实践

原则:

✅ 系统管理类 API 标记为 AdminOnly
✅ 用户业务类 API 标记为 AppOnly
✅ 公共数据类 API 标记为 Both
❌ 避免在应用端暴露管理功能

示例:

csharp

// ✅ 正确：用户管理仅限管理端
[ApiUsageScope(ApiUsageScopeEnum.AdminOnly)]
public class UserController : ControllerBase
{
    [HttpPost("create")]  // 创建用户
    public IActionResult Create() { ... }
    
    [HttpPut("{id}/role")]  // 分配角色
    public IActionResult AssignRole() { ... }
}

// ✅ 正确：个人信息仅限应用端
[ApiUsageScope(ApiUsageScopeEnum.AppOnly)]
public class ProfileController : ControllerBase
{
    [HttpGet("me")]  // 获取我的信息
    public IActionResult GetMyProfile() { ... }
    
    [Put("me")]  // 更新我的信息
    public IActionResult UpdateMyProfile() { ... }
}

// ✅ 正确：字典数据两端通用
[ApiUsageScope(ApiUsageScopeEnum.Both)]
public class DictController : ControllerBase
{
    [HttpGet("list")]  // 获取字典列表
    public IActionResult GetList() { ... }
}

📦 分层架构详解

1. 表现层 (Presentation Layer)

Fastdotnet.WebApi

职责：

HTTP 请求处理
路由匹配
参数验证
响应格式化

包含：

Controllers - API 控制器
Middleware - 中间件（认证、授权、日志等）
Filters - 过滤器
Endpoints - Minimal API 端点

2. 业务层 (Business Layer)

Fastdotnet.Service

职责：

业务逻辑实现
事务管理
数据校验
业务流程编排

包含：

IService - 服务接口
Service - 服务实现
DTOs - 数据传输对象

3. 领域层 (Domain Layer)

Fastdotnet.Core

职责：

核心业务实体
领域模型
业务规则
通用工具

包含：

Entities - 实体类
Enums - 枚举定义
Attributes - 自定义特性
Utils - 工具类
Exceptions - 异常定义

4. 数据层 (Data Layer)

Fastdotnet.Orm

职责：

数据库访问
ORM 映射
查询构建
缓存管理

基于 SqlSugar ORM 框架，支持：

多数据库切换
读写分离
分库分表
AOP 拦截

🔌 插件化架构

插件系统优势

模块化解耦：功能独立开发和部署
热插拔：无需重启即可加载/卸载插件
按需启用：根据业务需求选择插件
易于维护：问题隔离，便于调试

插件结构

Plugins/PluginName/
├── Backend/                    # 插件后端
│   ├── Controllers/           # API 控制器
│   ├── Services/              # 业务服务
│   ├── Models/                # 数据模型
│   └── PluginName.csproj      # 项目文件
├── Frontend/                   # 插件前端
│   ├── views/                 # 页面组件
│   ├── components/            # 通用组件
│   ├── router/                # 路由配置
│   └── package.json           # 依赖配置
└── README.md                   # 插件说明

插件生命周期

安装 → 加载 → 初始化 → 运行 → 卸载
  ↓      ↓        ↓       ↓      ↓
复制   扫描    注册    提供服务  清理
文件   程序集  服务    和路由   资源

🔒 安全架构

认证方式

JWT Token - 主要的认证方式
OAuth2/OIDC - 第三方登录支持
API Key - 服务端对服务端调用

授权模型

RBAC (Role-Based Access Control)
- 用户 → 角色 → 权限
- 细粒度权限控制到按钮级别
数据权限
- 行级权限（只能查看自己的数据）
- 部门权限（只能查看本部门数据）
- 自定义权限策略

安全措施

HTTPS 强制
CORS 配置
SQL 注入防护
XSS 防护
CSRF 防护
请求频率限制
敏感数据加密

📊 技术栈总览

后端技术栈

类别	技术	版本
运行时	.NET	10.0+
Web 框架	ASP.NET Core	10.0
ORM	SqlSugar	最新版
依赖注入	Autofac	最新版
认证授权	JWT + Identity	-
文档	Swagger/OpenAPI	-
实时通信	SignalR	-
缓存	Redis / MemoryCache	-
日志	Serilog	-

前端技术栈

类别	技术	版本	说明
Web 框架	Vue 3	3.x	管理端和应用端
语言	TypeScript	5.x	类型安全
UI 库	Element Plus	2.x	Vue 3 组件库
构建工具	Vite	5.x	极速构建
状态管理	Pinia	2.x	Vue 3 官方推荐
路由	Vue Router	4.x	官方路由
HTTP 客户端	Axios	1.x	Promise 基于
微前端	qiankun	2.x	插件独立部署
桌面端	Avalonia	最新版	跨平台桌面应用 ✅ 已确定
移动端	待考量	-	技术选型中 📋

数据库支持

✅ SQL Server 2019+
✅ PostgreSQL 14+
✅ MySQL 8.0+
✅ SQLite 3.x
✅ 达梦数据库 DM8

🚀 性能优化

后端优化

异步编程 (async/await)
数据库连接池
查询缓存
响应压缩
静态文件 CDN

前端优化

代码分割
懒加载
图片优化
浏览器缓存
Service Worker

📚 下一步

插件系统详解 - 深入了解插件架构
权限模型 - RBAC 和数据权限
后端开发 - 开始后端开发
前端开发 - 开始前端开发

系统架构 ​

🏗️ 整体架构 ​

🎯 多端架构设计 ​

前端项目划分 ​

1. 管理端 (Admin) ​

2. 应用端 (App) ​

开发路线图 ​

🔐 API 作用域设计 ​

ApiUsageScopeEnum ​

ApiUsageScopeAttribute ​

作用域验证中间件 ​

最佳实践 ​

📦 分层架构详解 ​

1. 表现层 (Presentation Layer) ​

2. 业务层 (Business Layer) ​

3. 领域层 (Domain Layer) ​

4. 数据层 (Data Layer) ​

🔌 插件化架构 ​

插件系统优势 ​

插件结构 ​

插件生命周期 ​

🔒 安全架构 ​

认证方式 ​

授权模型 ​

安全措施 ​

📊 技术栈总览 ​

后端技术栈 ​

前端技术栈 ​

数据库支持 ​

🚀 性能优化 ​

后端优化 ​

前端优化 ​

📚 下一步 ​

系统架构

🏗️ 整体架构

🎯 多端架构设计

前端项目划分

1. 管理端 (Admin)

2. 应用端 (App)

开发路线图

🔐 API 作用域设计

ApiUsageScopeEnum

ApiUsageScopeAttribute

作用域验证中间件

最佳实践

📦 分层架构详解

1. 表现层 (Presentation Layer)

2. 业务层 (Business Layer)

3. 领域层 (Domain Layer)

4. 数据层 (Data Layer)

🔌 插件化架构

插件系统优势

插件结构

插件生命周期

🔒 安全架构

认证方式

授权模型

安全措施

📊 技术栈总览

后端技术栈

前端技术栈

数据库支持

🚀 性能优化

后端优化

前端优化

📚 下一步