# BeautyNetWebApi

**Repository Path**: leafCore/beauty-net-web-api

## Basic Information

- **Project Name**: BeautyNetWebApi
- **Description**: Beauty.Net 是一个基于.Net8的扩张服务API项目，在这儿你可以看到RabbitMQ、Kafka、Redis、FreeSql、Elasticsearch、rpc服务等多种二次封装，以极简和详实的代码助力小白工程师完成快速的服务搭建和整体规划
- **Primary Language**: C#
- **License**: Not specified
- **Default Branch**: develop
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 17
- **Forks**: 1
- **Created**: 2025-11-04
- **Last Updated**: 2026-02-04

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Beauty.NetWebApi

## 项目概述

Beauty.NetWebApi是一个功能完备的.NET微服务框架，基于.NET 8构建，旨在为开发人员提供一个集成了多种常用服务组件的快速开发平台。该项目专注于简化微服务架构中的常见挑战，通过对多种主流技术的二次封装，以极简和详实的代码助力工程师完成快速的服务搭建和整体规划。

### 主要价值

- **组件化设计**：将各种微服务组件（如缓存、消息队列、服务发现等）封装为独立模块，便于单独使用或组合使用
- **统一的API设计**：提供一致的接口和使用方式，降低学习和使用成本
- **可扩展性**：每个模块都支持多种实现和灵活配置，满足不同场景的需求
- **开箱即用**：集成了完整的示例控制器和配置，可快速上手和测试
- **标准化实现**：遵循.NET最佳实践和设计模式，确保代码质量和可维护性

本项目适用于需要构建微服务架构的企业应用、云原生应用以及任何需要集成多种服务组件的.NET Web API项目。

## 系统架构

### 技术栈

- **开发框架**：.NET 8
- **Web API**：ASP.NET Core 8.0
- **缓存**：内存缓存、Redis
- **消息队列**：RabbitMQ、Kafka
- **搜索引擎**：Elasticsearch
- **服务发现**：Consul
- **API网关**：Ocelot
- **日志中间件**：自定义全局日志中间件
- **响应包装**：统一API响应格式

### 架构设计

Beauty.NetWebApi采用了模块化的微服务架构设计，各个组件通过接口抽象实现解耦，可以根据实际需求灵活组合使用。整体架构分为以下几个层次：

#### 1. 基础层（Core）

每个功能模块都包含一个Core目录，定义了核心接口和抽象类，确保不同实现之间的一致性和可替换性。

#### 2. 实现层

提供了各接口的具体实现，如内存缓存实现、Redis缓存实现、各种消息队列模式的实现等。

#### 3. 集成层

Beauty.Net.Integration模块负责协调各个组件之间的交互，特别是Consul服务发现和Ocelot API网关的集成。

#### 4. 中间件层

Beauty.Net.Middleware提供了全局日志记录、统一响应包装等中间件，用于处理横切关注点。

#### 5. 应用层

主项目Beauty.NetWebApi提供了演示控制器和示例代码，展示如何使用各个功能模块。

### 数据流设计

- **请求流**：外部请求 → Ocelot网关 → 微服务 → 控制器 → 业务逻辑 → 数据访问
- **消息流**：生产者 → 消息队列（RabbitMQ/Kafka）→ 消费者 → 业务处理
- **缓存流**：数据访问 → 缓存服务 → 内存缓存/Redis
- **服务注册与发现**：服务启动 → 注册到Consul → 其他服务通过Consul发现服务

## 组件模块说明

### 项目结构概览

