# 基于.net 10的webapi分层系统

**Repository Path**: hlw422/net10-webapi-system

## Basic Information

- **Project Name**: 基于.net 10的webapi分层系统
- **Description**: 基于.net 10的webapi分层系统
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-06-17
- **Last Updated**: 2026-06-18

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# NetFull WebAPI System

基于 .NET 10 + SqlSugar + PostgreSQL 的标准后端服务模板，采用分层架构设计，包含 RBAC 权限管理、JWT 认证、全局异常处理、参数校验、限流、日志等完整功能。

## 技术栈

| 技术 | 版本 | 用途 |
|------|------|------|
| .NET | 10.0 | 运行框架 |
| SqlSugar | 5.x | ORM 框架 |
| PostgreSQL | 14+ | 数据库 |
| JWT | - | 身份认证 |
| FluentValidation | 12.x | 参数校验 |
| Serilog | 10.x | 日志框架 |
| Swashbuckle | 10.x | Swagger 文档 |
| xUnit | - | 单元测试 |
| Moq | - | Mock 框架 |

## 项目结构

```
net_full_webapi/
├── src/
│   ├── NetFull.WebApi/              # API 层 - 控制器、中间件、启动配置
│   │   ├── Controllers/             # API 控制器
│   │   ├── Middlewares/             # 中间件（异常处理、日志）
│   │   ├── Filters/                 # 过滤器（参数校验）
│   │   ├── Program.cs               # 应用入口
│   │   └── appsettings.json         # 配置文件
│   ├── NetFull.Application/         # 应用层 - 业务逻辑、DTO、服务
│   │   ├── Auth/                    # 认证模块
│   │   │   ├── DTOs/                # 数据传输对象
│   │   │   ├── Services/            # 认证服务
│   │   │   └── Validators/          # 参数校验器
│   │   ├── Users/                   # 用户模块
│   │   │   ├── DTOs/
│   │   │   ├── Services/
│   │   │   └── Validators/
│   │   └── Common/                  # 通用组件
│   │       ├── Models/              # 通用模型（ApiResponse、分页）
│   │       ├── Interfaces/          # 通用接口
│   │       └── Services/            # 基础服务
│   ├── NetFull.Core/                # 核心层 - 实体、枚举、常量
│   │   ├── Entities/                # 数据库实体
│   │   ├── Enums/                   # 枚举定义
│   │   └── Constants/               # 常量定义
│   └── NetFull.Infrastructure/      # 基础设施层 - 数据库、仓储
│       ├── Database/                # 数据库上下文
│       └── Repositories/            # 仓储模式
└── tests/
    └── NetFull.Tests/               # 单元测试
```

## 快速开始

### 环境要求

- .NET 10 SDK
- PostgreSQL 14+
- 可选：Docker（用于运行 PostgreSQL）

### 1. 克隆项目

```bash
git clone http://localhost:3001/hlw/net10-webapi-system.git
cd net10-webapi-system
```

### 2. 配置数据库

编辑 `src/NetFull.WebApi/appsettings.json`：

```json
{
  "ConnectionStrings": {
    "Default": "Host=localhost;Port=5432;Database=netfull;Username=postgres;Password=your_password"
  }
}
```

### 3. 配置 JWT

```json
{
  "Jwt": {
    "Key": "YourSuperSecretKeyThatIsAtLeast32CharactersLong!",
    "Issuer": "NetFull",
    "Audience": "NetFull",
    "ExpireHours": 24
  }
}
```

### 4. 运行项目

```bash
cd src/NetFull.WebApi
dotnet run
```

应用启动后会自动：
- 创建数据库（如果不存在）
- 创建所有数据表（CodeFirst 模式）

### 5. 访问 Swagger

打开浏览器访问：`http://localhost:5000/swagger`

## 数据库表结构

项目使用 SqlSugar CodeFirst 模式，启动时自动建表：

| 表名 | 说明 | 主要字段 |
|------|------|----------|
| `sys_user` | 用户表 | Id, Username, PasswordHash, Nickname, Email, Phone, Status |
| `sys_role` | 角色表 | Id, Name, Code, Description, Sort, Status |
| `sys_permission` | 权限表 | Id, Name, Code, Description, Type |
| `sys_menu` | 菜单表 | Id, ParentId, Name, Path, Component, Icon, Sort, Status |
| `sys_user_role` | 用户角色关联 | UserId (PK), RoleId (PK) |
| `sys_role_permission` | 角色权限关联 | RoleId (PK), PermissionId (PK) |

所有表继承 `BaseEntity`，包含：
- `Id` - 主键（自增）
- `CreatedAt` - 创建时间
- `UpdatedAt` - 更新时间
- `IsDeleted` - 软删除标记

## API 接口

### 认证接口

| 方法 | 路径 | 说明 | 认证 |
|------|------|------|------|
| POST | `/api/auth/register` | 用户注册 | 否 |
| POST | `/api/auth/login` | 用户登录 | 否 |

### 用户接口

