sharp-basic/test/NetServer.Test/README.md

NetServer.Test - 测试和示例项目

这个项目包含了 Sharp.NetServer 框架的完整测试和使用示例。

📁 项目结构

NetServer.Test/
├── UnitTests/                      # 单元测试
│   ├── RouteTableTests.cs         # 路由表测试
│   ├── MiddlewarePipelineTests.cs # 中间件管道测试
│   └── MiddlewareTests.cs         # 中间件功能测试
│
├── IntegrationTests/               # 集成测试
│   └── ServerIntegrationTests.cs  # 服务器集成测试
│
├── Examples/                       # 完整示例
│   ├── Controllers/
│   │   ├── UserController.cs      # 用户管理示例
│   │   ├── ProductController.cs   # 产品管理示例
│   │   └── AuthController.cs      # 认证示例
│   └── ExampleProgram.cs          # 示例程序入口
│
└── NetServer.Test.csproj          # 项目配置

🚀 运行测试

运行所有测试

cd test/NetServer.Test
dotnet test

运行特定测试类

dotnet test --filter "FullyQualifiedName~RouteTableTests"
dotnet test --filter "FullyQualifiedName~MiddlewarePipelineTests"
dotnet test --filter "FullyQualifiedName~ServerIntegrationTests"

🎯 运行示例程序

方式一：直接运行

cd test/NetServer.Test
dotnet run

# 或指定端口
dotnet run 8080

方式二：编译后运行

dotnet build
cd bin/Debug/net8.0
./NetServer.Test.exe       # Windows
./NetServer.Test           # Linux/Mac

📚 测试说明

1. 单元测试 (UnitTests/)

RouteTableTests.cs

测试路由系统的核心功能：

• ✅ 路由注册和发现
• ✅ 路由匹配（包括路径参数）
• ✅ 特性解析（授权、限流、缓存等）
• ✅ 无效路由处理

MiddlewarePipelineTests.cs

测试中间件管道：

• ✅ 中间件执行顺序
• ✅ 多个中间件的链式调用
• ✅ 中间件短路机制

2. 集成测试 (IntegrationTests/)

ServerIntegrationTests.cs

测试完整的服务器功能：

• ✅ HTTP GET/POST 请求处理
• ✅ 查询参数解析
• ✅ 404 错误处理
• ✅ CORS 响应头
• ✅ 并发请求处理

注意: 集成测试会启动一个真实的 HTTP 服务器，监听端口 15000。

💡 示例说明

1. 用户管理示例 (UserController.cs)

展示了完整的 CRUD 操作：

• GET /api/users - 获取所有用户（需要 Admin 角色）
• GET /api/users/{id} - 获取单个用户（带缓存）
• POST /api/users - 创建用户（需要 Admin 角色）
• PUT /api/users/{id} - 更新用户
• DELETE /api/users/{id} - 删除用户（需要 Admin 角色）
• GET /api/users/search - 搜索用户（允许匿名）

特性展示:

• 角色授权 ([Authorize(Roles = "Admin")])
• 限流保护 ([RateLimit])
• 响应缓存 ([ResponseCache])
• 允许匿名访问 ([AllowAnonymous])

2. 产品管理示例 (ProductController.cs)

展示了产品管理功能：

• GET /api/products - 获取所有产品（公开接口，带缓存和限流）
• GET /api/products/{id} - 获取产品详情（带缓存）
• POST /api/products - 创建产品（需要 Admin）
• PATCH /api/products/{id}/stock - 更新库存（需要认证）
• DELETE /api/products/{id} - 删除产品（需要 Admin）
• GET /api/products/search - 搜索产品（支持价格范围）

特性展示:

• 查询参数处理
• 部分更新 (PATCH)
• 复杂搜索条件
• 响应缓存策略

3. 认证示例 (AuthController.cs)

展示了完整的认证流程：

• POST /api/auth/login - 用户登录
• POST /api/auth/logout - 用户登出
• GET /api/auth/me - 获取当前用户信息
• POST /api/auth/change-password - 修改密码
• POST /api/auth/refresh - 刷新 Token

特性展示:

• 简单的 Token 认证实现
• Cookie 操作
• 密码验证
• 防暴力破解限流

4. 完整示例程序 (ExampleProgram.cs)

一个完整的可运行示例，包含：

• ✅ 服务器配置和启动
• ✅ CORS 配置
• ✅ 认证授权配置
• ✅ 限流和缓存配置
• ✅ 自定义中间件（请求计时）
• ✅ 日志配置
• ✅ 依赖注入

🔧 使用示例

启动服务器

cd test/NetServer.Test
dotnet run

服务器将在 http://localhost:5000/ 启动。

测试 API

1. 登录获取 Token

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

响应示例：

{
  "success": true,
  "data": {
    "token": "YWRtaW46QWRtaW46MTczNDU2Nzg5MA==",
    "username": "admin",
    "role": "Admin",
    "expiresIn": 3600
  },
  "message": "登录成功",
  "timestamp": 1734567890123
}

2. 获取所有产品（无需认证）

curl http://localhost:5000/api/products

3. 搜索用户（无需认证）

curl "http://localhost:5000/api/users/search?keyword=张"

4. 获取用户详情（需要认证）

curl http://localhost:5000/api/users/1 \
     -H "Authorization: Bearer YOUR_TOKEN_HERE"

或使用 Cookie 认证：

curl http://localhost:5000/api/users/1 \
     -b "auth_token=YOUR_TOKEN_HERE"

5. 创建产品（需要 Admin 角色）

curl -X POST http://localhost:5000/api/products \
     -H "Content-Type: application/json" \
     -H "Authorization: Bearer YOUR_TOKEN_HERE" \
     -d '{"name":"新产品","price":299,"stock":50,"category":"测试"}'

6. 更新库存（需要认证）

curl -X PATCH http://localhost:5000/api/products/1/stock \
     -H "Content-Type: application/json" \
     -H "Authorization: Bearer YOUR_TOKEN_HERE" \
     -d '{"quantity":100}'

🔑 测试账号

• 管理员: admin / admin123
• 普通用户: user / user123

📊 功能特性展示

认证授权

• ✅ 基于 Token 的认证
• ✅ Cookie 支持
• ✅ 角色验证
• ✅ 权限验证

限流

• ✅ 基于 IP 的限流
• ✅ 基于用户的限流
• ✅ 防暴力破解

缓存

• ✅ 内存响应缓存
• ✅ 基于查询参数的缓存变化

CORS

• ✅ 跨域资源共享
• ✅ 预检请求处理

日志

• ✅ 请求日志记录
• ✅ 错误日志记录
• ✅ 性能监控（慢请求警告）

🎓 学习路径

1. 初学者: 从 ExampleProgram.cs 开始，了解基本配置
2. 进阶: 查看各个 Controller，学习如何使用特性
3. 高级: 阅读单元测试和集成测试，深入理解框架原理

📝 注意事项

1. 端口占用: 确保 5000 端口未被占用，或通过参数指定其他端口
2. 管理员权限: Windows 上监听非 localhost 地址可能需要管理员权限
3. Token 安全: 示例中的 Token 实现仅用于演示，生产环境应使用 JWT
4. 数据持久化: 示例使用内存存储，重启后数据会丢失

🚧 扩展建议

基于这些示例，你可以：

• 添加数据库支持（Entity Framework Core）
• 实现真正的 JWT 认证
• 添加 Swagger/OpenAPI 文档
• 实现文件上传功能
• 添加 WebSocket 支持
• 集成分布式缓存（Redis）
• 实现更复杂的业务逻辑

📖 相关文档

• 框架 README
• 架构文档