```
Beauty.NetWebApi/
├── Beauty.Net.Cache/                # 缓存模块
├── Beauty.Net.Consul/               # 服务发现模块
├── Beauty.Net.Elasticsearch/        # 搜索引擎模块
├── Beauty.Net.Integration/          # 集成扩展模块
├── Beauty.Net.JsonWebToken/         # JWT身份验证模块
├── Beauty.Net.Kafka/                # Kafka消息队列模块
├── Beauty.Net.Middleware/           # 中间件模块
├── Beauty.Net.Ocelot/               # API网关模块
├── Beauty.Net.RabbitMQ/             # RabbitMQ消息队列模块
├── Beauty.Net.MongoDB/              # MongoDB数据访问模块
└── Beauty.NetWebApi/                # 主项目
```

### 1. Beauty.Net.Cache - 缓存模块

**功能概述**：提供统一的缓存访问接口，支持内存缓存和Redis缓存实现。

**主要特性**：
- 统一的`ICacheService`接口设计
- 支持对象序列化和反序列化
- 支持缓存过期时间设置
- 批量操作支持（获取多个缓存、删除多个缓存）
- 支持缓存键前缀配置

**实现类**：
- `MemoryCacheService`：基于内存的缓存实现
- `RedisCacheService`：基于Redis的分布式缓存实现

### 2. Beauty.Net.Consul - 服务发现模块

**功能概述**：提供服务注册、健康检查和服务发现功能，便于微服务架构中的服务治理。

**主要特性**：
- 自动服务注册
- 健康检查机制
- 服务发现能力
- 配置中心功能支持
- 多数据中心支持

**核心组件**：
- `ConsulDiscoveryService`：服务发现实现
- `ConsulHostedService`：服务注册与健康检查托管服务
- `ConsulOptions`：配置选项

### 3. Beauty.Net.Elasticsearch - 搜索引擎模块

**功能概述**：封装Elasticsearch客户端，提供简化的索引管理、文档操作和搜索功能。

**主要特性**：
- 文档索引与管理
- 支持多种查询类型
- 支持聚合操作
- 批量操作支持
- 索引生命周期管理

**核心接口**：
- `IElasticsearchService`：定义Elasticsearch操作接口
- `ElasticsearchConfig`：配置选项

### 4. Beauty.Net.Kafka - Kafka消息队列模块

**功能概述**：封装Kafka生产者和消费者，提供简单易用的消息发送和接收功能。

**主要特性**：
- 消息生产与消费
- 支持消息键值对
- 支持自定义头部信息
- 批量消息处理
- 消费者组管理

**核心接口**：
- `IKafkaProducer`：消息生产者接口
- `IKafkaConsumer`：消息消费者接口
- `IKafkaMessage`：消息模型接口

### 5. Beauty.Net.RabbitMQ - RabbitMQ消息队列模块

**功能概述**：提供多种RabbitMQ消息模式的实现，支持不同的消息传递需求。

**支持的消息模式**：
- 简单队列（Simple Queue）
- 工作队列（Work Queue）
- 发布/订阅（Publish/Subscribe）

### 6. Beauty.Net.MongoDB - MongoDB数据访问模块

**功能概述**：封装MongoDB数据库访问操作，提供统一、简洁的数据访问接口，支持文档的增删改查、索引管理等功能。

**主要特性**：
- 简化的数据库连接管理
- 支持同步和异步操作
- 类型安全的文档操作
- 灵活的集合和数据库选择
- 支持连接超时和SSL配置

**核心接口与类**：
- `IMongoDBService`：MongoDB服务核心接口，定义了数据库访问的主要方法
- `MongoDBService`：IMongoDBService接口的具体实现
- `MongoDBOptions`：配置选项类，包含连接字符串、数据库名称、连接超时等设置
- 路由模式（Routing）
- 主题模式（Topic）
- 头部交换（Headers）

**核心接口**：
- `IRabbitMQProducer`：生产者基础接口
- `IRabbitMQConsumer`：消费者基础接口

### 5.1. Beauty.Net.JsonWebToken - JWT身份验证模块

**功能概述**：一个功能完整、易于使用的基于.NET 8的JWT (JSON Web Token) 身份验证库，提供全面的令牌管理功能。

