# Furion_qlSugar

**Repository Path**: chenbool/furion_ql-sugar

## Basic Information

- **Project Name**: Furion_qlSugar
- **Description**: c#  Furion + qlSugar  Api
- **Primary Language**: C#
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-04-16
- **Last Updated**: 2026-04-16

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# MyFurionApi - WebAPI 项目文档

## 📖 项目概述

MyFurionApi 是一个基于 **.NET 10** 的 WebAPI 项目，使用 **SqlSugar** 作为 ORM 框架连接 **MySQL** 数据库。项目实现了完整的用户管理系统，包含密码加密、性别枚举、自动数据库迁移等功能。

## 🚀 技术栈

| 技术 | 版本 | 说明 |
|------|------|------|
| .NET | 10.0 | 开发框架 |
| SqlSugar | 5.1.4.170 | ORM 框架 |
| MySQL | 8.0+ | 数据库 |
| Swashbuckle.AspNetCore | 6.5.0 | Swagger API 文档 |

## 📁 项目结构

```
MyFurionApi/
├── Common/                          # 公共工具类
│   ├── GenderEnum.cs               # 性别枚举定义
│   └── PasswordHelper.cs           # 密码加密帮助类
├── Controllers/                     # API 控制器
│   └── UserController.cs           # 用户管理控制器
├── Entity/                          # 实体类
│   └── SysUser.cs                  # 用户实体
├── Properties/                      # 项目属性
│   └── launchSettings.json         # 启动配置
├── appsettings.json                # 应用配置文件
├── appsettings.Development.json    # 开发环境配置
├── MyFurionApi.csproj              # 项目文件
├── MyFurionApi.http                # HTTP 测试文件
├── Program.cs                      # 程序入口
└── readme.md                       # 项目文档
```

## ⚙️ 配置说明

### 1. 数据库连接字符串

编辑 `appsettings.json`：

```json
{
  "ConnectionStrings": {
    "Default": "Server=localhost;Port=3306;Database=testdb;Uid=root;Pwd=your_password;Charset=utf8mb4;"
  }
}
```

**参数说明：**
- `Server`: MySQL 服务器地址
- `Port`: MySQL 端口（默认 3306）
- `Database`: 数据库名称
- `Uid`: 数据库用户名
- `Pwd`: 数据库密码
- `Charset`: 字符集（建议使用 utf8mb4）

### 2. 密码加密盐值

编辑 `Common/PasswordHelper.cs`：

```csharp
private const string Salt = "MyFurionApi_Salt_2024";
```

**注意：** 生产环境建议将盐值放到配置文件中！

## 🗄️ 数据库设计

### sys_user 表结构

| 字段名 | 类型 | 长度 | 可空 | 说明 |
|--------|------|------|------|------|
| Id | bigint | - | 否 | 主键，自增 |
| UserName | varchar | 50 | 否 | 用户名（登录账号） |
| Password | varchar | 100 | 否 | 密码（SHA256 加密） |
| Email | varchar | 100 | 是 | 邮箱地址 |
| Sex | int | - | 是 | 性别（0-未知，1-男，2-女） |
| Name | varchar | 50 | 是 | 显示名称/昵称 |
| Age | int | - | 是 | 年龄 |
| CreateTime | datetime | - | 是 | 创建时间 |

### 性别枚举

```csharp
public enum GenderEnum
{
    Unknown = 0,  // 未知/保密
    Male = 1,     // 男
    Female = 2    // 女
}
```

## 🔐 安全特性

### 1. 密码加密

- **算法**: SHA256 + 盐值
- **加密流程**: 明文密码 + 盐值 → SHA256 哈希 → 64位十六进制字符串
- **安全特性**:
  - 使用盐值防止彩虹表攻击
  - 恒定时间比较防止时序攻击
  - API 返回数据自动清除密码字段

### 2. 密码验证

```csharp
// 加密密码
string encrypted = PasswordHelper.Encrypt("123456");

// 验证密码
bool isValid = PasswordHelper.Verify("123456", encryptedPassword);
```

## 📡 API 接口文档

### 基础信息

- **Base URL**: `http://localhost:5211`
- **Swagger UI**: `http://localhost:5211/swagger`

### 接口列表

#### 1. 获取所有用户

```http
GET /api/user
```

**响应示例：**
```json
[
  {
    "id": 1,
    "userName": "zhangsan",
    "email": "zhangsan@example.com",
    "sex": 1,
    "name": "张三",
    "age": 25,
    "createTime": "2024-01-15T10:30:00"
  }
]
```

#### 2. 根据 ID 获取用户

```http
GET /api/user/{id}
```

**响应示例：**
```json
{
  "id": 1,
  "userName": "zhangsan",
  "email": "zhangsan@example.com",
  "sex": 1,
  "name": "张三",
  "age": 25,
  "createTime": "2024-01-15T10:30:00"
}
```

#### 3. 创建用户

```http
POST /api/user
Content-Type: application/json
```

**请求体：**
```json
{
  "userName": "zhangsan",
  "password": "123456",
  "email": "zhangsan@example.com",
  "sex": 1,
  "name": "张三",
  "age": 25
}
```

**字段说明：**
| 字段 | 类型 | 必填 | 说明 |
|------|------|------|------|
| userName | string | 是 | 用户名，用于登录 |
| password | string | 是 | 密码（明文，服务器自动加密） |
| email | string | 否 | 邮箱地址 |
| sex | int | 否 | 性别：0-未知，1-男，2-女 |
| name | string | 否 | 显示名称 |
| age | int | 否 | 年龄 |

