# JWTWebApi

**Repository Path**: sky0535/JWTWebApi

## Basic Information

- **Project Name**: JWTWebApi
- **Description**: 实现简单的JWT身份认证和授权示例
- **Primary Language**: C#
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 2
- **Forks**: 0
- **Created**: 2025-03-18
- **Last Updated**: 2025-09-21

## Categories & Tags

**Categories**: Uncategorized

**Tags**: JWT, WebApi

## README

# JWT WebAPI 项目

## 📋 项目概述

这是一个基于 ASP.NET Core 8.0 的 Web API 项目，演示了如何使用 JWT (JSON Web Token) 进行身份认证和授权。项目包含了完整的登录认证、订单管理功能，并集成了 Serilog 日志记录、Swagger API 文档等功能。

## ✨ 功能特性

- 🔐 **JWT 身份认证**：完整的 JWT Token 生成、验证和授权机制
- 📊 **订单管理**：受保护的订单查询和管理 API
- 📁 **文件上传**：支持图片文件上传功能
- 📝 **日志记录**：集成 Serilog，支持控制台和文件日志输出
- 📖 **API 文档**：集成 Swagger，提供交互式 API 文档
- 🌐 **CORS 支持**：配置跨域资源共享
- 🎨 **前端测试页面**：提供 HTML 测试页面用于 API 调试

## 🛠️ 技术栈

- **框架**：ASP.NET Core 8.0
- **认证**：JWT Bearer Authentication
- **日志**：Serilog
- **API 文档**：Swagger/OpenAPI
- **序列化**：Newtonsoft.Json
- **前端**：HTML + JavaScript + Bootstrap 3.3.7

## 📦 依赖包

```xml
<PackageReference Include="Microsoft.AspNetCore.Authentication.JwtBearer" Version="8.0.19" />
<PackageReference Include="Microsoft.AspNetCore.Mvc.NewtonsoftJson" Version="8.0.19" />
<PackageReference Include="Serilog.AspNetCore" Version="9.0.0" />
<PackageReference Include="Swashbuckle.AspNetCore" Version="9.0.3" />
<PackageReference Include="System.IdentityModel.Tokens.Jwt" Version="8.13.0" />
```

## 🚀 快速开始

### 环境要求

- .NET 8.0 SDK
- Visual Studio 2022 或 VS Code

### 运行项目

1. **克隆项目**
   ```bash
   git clone <repository-url>
   cd JWTWebApi
   ```

2. **还原依赖**
   ```bash
   dotnet restore
   ```

3. **运行项目**
   ```bash
   dotnet run --project JWTWebApi
   ```

4. **访问应用**
   - API 基础地址：`https://localhost:5001`
   - Swagger 文档：`https://localhost:5001/swagger`
   - 测试页面：`https://localhost:5001/JwtTest.html`

## 📚 API 文档

### 认证接口

#### 获取 JWT Token
```http
POST /api/Login/GetJwtToken
Content-Type: application/json

{
  "userName": "admin",
  "password": "123456"
}
```

**响应示例：**
```json
{
  "success": true,
  "message": "获取Token成功",
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
}
```

### 订单接口

#### 获取订单信息
```http
GET /api/Order?id=1
Authorization: Bearer <your-jwt-token>
```

**响应示例：**
```json
{
  "orderId": 1,
  "customerId": 2,
  "customerName": "admin",
  "tokenUserName": "admin",
  "orderDate": "2024-01-01T10:00:00",
  "totalAmount": 110.0,
  "status": "已完成"
}
```

#### 上传图片
```http
POST /api/Order/UploadImgage
Authorization: Bearer <your-jwt-token>
Content-Type: multipart/form-data

file: <image-file>
```

## 📁 项目结构

```
JWTWebApi/
├── Controllers/              # 控制器
│   ├── LoginController.cs    # 登录认证控制器
│   └── OrderController.cs    # 订单管理控制器
├── Models/                   # 数据模型
│   ├── JwtTokenModel.cs      # JWT Token 模型
│   ├── LoginModel.cs         # 登录模型
│   ├── OrderData.cs          # 订单数据模型
│   └── TokenResult.cs        # Token 结果模型
├── Utils/                    # 工具类
│   ├── AppSettings.cs        # 配置设置
│   └── JwtHelper.cs          # JWT 帮助类
├── wwwroot/                  # 静态文件
│   ├── JwtTest.html          # JWT 测试页面
│   ├── ApiTest.html          # API 测试页面
│   ├── css/                  # 样式文件
│   ├── libs/                 # 第三方库
│   └── scripts/              # JavaScript 文件
├── Uploads/                  # 文件上传目录
├── Program.cs                # 程序入口
├── appsettings.json          # 配置文件
└── JWTWebApi.csproj          # 项目文件
```

## ⚙️ 配置说明

### JWT 配置

在 `appsettings.json` 中配置 JWT 参数：

```json
{
  "Jwt": {
    "Issuer": "http://yourdomain.com",
    "Audience": "web-client",
    "SecretKey": "secret-key@2025-12345678-abc123456789",
    "ExpireMinutes": 60
  }
}
```

### CORS 配置

```json
{
  "CorsAccessorSettings": {
    "AllowCredentials": true,
    "AllowOrigins": [
      "http://localhost:5279",
      "http://localhost:5500",
      "http://127.0.0.1:5500"
    ]
  }
}
```

### 日志配置

项目使用 Serilog 进行日志记录，支持控制台和文件输出：