**主要特性**：
- 访问令牌创建与验证
- 刷新令牌生成与管理
- 自定义声明支持
- 令牌过期检查
- 与ASP.NET Core无缝集成的依赖注入扩展

**核心接口与类**：
- `IJwtService`：JWT服务接口，定义令牌操作方法
- `JwtOptions`：JWT配置选项，包含密钥、颁发者等配置
- `TokenClaims`：令牌声明模型，用于存储和管理令牌中的声明信息
- `JwtServiceCollectionExtensions`：提供三种不同的服务注册方式

### 6. Beauty.Net.Middleware - 中间件模块

**功能概述**：提供全局日志记录、统一API响应包装等中间件功能。

**主要中间件**：
- `GlobalLoggingMiddleware`：全局请求日志记录
- `ResponseWrapperMiddleware`：统一API响应格式包装

**日志存储支持**：
- 控制台日志
- MySQL日志存储
- Elasticsearch日志存储
- MongoDB日志存储

### 7. Beauty.Net.Ocelot - API网关模块

**功能概述**：基于Ocelot构建的API网关，提供路由、负载均衡、限流等功能。

**主要特性**：
- 路由转发
- 负载均衡
- 限流保护
- 路由配置管理
- 服务发现集成

**核心组件**：
- `IOcelotConfigurationManager`：配置管理接口
- `OcelotOptions`：配置选项

### 8. Beauty.Net.Integration - 集成扩展模块

**功能概述**：提供各个模块之间的集成功能，特别是服务发现和API网关的无缝集成。

**主要功能**：
- Consul和Ocelot的配置同步
- 微服务架构的整体配置
- 路由规则的统一管理

**核心扩展**：
- `ServiceDiscoveryAndGatewayExtensions`：服务发现和网关集成扩展

## 快速开始

### 环境要求

- **开发环境**：
  - .NET 8.0 SDK 或更高版本
  - Visual Studio 2022 或更高版本（推荐）
  - Git

- **运行环境**：
  - .NET 8.0 Runtime 或更高版本
  - Docker（推荐，用于运行依赖服务）

- **依赖服务**：
  - Redis（用于缓存服务）
  - RabbitMQ（用于消息队列）
  - Kafka（用于消息队列）
  - Elasticsearch（用于搜索引擎）
  - Consul（用于服务发现）

### 安装步骤

1. **克隆项目**
   ```bash
   git clone https://gitee.com/leafCore/beauty-net-web-api.git
   cd Beauty.NetWebApi
   ```

2. **还原NuGet包**
   ```bash
   dotnet restore
   ```

3. **构建项目**
   ```bash
   dotnet build
   ```

### 基本配置

1. **配置文件设置**
   项目使用 `appsettings.json` 和 `appsettings.{Environment}.json` 进行配置。主要配置项包括：

   ```json
   {
     "Logging": {
       "LogLevel": {
         "Default": "Information",
         "Microsoft.AspNetCore": "Warning"
       }
     },
     "AllowedHosts": "*",
     "RabbitMQ": {
       "HostName": "localhost",
       "Port": 5672,
       "UserName": "guest",
       "Password": "guest"
     },
     "Kafka": {
       "BootstrapServers": "localhost:9092",
       "GroupId": "beauty-net-consumer"
     },
     "Consul": {
       "Address": "http://localhost:8500",
       "ServiceName": "Beauty.Net.WebApi",
       "HealthCheckPath": "/health",
       "HealthCheckIntervalInSeconds": 10,
       "DeregisterCriticalServiceAfterInSeconds": 60
     }
   }
   ```

2. **Docker环境配置**
   推荐使用Docker Compose启动所有依赖服务：

   ```yaml
   version: '3'
   services:
     redis:
       image: redis:latest
       ports:
         - "6379:6379"
     rabbitmq:
       image: rabbitmq:management
       ports:
         - "5672:5672"
         - "15672:15672"
     kafka:
       image: confluentinc/cp-kafka:latest
       ports:
         - "9092:9092"
     elasticsearch:
       image: elasticsearch:7.17.0
       ports:
         - "9200:9200"
       environment:
         - discovery.type=single-node
     consul:
       image: consul:latest
       ports:
         - "8500:8500"
   ```