**响应示例：**
```json
{
  "id": 1,
  "userName": "zhangsan",
  "email": "zhangsan@example.com",
  "sex": 1,
  "name": "张三",
  "age": 25,
  "createTime": "2024-01-15T10:30:00"
}
```

#### 4. 更新用户

```http
PUT /api/user/{id}
Content-Type: application/json
```

**请求体：**
```json
{
  "userName": "zhangsan",
  "password": "newpassword",
  "email": "zhangsan@example.com",
  "sex": 1,
  "name": "张三",
  "age": 26
}
```

**注意：**
- 如果提供 `password`，会自动加密
- 如果不提供 `password`，保持原密码不变

#### 5. 删除用户

```http
DELETE /api/user/{id}
```

**响应：** HTTP 204 NoContent

#### 6. 用户登录

```http
POST /api/user/login
Content-Type: application/json
```

**请求体：**
```json
{
  "userName": "zhangsan",
  "password": "123456"
}
```

**成功响应：**
```json
{
  "id": 1,
  "userName": "zhangsan",
  "email": "zhangsan@example.com",
  "sex": 1,
  "name": "张三",
  "age": 25,
  "createTime": "2024-01-15T10:30:00"
}
```

**失败响应：** HTTP 401 Unauthorized
```json
{
  "message": "用户名或密码错误"
}
```

## 🚀 快速开始

### 1. 环境准备

- 安装 .NET 10 SDK
- 安装 MySQL 8.0+
- 创建数据库 `testdb`

### 2. 配置数据库

编辑 `appsettings.json`，修改连接字符串中的密码。

### 3. 运行项目

```bash
# 进入项目目录
cd MyFurionApi

# 还原 NuGet 包
dotnet restore

# 运行项目
dotnet run
```

### 4. 访问 API

- **Swagger UI**: http://localhost:5211/swagger
- **API 地址**: http://localhost:5211

## 🧪 测试示例

### 创建用户

```bash
curl -X POST http://localhost:5211/api/user \
  -H "Content-Type: application/json" \
  -d '{
    "userName": "zhangsan",
    "password": "123456",
    "email": "zhangsan@example.com",
    "sex": 1,
    "name": "张三",
    "age": 25
  }'
```

### 用户登录

```bash
curl -X POST http://localhost:5211/api/user/login \
  -H "Content-Type: application/json" \
  -d '{
    "userName": "zhangsan",
    "password": "123456"
  }'
```

### 获取用户列表

```bash
curl http://localhost:5211/api/user
```

## 🔧 核心功能说明

### 1. 自动数据库迁移

项目启动时自动检查并创建数据库表：

```csharp
// Program.cs 中配置
using (var scope = app.Services.CreateScope())
{
    var dbInitializer = scope.ServiceProvider.GetRequiredService<DatabaseInitializer>();
    dbInitializer.Initialize();
}
```

**特点：**
- 表不存在时自动创建
- 支持增量更新表结构
- 控制台输出初始化日志

### 2. SQL 日志记录

开发环境自动记录执行的 SQL 语句：

```csharp
db.Aop.OnLogExecuting = (sql, pars) =>
{
    Console.WriteLine($"[SQL] {sql}");
    Console.WriteLine($"[参数] {string.Join(", ", pars.Select(p => p.Value?.ToString() ?? "null"))}");
};
```

### 3. 依赖注入

```csharp
// 注册服务
builder.Services.AddSingleton<ISqlSugarClient>(...);
builder.Services.AddSingleton<DatabaseInitializer>();

// 构造函数注入
public UserController(ISqlSugarClient db)
{
    _db = db;
}
```

## 📋 开发规范

### 1. 实体类规范

```csharp
[SugarTable("表名")]
public class EntityName
{
    [SugarColumn(IsPrimaryKey = true, IsIdentity = true)]
    public long Id { get; set; }
    
    [SugarColumn(Length = 50, IsNullable = false)]
    public string RequiredField { get; set; } = string.Empty;
    
    [SugarColumn(IsNullable = true)]
    public string? OptionalField { get; set; }
}
```

### 2. API 控制器规范

```csharp
[ApiController]
[Route("api/[controller]")]
public class EntityController : ControllerBase
{
    private readonly ISqlSugarClient _db;
    
    public EntityController(ISqlSugarClient db)
    {
        _db = db;
    }
    
    [HttpGet]
    public async Task<IActionResult> GetAll()
    {
        var list = await _db.Queryable<Entity>().ToListAsync();
        return Ok(list);
    }
}
```

## ⚠️ 注意事项

1. **生产环境**
   - 修改密码盐值
   - 关闭 SQL 日志记录
   - 配置 HTTPS
   - 启用身份验证和授权

2. **数据库安全**
   - 使用强密码
   - 限制数据库访问权限
   - 定期备份数据

3. **密码安全**
   - 永远不要传输明文密码
   - 定期更换盐值
   - 考虑使用更安全的算法（如 bcrypt）

## 🐛 常见问题

### 1. 数据库连接失败

**问题：** 无法连接到 MySQL 数据库

**解决：**
- 检查 MySQL 服务是否启动
- 检查连接字符串配置
- 检查防火墙设置

### 2. 表创建失败

**问题：** 自动迁移时表创建失败

**解决：**
- 检查数据库用户是否有创建表权限
- 检查数据库是否存在
- 查看控制台错误日志

### 3. 密码验证失败

**问题：** 登录时密码验证失败

**解决：**
- 确认密码是否正确
- 检查盐值是否一致
- 查看数据库中存储的密码格式

## 📄 许可证

MIT License

## 🤝 贡献

欢迎提交 Issue 和 Pull Request！

## 📞 联系方式

如有问题，请联系项目维护者。

---

**最后更新：** 2024年