| 方法 | 路径 | 说明 | 认证 |
|------|------|------|------|
| GET | `/api/user/{id}` | 获取用户详情 | 是 |
| GET | `/api/user` | 分页查询用户 | 是 |
| POST | `/api/user` | 创建用户 | 是 |
| PUT | `/api/user` | 更新用户 | 是 |
| DELETE | `/api/user/{id}` | 删除用户 | 是 |

### 请求示例

#### 注册

```bash
curl -X POST http://localhost:5000/api/auth/register \
  -H "Content-Type: application/json" \
  -d '{
    "username": "admin",
    "password": "123456",
    "nickname": "管理员",
    "email": "admin@example.com"
  }'
```

#### 登录

```bash
curl -X POST http://localhost:5000/api/auth/login \
  -H "Content-Type: application/json" \
  -d '{
    "username": "admin",
    "password": "123456"
  }'
```

响应：
```json
{
  "code": 200,
  "message": "success",
  "data": {
    "token": "eyJhbGciOiJIUzI1NiIs...",
    "expiresAt": "2026-06-18T14:00:00Z",
    "username": "admin",
    "userId": 1
  }
}
```

#### 访问受保护接口

```bash
curl -X GET http://localhost:5000/api/user/1 \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..."
```

## 核心功能

### 1. 统一响应格式

所有接口返回统一的 `ApiResponse<T>` 格式：

```json
{
  "code": 200,
  "message": "success",
  "data": {}
}
```

错误响应：
```json
{
  "code": 400,
  "message": "用户名不能为空; 密码长度不能少于6个字符"
}
```

### 2. 参数校验

使用 FluentValidation 进行自动参数校验，通过 `ValidationFilter` 全局拦截：

- 登录：用户名非空、密码≥6位
- 注册：用户名格式、密码强度、邮箱格式
- 创建用户：用户名唯一性、手机号格式

### 3. 全局异常处理

`GlobalExceptionMiddleware` 统一捕获异常：

| 异常类型 | HTTP 状态码 | 响应消息 |
|----------|-------------|----------|
| UnauthorizedAccessException | 401 | 未授权访问 |
| KeyNotFoundException | 404 | 资源不存在 |
| ArgumentException | 400 | 具体错误信息 |
| 其他异常 | 500 | 服务器内部错误 |

### 4. JWT 认证

- 登录成功后返回 JWT Token
- Token 有效期可在配置中调整（默认 24 小时）
- 使用 `[Authorize]` 特性保护接口
- Claims 包含：UserId、Username、Jti

### 5. 日志管理

使用 Serilog 实现结构化日志：

- 控制台输出（开发环境）
- 文件滚动（按天切割）
- 日志路径：`logs/log-{date}.txt`

### 6. 接口限流

基于 ASP.NET Core Rate Limiting：

- 固定窗口限流：100 次/分钟
- 超出限制返回 429

### 7. 分页查询

统一分页请求/响应格式：

请求参数：
```json
{
  "page": 1,
  "pageSize": 10,
  "keyword": "搜索关键词",
  "orderBy": "CreatedAt desc"
}
```

响应格式：
```json
{
  "code": 200,
  "data": {
    "items": [],
    "total": 100,
    "page": 1,
    "pageSize": 10,
    "totalPages": 10
  }
}
```

## 单元测试

运行测试：

```bash
dotnet test
```

测试覆盖：
- AuthService：登录失败场景
- UserService：用户不存在场景

## 配置说明

### appsettings.json 完整配置

```json
{
  "ConnectionStrings": {
    "Default": "Host=localhost;Port=5432;Database=netfull;Username=postgres;Password=postgres"
  },
  "Jwt": {
    "Key": "YourSuperSecretKeyThatIsAtLeast32CharactersLong!",
    "Issuer": "NetFull",
    "Audience": "NetFull",
    "ExpireHours": 24
  },
  "Serilog": {
    "MinimumLevel": {
      "Default": "Information",
      "Override": {
        "Microsoft.AspNetCore": "Warning"
      }
    },
    "WriteTo": [
      { "Name": "Console" },
      {
        "Name": "File",
        "Args": {
          "path": "logs/log-.txt",
          "rollingInterval": "Day"
        }
      }
    ]
  }
}
```

## 扩展指南

### 添加新模块

1. 在 `Core/Entities` 添加实体类
2. 在 `Application` 添加 DTO、Service、Validator
3. 在 `WebApi/Controllers` 添加控制器
4. 在 `DbContext` 添加 SimpleClient 属性
5. 在 `DbInitializer.Initialize()` 注册实体

### 添加新实体示例

```csharp
// Core/Entities/Department.cs
[SugarTable("sys_department", TableDescription = "部门表")]
public class Department : BaseEntity
{
    [SugarColumn(Length = 50, ColumnDescription = "部门名称")]
    public string Name { get; set; } = string.Empty;

    [SugarColumn(ColumnDescription = "父部门ID")]
    public long ParentId { get; set; } = 0;
}
```

## 待实现功能

- [ ] 角色管理（RoleController）
- [ ] 权限管理（PermissionController）
- [ ] 菜单管理（MenuController）
- [ ] 用户角色关联
- [ ] 角色权限关联
- [ ] 基于策略的权限授权
- [ ] 数据库种子数据

## 许可证

MIT License