3. **运行项目**
   ```bash
   # 开发环境运行
   dotnet run --project Beauty.NetWebApi

   # 生产环境运行
   dotnet run --project Beauty.NetWebApi --environment Production
   ```

   或者在Visual Studio中设置 `Beauty.NetWebApi` 为启动项目并按下F5运行。

### 健康检查

项目启动后，可以通过以下地址访问健康检查端点：

```
http://localhost:5000/health
```

此端点返回项目和依赖服务的健康状态信息。

## 使用示例

以下是各个功能模块的使用示例，展示如何在实际项目中集成和使用这些模块。

### 1. 缓存服务（Cache）

#### 注册缓存服务

```csharp
// 在 Program.cs 中注册缓存服务
var builder = WebApplication.CreateBuilder(args);

// 使用内存缓存
builder.Services.AddMemoryCache();
builder.Services.AddSingleton<ICacheService, MemoryCacheService>();

// 或使用Redis缓存（需配置Redis连接）
// builder.Services.AddSingleton<ICacheService, RedisCacheService>();
```

#### 使用缓存服务

```csharp
// 在控制器或服务中注入并使用缓存
public class ProductController : ControllerBase
{
    private readonly ICacheService _cacheService;
    
    public ProductController(ICacheService cacheService)
    {
        _cacheService = cacheService;
    }
    
    [HttpGet("{id}")]
    public async Task<ActionResult<Product>> GetProduct(int id)
    {
        // 定义缓存键
        var cacheKey = $"product:{id}";
        
        // 尝试从缓存获取
        var product = await _cacheService.GetAsync<Product>(cacheKey);
        if (product != null)
        {
            return Ok(product);
        }
        
        // 缓存未命中，从数据库获取
        product = await _repository.GetProductByIdAsync(id);
        if (product == null)
        {
            return NotFound();
        }
        
        // 存入缓存，设置过期时间为10分钟
        await _cacheService.SetAsync(cacheKey, product, TimeSpan.FromMinutes(10));
        
        return Ok(product);
    }
    
    [HttpDelete("{id}/cache")]
    public async Task<IActionResult> ClearProductCache(int id)
    {
        // 删除缓存
        await _cacheService.RemoveAsync($"product:{id}");
        return Ok("缓存已清除");
    }
}
```

### 2. Kafka消息队列

#### 注册Kafka服务

```csharp
// 在 Program.cs 中注册Kafka服务
var builder = WebApplication.CreateBuilder(args);

// 配置Kafka服务
builder.Services.Configure<KafkaOptions>(builder.Configuration.GetSection("Kafka"));
builder.Services.AddSingleton<IKafkaProducer, KafkaProducer>();
builder.Services.AddHostedService<KafkaConsumerBackgroundService>();
```

#### 发送Kafka消息

```csharp
public class NotificationController : ControllerBase
{
    private readonly IKafkaProducer _kafkaProducer;
    
    public NotificationController(IKafkaProducer kafkaProducer)
    {
        _kafkaProducer = kafkaProducer;
    }
    
    [HttpPost]
    public async Task<IActionResult> SendNotification([FromBody] NotificationRequest request)
    {
        // 创建消息对象
        var message = new KafkaMessage
        {
            Topic = "notifications",
            Key = request.UserId.ToString(),
            Value = JsonSerializer.Serialize(request),
            Headers = new Dictionary<string, string> { { "MessageType", "Notification" } }
        };
        
        // 发送消息
        await _kafkaProducer.ProduceAsync(message);
        return Ok("消息已发送到Kafka");
    }
    
    [HttpPost("batch")]
    public async Task<IActionResult> SendBatchNotifications([FromBody] List<NotificationRequest> requests)
    {
        // 批量发送消息
        var messages = requests.Select(request => new KafkaMessage
        {
            Topic = "notifications",
            Key = request.UserId.ToString(),
            Value = JsonSerializer.Serialize(request)
        }).ToList();
        
        await _kafkaProducer.ProduceBatchAsync(messages);
        return Ok($"已批量发送{messages.Count}条消息");
    }
}
```

