# FreeSqlDemo

**Repository Path**: phusun/free-sql-demo

## Basic Information

- **Project Name**: FreeSqlDemo
- **Description**: FreeSql在Winform中的最佳实践示例
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 2
- **Forks**: 2
- **Created**: 2025-07-05
- **Last Updated**: 2025-12-27

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# FreeSql Demo - WinForms 最佳实践演示项目

## 🎯 项目简介

这是一个基于 FreeSql ORM 框架的 WinForms 桌面应用程序，展示了 FreeSql 在实际项目中的最佳实践用法。项目采用现代化的分层架构设计，包含完整的用户管理、产品管理、订单管理等功能模块。

**✅ 项目已完成并可正常运行！**

## 技术栈

- **.NET 8.0** - 最新的 .NET 框架
- **WinForms** - 桌面应用程序框架
- **FreeSql 3.2.833** - 强大的 ORM 框架
- **SQLite** - 轻量级数据库
- **Microsoft.Extensions.DependencyInjection** - 依赖注入容器
- **Serilog** - 结构化日志框架

## 项目特色

### 🏗️ 架构设计
- **分层架构**: 实体层、数据访问层、业务逻辑层、表示层
- **依赖注入**: 使用 Microsoft.Extensions.DependencyInjection
- **Repository 模式**: 封装数据访问逻辑
- **UnitOfWork 模式**: 事务管理

### 🚀 FreeSql 最佳实践
- **CodeFirst**: 自动同步数据库结构
- **实体配置**: 使用 Attribute 和 FluentAPI 配置实体
- **导航属性**: 一对一、一对多、多对多关系
- **软删除**: 逻辑删除实现
- **审计字段**: 自动填充创建时间、更新时间等
- **分页查询**: 高效的分页实现
- **动态查询**: 灵活的查询条件构建
- **聚合查询**: 统计分析功能
- **事务处理**: 确保数据一致性

### 📊 功能模块
- **用户管理**: 用户增删改查、角色分配、状态管理
- **产品管理**: 产品信息管理、分类管理、库存管理
- **订单管理**: 订单处理、状态跟踪、统计分析
- **系统管理**: 权限控制、日志记录、异常处理

## 项目结构

```
FreeSqlDemo/
├── Models/                 # 实体模型
│   ├── BaseEntity.cs      # 基础实体类
│   ├── User.cs            # 用户实体
│   ├── Role.cs            # 角色实体
│   ├── Category.cs        # 分类实体
│   ├── Product.cs         # 产品实体
│   ├── Order.cs           # 订单实体
│   └── OrderItem.cs       # 订单明细实体
├── Repositories/          # 数据访问层
│   ├── IBaseRepository.cs # 基础仓储接口
│   ├── BaseRepository.cs  # 基础仓储实现
│   ├── IUserRepository.cs # 用户仓储接口
│   ├── IProductRepository.cs # 产品仓储接口
│   └── IOrderRepository.cs # 订单仓储接口
├── Services/              # 业务逻辑层
│   ├── IUserService.cs    # 用户服务接口
│   ├── UserService.cs     # 用户服务实现
│   ├── IProductService.cs # 产品服务接口
│   └── ProductService.cs  # 产品服务实现
├── Forms/                 # 窗体界面
│   ├── LoginForm.cs       # 登录窗体
│   ├── MainForm.cs        # 主窗体
│   └── UserManagementForm.cs # 用户管理窗体
├── Data/                  # 数据上下文
│   └── FreeSqlDbContext.cs # FreeSql 数据库上下文
├── Common/                # 公共组件
│   ├── ApiResult.cs       # 统一响应模型
│   ├── BusinessException.cs # 业务异常类
│   ├── ServiceCollectionExtensions.cs # 服务注册扩展
│   ├── GlobalExceptionHandler.cs # 全局异常处理
│   └── PerformanceMonitor.cs # 性能监控
├── Properties/            # 项目属性
├── appsettings.json       # 应用配置
└── Program.cs             # 程序入口
```

## 🚀 快速开始

### 1. 环境要求
- .NET 8.0 SDK
- Windows 10/11 或 Windows Server 2019+
- Visual Studio 2022 或 VS Code（可选）

### 2. 运行项目
```bash
# 编译项目
dotnet build

# 运行项目
dotnet run
```

### 3. 登录系统
- **用户名**: `admin`
- **密码**: `123456`