```json
{
  "Serilog": {
    "MinimumLevel": {
      "Default": "Information",
      "Override": {
        "Microsoft": "Warning",
        "System": "Warning"
      }
    },
    "WriteTo": [
      { "Name": "Console" },
      {
        "Name": "File",
        "Args": {
          "path": "Logs/app-.log",
          "rollingInterval": "Day",
          "retainedFileCountLimit": 30
        }
      }
    ]
  }
}
```

## 🧪 测试

### 使用 Swagger 测试

1. 启动项目后访问 `https://localhost:5001/swagger`
2. 首先调用 `/api/Login/GetJwtToken` 获取 Token
3. 点击 "Authorize" 按钮，输入 `Bearer <your-token>`
4. 测试受保护的 API 接口

### 使用测试页面

访问 `https://localhost:5001/JwtTest.html` 使用内置的测试页面进行功能测试。

### 使用 HTTP 文件测试

项目包含 `JWTWebApi.http` 文件，可以在 Visual Studio 或 VS Code 中直接运行 HTTP 请求进行测试。

## 🔧 开发指南

### 添加新的 API 接口

1. **创建模型**：在 `Models` 文件夹中添加数据模型
2. **创建控制器**：在 `Controllers` 文件夹中添加新的控制器
3. **添加授权**：使用 `[Authorize]` 特性保护需要认证的接口
4. **添加日志**：注入 `ILogger` 并添加适当的日志记录

### 自定义 JWT Claims

在 `JwtHelper.cs` 中修改 `IssueJwt` 方法来添加自定义的 Claims：

```csharp
var claims = new[]
{
    new Claim(ClaimTypes.Name, tokenModel.UserName),
    new Claim(ClaimTypes.Role, tokenModel.Role),
    new Claim("uid", tokenModel.Uid.ToString()),
    // 添加更多自定义 Claims
};
```

### 扩展文件上传功能

当前项目支持图片上传，可以在 `OrderController.cs` 的 `UploadImgage` 方法基础上扩展：

- 添加文件类型验证
- 实现文件大小限制
- 添加文件存储到云服务的功能

## 🔒 安全注意事项

1. **生产环境配置**：
   - 更改默认的 JWT SecretKey
   - 启用 HTTPS
   - 配置适当的 CORS 策略
   - 使用环境变量存储敏感配置

2. **Token 安全**：
   - 设置合理的过期时间（建议不超过24小时）
   - 考虑实现 Refresh Token 机制
   - 避免在客户端长期存储敏感信息
   - 实现 Token 黑名单机制

3. **日志安全**：
   - 避免记录敏感信息（如密码、完整 Token）
   - 定期清理日志文件
   - 在生产环境中调整日志级别

4. **输入验证**：
   - 对所有用户输入进行验证
   - 使用数据注解进行模型验证
   - 防止 SQL 注入和 XSS 攻击

## 🚀 部署指南

### 本地部署

```bash
# 发布项目
dotnet publish -c Release -o ./publish

# 运行发布版本
cd publish
dotnet JWTWebApi.dll
```

### Docker 部署

创建 `Dockerfile`：

```dockerfile
FROM mcr.microsoft.com/dotnet/aspnet:8.0 AS base
WORKDIR /app
EXPOSE 80
EXPOSE 443

FROM mcr.microsoft.com/dotnet/sdk:8.0 AS build
WORKDIR /src
COPY ["JWTWebApi/JWTWebApi.csproj", "JWTWebApi/"]
RUN dotnet restore "JWTWebApi/JWTWebApi.csproj"
COPY . .
WORKDIR "/src/JWTWebApi"
RUN dotnet build "JWTWebApi.csproj" -c Release -o /app/build

FROM build AS publish
RUN dotnet publish "JWTWebApi.csproj" -c Release -o /app/publish

FROM base AS final
WORKDIR /app
COPY --from=publish /app/publish .
ENTRYPOINT ["dotnet", "JWTWebApi.dll"]
```

构建和运行 Docker 容器：

```bash
# 构建镜像
docker build -t jwtwebapi .

# 运行容器
docker run -d -p 8080:80 --name jwtwebapi-container jwtwebapi
```

## 🔄 版本更新

### v1.0.0 (当前版本)
- 基础 JWT 认证功能
- 订单管理 API
- 文件上传功能
- Serilog 日志集成
- Swagger API 文档

## 📚 相关文档

- [Document.md](Document.md) - JWT 技术详细教程
- [ASP.NET Core 官方文档](https://docs.microsoft.com/aspnet/core/)
- [JWT 官方网站](https://jwt.io/)
- [Serilog 文档](https://serilog.net/)

## 🤝 贡献

欢迎提交 Issue 和 Pull Request 来改进这个项目。

### 贡献指南

1. Fork 项目
2. 创建功能分支 (`git checkout -b feature/AmazingFeature`)
3. 提交更改 (`git commit -m 'Add some AmazingFeature'`)
4. 推送到分支 (`git push origin feature/AmazingFeature`)
5. 打开 Pull Request

## 📄 许可证

本项目采用 MIT 许可证，详见 [LICENSE](LICENSE) 文件。

---

**注意**：这是一个学习和演示项目，在生产环境中使用前请确保进行适当的安全配置和测试。

## 🙏 致谢

感谢以下开源项目和社区的支持：

- ASP.NET Core 团队
- Serilog 社区
- JWT.io
- Bootstrap 团队

---

*最后更新：2024年12月*