#### 消费Kafka消息

```csharp
public class NotificationConsumerService : BackgroundService
{
    private readonly IKafkaConsumer _consumer;
    private readonly ILogger<NotificationConsumerService> _logger;
    
    public NotificationConsumerService(IKafkaConsumer consumer, ILogger<NotificationConsumerService> logger)
    {
        _consumer = consumer;
        _logger = logger;
    }
    
    protected override async Task ExecuteAsync(CancellationToken stoppingToken)
    {
        // 订阅主题
        await _consumer.SubscribeAsync("notifications", async (message) =>
        {
            try
            {
                // 处理消息
                var notification = JsonSerializer.Deserialize<NotificationRequest>(message.Value);
                _logger.LogInformation("接收到通知: {Title}", notification.Title);
                
                // 执行通知逻辑...
                await ProcessNotificationAsync(notification);
                
                // 确认消息处理完成
                return true;
            }
            catch (Exception ex)
            {
                _logger.LogError(ex, "处理通知失败");
                return false; // 返回false表示处理失败
            }
        }, stoppingToken);
    }
    
    private async Task ProcessNotificationAsync(NotificationRequest notification)
    {
        // 实现通知处理逻辑
        await Task.Delay(100); // 模拟异步操作
    }
}
```

### 3. RabbitMQ消息队列

#### 注册RabbitMQ服务

```csharp
// 在 Program.cs 中注册RabbitMQ服务
var builder = WebApplication.CreateBuilder(args);

// 配置RabbitMQ服务
builder.Services.Configure<RabbitMQOptions>(builder.Configuration.GetSection("RabbitMQ"));
builder.Services.AddSingleton<IRabbitMQConnectionFactory, RabbitMQConnectionFactory>();
builder.Services.AddSingleton<ISimpleQueueProducer, SimpleQueueProducer>();
builder.Services.AddSingleton<IPublishSubscribeProducer, PublishSubscribeProducer>();
builder.Services.AddHostedService<SimpleQueueConsumerService>();
```

#### 使用简单队列模式

```csharp
public class TaskController : ControllerBase
{
    private readonly ISimpleQueueProducer _queueProducer;
    
    public TaskController(ISimpleQueueProducer queueProducer)
    {
        _queueProducer = queueProducer;
    }
    
    [HttpPost]
    public async Task<IActionResult> CreateTask([FromBody] TaskRequest request)
    {
        // 发送任务到队列
        await _queueProducer.ProduceAsync("tasks_queue", JsonSerializer.Serialize(request));
        return Accepted("任务已创建并加入队列");
    }
}

// 消费者服务
public class TaskProcessingService : BackgroundService
{
    private readonly IRabbitMQConsumer _consumer;
    private readonly ILogger<TaskProcessingService> _logger;
    
    public TaskProcessingService(IRabbitMQConsumer consumer, ILogger<TaskProcessingService> logger)
    {
        _consumer = consumer;
        _logger = logger;
    }
    
    protected override async Task ExecuteAsync(CancellationToken stoppingToken)
    {
        // 消费队列中的任务
        await _consumer.ConsumeAsync("tasks_queue", async (message) =>
        {
            try
            {
                var task = JsonSerializer.Deserialize<TaskRequest>(message);
                _logger.LogInformation("开始处理任务: {TaskId}", task.TaskId);
                
                // 执行任务处理逻辑
                await ProcessTaskAsync(task);
                
                return true; // 确认消息
            }
            catch (Exception ex)
            {
                _logger.LogError(ex, "任务处理失败");
                return false;
            }
        }, stoppingToken);
    }
    
    private async Task ProcessTaskAsync(TaskRequest task)
    {
        // 实现任务处理逻辑
        await Task.Delay(2000); // 模拟长时间运行的任务
    }
}
```