### 4. 功能验证
- ✅ 登录功能正常
- ✅ 用户管理：查看、搜索、分页
- ✅ 数据库自动创建和初始化
- ✅ 日志记录系统正常工作

## 核心功能演示

### 1. 实体设计
```csharp
[Table(Name = "users")]
[Index("idx_username", "UserName", true)]
public class User : BaseEntity, IEntityCreated, IEntityModified
{
    [Column(StringLength = 50)]
    public string UserName { get; set; } = string.Empty;
    
    [Navigate(nameof(Order.UserId))]
    public virtual List<Order> Orders { get; set; } = new();
}
```

### 2. Repository 模式
```csharp
public class UserRepository : BaseRepository<User, long>, IUserRepository
{
    public async Task<User?> GetByUserNameAsync(string userName)
    {
        return await Select.Where(u => u.UserName == userName && !u.IsDeleted).FirstAsync();
    }
}
```

### 3. 业务服务
```csharp
public async Task<ApiResult<User>> LoginAsync(string userName, string password, string loginIp)
{
    var user = await _userRepository.GetByUserNameAsync(userName);
    if (user == null || !VerifyPassword(password, user.PasswordHash))
    {
        return ApiResult<User>.Fail("用户名或密码错误");
    }
    
    await _userRepository.UpdateLoginInfoAsync(user.Id, loginIp);
    return ApiResult<User>.Ok(user, "登录成功");
}
```

### 4. 分页查询
```csharp
public async Task<(List<User> Items, long Total)> GetPageListAsync(int pageIndex, int pageSize)
{
    var query = Select.Where(u => !u.IsDeleted);
    var total = await query.CountAsync();
    var items = await query.Page(pageIndex, pageSize).ToListAsync();
    return (items, total);
}
```

### 5. 动态查询
```csharp
var query = _productRepository.Select.Where(p => !p.IsDeleted);

if (!string.IsNullOrWhiteSpace(keyword))
{
    query = query.Where(p => p.Name.Contains(keyword) || p.Code.Contains(keyword));
}

if (categoryId.HasValue)
{
    query = query.Where(p => p.CategoryId == categoryId.Value);
}
```

### 6. 事务处理
```csharp
using var uow = _fsql.CreateUnitOfWork();
try
{
    await _userRepository.InsertAsync(user);
    await _fsql.Insert(userRoles).ExecuteAffrowsAsync();
    uow.Commit();
}
catch
{
    uow.Rollback();
    throw;
}
```

## ⚙️ 配置说明

### 数据库配置 (appsettings.json)
```json
{
  "ConnectionStrings": {
    "DefaultConnection": "Data Source=FreeSqlDemo.db;Cache=Shared"
  },
  "FreeSql": {
    "UseAutoSyncStructure": true,
    "UseMonitorCommand": true,
    "UseAdoConnectionPool": true
  }
}
```

### 默认数据
系统启动时会自动创建：
- 管理员角色和普通用户角色
- 默认管理员账户 (admin/123456)
- 默认产品分类

## 📊 技术特色

### 日志系统
- 控制台输出和文件记录
- 结构化日志（Serilog）
- 性能监控和慢查询检测

### 异常处理
- 全局异常处理机制
- 自定义业务异常类型
- 用户友好的错误提示

## 🎯 学习价值

这个项目是学习 FreeSql 和现代 .NET 桌面应用开发的绝佳资源：

1. **FreeSql 深度应用**: 从基础到高级的完整示例
2. **架构设计**: 分层架构、设计模式的实际应用
3. **最佳实践**: 异常处理、日志记录、性能优化
4. **实战经验**: 真实业务场景的解决方案

### 最佳实践要点
- ✅ 实体设计：基础实体类，统一审计字段
- ✅ 仓储模式：封装数据访问，提供统一接口
- ✅ 服务层：处理业务逻辑，事务管理
- ✅ 依赖注入：降低耦合度，提高可测试性
- ✅ 异常处理：统一异常处理机制
- ✅ 日志记录：完善的日志记录和性能监控

## 🚨 故障排除

### 常见问题
1. **编译错误**: 确保安装了 .NET 8.0 SDK
2. **运行错误**: 检查 appsettings.json 配置
3. **登录失败**: 删除 FreeSqlDemo.db 文件，重新运行应用

### 日志查看
- 控制台输出：实时日志
- 文件日志：`logs/freesql-demo-*.log`

## 📄 许可证

MIT License - 欢迎学习和使用！