#### 使用发布/订阅模式

```csharp
public class EventController : ControllerBase
{
    private readonly IPublishSubscribeProducer _pubSubProducer;
    
    public EventController(IPublishSubscribeProducer pubSubProducer)
    {
        _pubSubProducer = pubSubProducer;
    }
    
    [HttpPost]
    public async Task<IActionResult> PublishEvent([FromBody] EventRequest request)
    {
        // 发布事件到交换机
        await _pubSubProducer.PublishAsync("events_exchange", request.EventType, JsonSerializer.Serialize(request));
        return Ok("事件已发布");
    }
}

// 订阅者服务
public class EventSubscriberService : BackgroundService
{
    private readonly IRabbitMQConsumer _consumer;
    private readonly ILogger<EventSubscriberService> _logger;
    
    public EventSubscriberService(IRabbitMQConsumer consumer, ILogger<EventSubscriberService> logger)
    {
        _consumer = consumer;
        _logger = logger;
    }
    
    protected override async Task ExecuteAsync(CancellationToken stoppingToken)
    {
        // 订阅特定类型的事件
        await _consumer.SubscribeAsync("events_exchange", "user.*", async (message) =>
        {
            try
            {
                var @event = JsonSerializer.Deserialize<EventRequest>(message);
                _logger.LogInformation("收到事件: {EventType}", @event.EventType);
                
                // 处理事件
                await ProcessEventAsync(@event);
                
                return true;
            }
            catch (Exception ex)
            {
                _logger.LogError(ex, "事件处理失败");
                return false;
            }
        }, stoppingToken);
    }
    
    private async Task ProcessEventAsync(EventRequest @event)
    {
        // 实现事件处理逻辑
        await Task.Delay(100);
    }
}
```

### 4. Elasticsearch搜索

#### 注册Elasticsearch服务

```csharp
// 在 Program.cs 中注册Elasticsearch服务
var builder = WebApplication.CreateBuilder(args);

builder.Services.Configure<ElasticsearchConfig>(builder.Configuration.GetSection("Elasticsearch"));
builder.Services.AddSingleton<IElasticsearchService, ElasticsearchService>();
```

#### 使用Elasticsearch进行搜索

```csharp
public class SearchController : ControllerBase
{
    private readonly IElasticsearchService _elasticsearchService;
    
    public SearchController(IElasticsearchService elasticsearchService)
    {
        _elasticsearchService = elasticsearchService;
    }
    
    [HttpPost("index")]
    public async Task<IActionResult> IndexDocument([FromBody] ProductDocument document)
    {
        // 索引文档
        await _elasticsearchService.IndexDocumentAsync("products", document.Id.ToString(), document);
        return Ok("文档已索引");
    }
    
    [HttpGet]
    public async Task<IActionResult> SearchProducts([FromQuery] string query, [FromQuery] int page = 1, [FromQuery] int size = 10)
    {
        // 构建搜索请求
        var searchRequest = new {
            query = new {
                multi_match = new {
                    query = query,
                    fields = new[] { "name^3", "description", "category" }
                }
            },
            from = (page - 1) * size,
            size = size
        };
        
        // 执行搜索
        var result = await _elasticsearchService.SearchAsync<ProductDocument>("products", JsonSerializer.Serialize(searchRequest));
        
        return Ok(new {
            total = result.Total,
            items = result.Documents,
            page = page,
            size = size
        });
    }
}
```

### 5. 服务发现与API网关集成

#### 配置服务发现与网关

```csharp
// 在 Program.cs 中配置服务发现与API网关
var builder = WebApplication.CreateBuilder(args);

// 配置Consul服务发现
builder.Services.AddConsulServiceDiscovery();

// 配置Ocelot网关
builder.Configuration.AddJsonFile("ocelot.json", optional: false, reloadOnChange: true);
builder.Services.AddOcelot(builder.Configuration);

// 集成服务发现和API网关
builder.Services.ConfigureConsulOcelotIntegration();

// 在应用程序中使用
app.UseOcelot().Wait();
```

#### 配置ocelot.json

```json
{
  "Routes": [
    {
      "DownstreamPathTemplate": "/api/products/{everything}",
      "DownstreamScheme": "http",
      "UpstreamPathTemplate": "/api/products/{everything}",
      "UpstreamHttpMethod": [ "Get", "Post", "Put", "Delete" ],
      "ServiceName": "ProductService",
      "LoadBalancerOptions": {
        "Type": "RoundRobin"
      },
      "RateLimitOptions": {
        "ClientWhitelist": [],
        "EnableRateLimiting": true,
        "Period": "1m",
        "PeriodTimespan": 1,
        "Limit": 100
      }
    },
    {
      "DownstreamPathTemplate": "/api/orders/{everything}",
      "DownstreamScheme": "http",
      "UpstreamPathTemplate": "/api/orders/{everything}",
      "UpstreamHttpMethod": [ "Get", "Post", "Put", "Delete" ],
      "ServiceName": "OrderService"
    }
  ],
  "GlobalConfiguration": {
    "ServiceDiscoveryProvider": {
      "Type": "Consul",
      "Host": "localhost",
      "Port": 8500
    },
    "BaseUrl": "https://api.beautynet.com"
  }
}```

## API文档

### Swagger API文档

项目集成了Swagger/OpenAPI，启动应用程序后，可以通过以下地址访问交互式API文档：

```
http://localhost:5000/swagger
```

Swagger文档提供了以下功能：
- 查看所有可用的API端点
- 了解每个API的请求参数和响应格式
- 直接在浏览器中测试API调用
- 下载API定义文件（支持多种格式，如JSON、YAML）

### API版本控制

项目支持API版本控制，可以通过URL路径或请求头进行版本控制。默认的API版本为v1。

**通过URL路径指定版本**：
```
http://localhost:5000/api/v1/products
http://localhost:5000/api/v2/products
```

**通过请求头指定版本**：
```
X-API-Version: 1
```

## 贡献指南

我们欢迎社区贡献！如果您想为Beauty.NetWebApi项目做出贡献，请遵循以下步骤：

### 开发流程

1. **Fork项目仓库**
   - 在GitHub上Fork原始仓库到您的账户

2. **克隆Fork后的仓库**
   ```bash
   git clone https://gitee.com/leafCore/beauty-net-web-api.git
   cd Beauty.NetWebApi
   ```

3. **创建功能分支**
   ```bash
   git checkout -b feature/your-feature-name
   ```

4. **开发和测试**
   - 编写代码
   - 确保代码符合项目的编码规范
   - 运行单元测试和集成测试

5. **提交代码**
   ```bash
   git add .
   git commit -m "描述您的变更"
   ```

6. **推送代码到远程仓库**
   ```bash
   git push origin feature/your-feature-name
   ```

7. **创建Pull Request**
   - 在GitHub上创建Pull Request
   - 描述您的变更、解决的问题和实现的功能
   - 等待代码审查

### 编码规范

- 使用C# 10.0特性
- 遵循.NET设计指南
- 使用Nullable引用类型
- 方法名使用PascalCase
- 变量和参数使用camelCase
- 类名和接口名使用PascalCase
- 接口名称以I开头
- 编写单元测试
- 添加适当的XML文档注释

### 提交规范

提交信息应清晰描述变更内容，推荐使用以下格式：

```
类型: 简短描述

详细描述（可选）

Fixes #issue-number（如果解决了特定问题）
```

提交类型包括：
- **feat**: 新功能
- **fix**: 修复bug
- **docs**: 文档更新
- **style**: 代码风格更改
- **refactor**: 代码重构
- **perf**: 性能优化
- **test**: 测试相关更改
- **build**: 构建配置更改

### 问题反馈

如果您在使用过程中发现任何问题或有功能建议，请在Giitee Issues页面提交：

```
https://gitee.com/leafCore/beauty-net-web-api/issues
```

提交问题时，请提供：
- 问题的详细描述
- 重现步骤
- 期望的行为
- 实际的行为
- 系统环境信息
- 相关的错误日志或截图

### 开发环境配置

为了确保一致性，我们建议使用以下开发环境配置：

- Visual Studio 2022 或更高版本
- .NET 8.0 SDK
- Resharper或Roslyn分析器（用于代码质量检查）
- StyleCop（用于代码风格一致性）

## 许可证

Beauty.NetWebApi 项目采用 MIT 许可证开源。详细信息请参阅 [LICENSE](https://gitee.com/leafCore/beauty-net-web-api/blob/main/LICENSE) 文件。

```
MIT License

Copyright (c) 2025 Beauty.Net

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.
```

## 联系方式

如果您有任何问题或建议，可以通过以下方式联系我们：

- **Giitee Issues**: [https://gitee.com/leafCore/beauty-net-web-api/issues](https://gitee.com/leafCore/beauty-net-web-api/issues)
- **电子邮件**: 154571895@qq.com
- **项目主页**: [https://gitee.com/leafCore/beauty-net-web-api](https://gitee.com/leafCore/beauty-net-web-api)

## 鸣谢

感谢以下开源项目和工具的支持，使Beauty.NetWebApi成为可能：

- [ASP.NET Core](https://dotnet.microsoft.com/apps/aspnet) - 用于构建Web API的基础框架
- [Redis](https://redis.io/) - 高性能键值存储
- [RabbitMQ](https://www.rabbitmq.com/) - 可靠的消息代理
- [Apache Kafka](https://kafka.apache.org/) - 分布式事件流平台
- [Elasticsearch](https://www.elastic.co/) - 搜索和分析引擎
- [Consul](https://www.consul.io/) - 服务发现和配置工具
- [Ocelot](https://github.com/ThreeMammals/Ocelot) - API网关
- [Swagger/OpenAPI](https://swagger.io/) - API文档生成工具

## 更新日志

### 1.0.0 (2025-11-01)

**功能**
- 初始版本发布
- 实现所有核心模块（缓存、消息队列、搜索引擎、服务发现、API网关等）
- 提供完整的示例控制器
- 集成Swagger文档
- 添加全局日志和响应包装中间件

## 附录

### 常见问题解答

**Q: 如何扩展现有模块？**
A: 每个模块都提供了接口抽象，您可以实现相应的接口来创建自定义实现，然后通过依赖注入注册您的实现。

**Q: 如何添加新的消息队列模式？**
A: 您可以继承相应的基类（如`BaseProducer`、`BaseConsumer`）并实现所需的方法，然后在服务注册时添加您的实现。

**Q: 如何监控和排查问题？**
A: 使用全局日志中间件记录的日志，您可以通过配置日志级别来获取更详细的信息。此外，健康检查端点提供了系统状态的实时监控。

### 性能建议

- 对于高性能场景，推荐使用Redis作为缓存实现
- 对于大量消息处理，建议调整Kafka消费者组和分区数量
- 使用连接池技术管理数据库和服务连接
- 定期清理过期缓存和日志数据

### 安全建议

- 不要在代码或配置文件中硬编码敏感信息（如密码、API密钥等）
- 使用环境变量或安全的配置管理工具存储敏感信息
- 启用HTTPS以保护API通信
- 实现适当的认证和授权机制
- 定期更新依赖库以修复安全漏洞