# 外卖SaaS系统 - AI编程规范汇总

> 本文档专门为AI编程助手准备，汇总了所有编码规范和规则，确保代码质量和一致性。

## 1. 技术栈要求

### 1.1 核心技术
- **.NET 10** + **ASP.NET Core Web API**
- **Entity Framework Core 10**（复杂查询和实体管理）
- **Dapper 2.1+**（高性能查询和批量操作）
- **PostgreSQL 16+**（主数据库）
- **Redis 7.0+**（缓存和会话）
- **RabbitMQ 3.12+**（消息队列）

### 1.2 必用框架和库
- **AutoMapper**：对象映射
- **FluentValidation**：数据验证
- **Serilog**：结构化日志
- **MediatR**：CQRS和中介者模式
- **Hangfire**：后台任务调度
- **Polly**：弹性和瞬态故障处理
- **Swagger/Swashbuckle**：API文档

### 1.3 测试框架
- **xUnit**：单元测试
- **Moq**：Mock框架
- **FluentAssertions**：断言库

## 2. 命名规范（严格遵守）

### 2.1 C#命名规范
```csharp
// ✅ 类名：PascalCase
public class OrderService { }

// ✅ 接口：I + PascalCase
public interface IOrderRepository { }

// ✅ 方法：PascalCase，异步方法以Async结尾
public async Task<Order> CreateOrderAsync() { }

// ✅ 私有字段：_camelCase（下划线前缀）
private readonly IOrderRepository _orderRepository;

// ✅ 公共属性：PascalCase
public string OrderNo { get; set; }

// ✅ 局部变量：camelCase
var orderTotal = 100.00m;

// ✅ 常量：PascalCase
public const int MaxOrderItems = 50;

// ✅ 枚举：PascalCase，枚举值也是PascalCase
public enum OrderStatus
{
    Pending = 1,
    Confirmed = 2,
    Completed = 3
}
```

### 2.2 数据库命名规范
```sql
-- ✅ 表名：小写，下划线分隔，复数形式
orders
order_items
merchant_stores

-- ✅ 字段名：小写，下划线分隔
order_no
created_at
total_amount

-- ✅ 索引：idx_表名_字段名
idx_orders_merchant_id
idx_orders_created_at

-- ✅ 外键：fk_表名_引用表名
fk_orders_merchants
```

## 3. 项目结构规范

### 3.1 分层架构（DDD + Clean Architecture）
```
TakeoutSaaS/
├── src/
│   ├── Api/                          # API层（表现层）
│   │   ├── Controllers/              # 控制器
│   │   ├── Filters/                  # 过滤器
│   │   ├── Middleware/               # 中间件
│   │   └── Models/                   # DTO模型
│   ├── Application/                  # 应用层
│   │   ├── Services/                 # 应用服务
│   │   ├── DTOs/                     # 数据传输对象
│   │   ├── Interfaces/               # 服务接口
│   │   ├── Validators/               # FluentValidation验证器
│   │   ├── Mappings/                 # AutoMapper配置
│   │   └── Commands/Queries/         # CQRS命令和查询
│   ├── Domain/                       # 领域层（核心业务）
│   │   ├── Entities/                 # 实体
│   │   ├── ValueObjects/             # 值对象
│   │   ├── Enums/                    # 枚举
│   │   ├── Events/                   # 领域事件
│   │   └── Interfaces/               # 仓储接口
│   ├── Infrastructure/               # 基础设施层
│   │   ├── Data/                     # 数据访问
│   │   │   ├── EFCore/              # EF Core实现
│   │   │   ├── Dapper/              # Dapper实现
│   │   │   └── Repositories/        # 仓储实现
│   │   ├── Cache/                    # 缓存实现
│   │   ├── MessageQueue/             # 消息队列
│   │   └── ExternalServices/         # 外部服务
│   ├── Core/                         # 核心共享层
│   │   ├── Constants/                # 常量
│   │   ├── Exceptions/               # 异常
│   │   ├── Extensions/               # 扩展方法
│   │   └── Results/                  # 统一返回结果
│   └── Modules/                      # 模块化（可选）
└── tests/
    ├── UnitTests/                    # 单元测试
    ├── IntegrationTests/             # 集成测试
    └── PerformanceTests/             # 性能测试
```

### 3.2 文件组织规则
- 每个文件只包含一个公共类/接口
- 文件名与类名保持一致
- 相关的类放在同一个文件夹
- 使用命名空间反映文件夹结构

## 4. 代码注释规范

### 4.1 XML文档注释（必须）
```csharp
/// <summary>
/// 订单服务接口
/// </summary>
public interface IOrderService
{
    /// <summary>
    /// 创建订单
    /// </summary>
    /// <param name="request">订单创建请求</param>
    /// <returns>订单信息</returns>
    /// <exception cref="BusinessException">业务异常</exception>
    Task<OrderDto> CreateOrderAsync(CreateOrderRequest request);
}
```

### 4.2 业务逻辑注释
```csharp
// ✅ 复杂业务逻辑必须添加注释
public async Task<decimal> CalculateOrderAmount(Order order)
{
    // 1. 计算菜品总金额
    var dishAmount = order.Items.Sum(x => x.Price * x.Quantity);

    // 2. 计算配送费（距离 > 3km，每公里加收2元）
    var deliveryFee = CalculateDeliveryFee(order.Distance);

    // 3. 应用优惠券折扣
    var discount = await ApplyCouponDiscountAsync(order.CouponId, dishAmount);

    // 4. 计算最终金额
    return dishAmount + deliveryFee - discount;
}
```

## 5. 异常处理规范

### 5.1 自定义异常
```csharp
// ✅ 业务异常
public class BusinessException : Exception
{
    public int ErrorCode { get; }

    public BusinessException(int errorCode, string message)
        : base(message)
    {
        ErrorCode = errorCode;
    }
}

// ✅ 验证异常
public class ValidationException : Exception
{
    public IDictionary<string, string[]> Errors { get; }

    public ValidationException(IDictionary<string, string[]> errors)
        : base("一个或多个验证错误")
    {
        Errors = errors;
    }
}
```

### 5.2 全局异常处理中间件（必须实现）
```csharp
public class ExceptionHandlingMiddleware
{
    private readonly RequestDelegate _next;
    private readonly ILogger<ExceptionHandlingMiddleware> _logger;

    public async Task InvokeAsync(HttpContext context)
    {
        try
        {
            await _next(context);
        }
        catch (BusinessException ex)
        {
            _logger.LogWarning(ex, "业务异常：{Message}", ex.Message);
            await HandleBusinessExceptionAsync(context, ex);
        }
        catch (ValidationException ex)
        {
            _logger.LogWarning(ex, "验证异常：{Errors}", ex.Errors);
            await HandleValidationExceptionAsync(context, ex);
        }
        catch (Exception ex)
        {
            _logger.LogError(ex, "系统异常：{Message}", ex.Message);
            await HandleSystemExceptionAsync(context, ex);
        }
    }

    private static Task HandleBusinessExceptionAsync(HttpContext context, BusinessException ex)
    {
        context.Response.StatusCode = StatusCodes.Status422UnprocessableEntity;
        return context.Response.WriteAsJsonAsync(new
        {
            success = false,
            code = ex.ErrorCode,
            message = ex.Message
        });
    }
}
```

### 5.3 异常使用示例
```csharp
// ✅ 正确的异常抛出
public async Task<Order> GetOrderAsync(Guid orderId)
{
    var order = await _orderRepository.GetByIdAsync(orderId);
    if (order == null)
    {
        throw new BusinessException(404, "订单不存在");
    }
    return order;
}

// ❌ 错误：不要吞掉异常
try
{
    // ...
}
catch (Exception)
{
    // 什么都不做 - 这是错误的！
}
```

## 6. 服务层编码规范

### 6.1 服务类结构（标准模板）
```csharp
// ✅ 好的服务实现
public class OrderService : IOrderService
{
    private readonly IOrderRepository _orderRepository;
    private readonly IUnitOfWork _unitOfWork;
    private readonly ILogger<OrderService> _logger;
    private readonly IMapper _mapper;
    private readonly IOptions<OrderSettings> _settings;

    public OrderService(
        IOrderRepository orderRepository,
        IUnitOfWork unitOfWork,
        ILogger<OrderService> logger,
        IMapper mapper,
        IOptions<OrderSettings> settings)
    {
        _orderRepository = orderRepository;
        _unitOfWork = unitOfWork;
        _logger = logger;
        _mapper = mapper;
        _settings = settings;
    }

    public async Task<OrderDto> CreateOrderAsync(CreateOrderRequest request)
    {
        try
        {
            // 1. 参数验证（FluentValidation会自动验证，这里是额外检查）
            if (request == null)
                throw new ArgumentNullException(nameof(request));

            // 2. 记录日志
            _logger.LogInformation("创建订单：{@Request}", request);

            // 3. 业务逻辑
            var order = new Order
            {
                OrderNo = GenerateOrderNo(),
                TotalAmount = request.TotalAmount,
                DeliveryFee = _settings.Value.DefaultDeliveryFee,
                CreatedAt = DateTime.UtcNow
            };

            // 4. 数据持久化
            await _orderRepository.AddAsync(order);
            await _unitOfWork.SaveChangesAsync();

            // 5. 记录成功日志
            _logger.LogInformation("订单创建成功：{OrderId}", order.Id);

            // 6. 返回DTO
            return _mapper.Map<OrderDto>(order);
        }
        catch (Exception ex)
        {
            _logger.LogError(ex, "创建订单失败：{@Request}", request);
            throw;
        }
    }
}

// ❌ 错误的服务实现
public class BadOrderService
{
    // ❌ 直接注入DbContext而不是仓储
    private readonly AppDbContext _dbContext;

    // ❌ 没有日志
    // ❌ 硬编码配置
    public Order CreateOrder(CreateOrderRequest request)
    {
        var order = new Order();
        order.DeliveryFee = 5.0m; // ❌ 硬编码
        _dbContext.Orders.Add(order);
        _dbContext.SaveChanges(); // ❌ 同步方法
        return order; // ❌ 返回实体而不是DTO
    }
}
```

### 6.2 依赖注入规则
```csharp
// ✅ 使用构造函数注入
public class OrderService
{
    private readonly IOrderRepository _orderRepository;

    public OrderService(IOrderRepository orderRepository)
    {
        _orderRepository = orderRepository;
    }
}

// ❌ 不要使用属性注入
public class BadOrderService
{
    [Inject]
    public IOrderRepository OrderRepository { get; set; }
}

// ❌ 不要使用服务定位器模式
public class BadOrderService
{
    public void DoSomething()
    {
        var repository = ServiceLocator.GetService<IOrderRepository>();
    }
}
```

## 7. 数据访问规范

### 7.1 仓储模式（必须使用）
```csharp
// ✅ 仓储接口
public interface IOrderRepository
{
    Task<Order> GetByIdAsync(Guid id);
    Task<IEnumerable<Order>> GetAllAsync();
    Task<Order> AddAsync(Order order);
    Task UpdateAsync(Order order);
    Task DeleteAsync(Guid id);
    Task<bool> ExistsAsync(Guid id);
}

// ✅ EF Core仓储实现
public class OrderRepository : IOrderRepository
{
    private readonly AppDbContext _context;

    public OrderRepository(AppDbContext context)
    {
        _context = context;
    }

    public async Task<Order> GetByIdAsync(Guid id)
    {
        return await _context.Orders
            .Include(o => o.OrderItems)
            .Include(o => o.Customer)
            .FirstOrDefaultAsync(o => o.Id == id);
    }

    public async Task<Order> AddAsync(Order order)
    {
        await _context.Orders.AddAsync(order);
        return order;
    }
}
```

### 7.2 EF Core vs Dapper 使用场景
```csharp
// ✅ EF Core - 复杂查询和实体管理
public async Task<Order> GetOrderWithDetailsAsync(Guid orderId)
{
    return await _dbContext.Orders
        .Include(o => o.OrderItems)
            .ThenInclude(oi => oi.Dish)
        .Include(o => o.Customer)
        .Include(o => o.Merchant)
        .FirstOrDefaultAsync(o => o.Id == orderId);
}

// ✅ Dapper - 高性能统计查询
public async Task<OrderStatistics> GetOrderStatisticsAsync(DateTime startDate, DateTime endDate)
{
    var sql = @"
        SELECT
            COUNT(*) as TotalOrders,
            SUM(total_amount) as TotalAmount,
            AVG(total_amount) as AvgAmount,
            MAX(total_amount) as MaxAmount,
            MIN(total_amount) as MinAmount
        FROM orders
        WHERE created_at BETWEEN @StartDate AND @EndDate
            AND status = @Status";

    return await _connection.QueryFirstOrDefaultAsync<OrderStatistics>(sql,
        new { StartDate = startDate, EndDate = endDate, Status = OrderStatus.Completed });
}

// ✅ Dapper - 批量插入
public async Task<int> BulkInsertOrdersAsync(IEnumerable<Order> orders)
{
    var sql = @"
        INSERT INTO orders (id, order_no, merchant_id, total_amount, created_at)
        VALUES (@Id, @OrderNo, @MerchantId, @TotalAmount, @CreatedAt)";

    return await _connection.ExecuteAsync(sql, orders);
}
```

### 7.3 工作单元模式（必须使用）
```csharp
// ✅ 工作单元接口
public interface IUnitOfWork : IDisposable
{
    Task<int> SaveChangesAsync(CancellationToken cancellationToken = default);
    Task BeginTransactionAsync();
    Task CommitTransactionAsync();
    Task RollbackTransactionAsync();
}

// ✅ 使用工作单元
public async Task<OrderDto> CreateOrderWithItemsAsync(CreateOrderRequest request)
{
    await _unitOfWork.BeginTransactionAsync();

    try
    {
        // 1. 创建订单
        var order = new Order { /* ... */ };
        await _orderRepository.AddAsync(order);

        // 2. 创建订单项
        foreach (var item in request.Items)
        {
            var orderItem = new OrderItem { /* ... */ };
            await _orderItemRepository.AddAsync(orderItem);
        }

        // 3. 提交事务
        await _unitOfWork.SaveChangesAsync();
        await _unitOfWork.CommitTransactionAsync();

        return _mapper.Map<OrderDto>(order);
    }
    catch
    {
        await _unitOfWork.RollbackTransactionAsync();
        throw;
    }
}
```

## 8. CQRS模式规范

### 8.1 命令（Command）- 写操作
```csharp
// ✅ 命令定义
public class CreateOrderCommand : IRequest<OrderDto>
{
    public Guid MerchantId { get; set; }
    public Guid CustomerId { get; set; }
    public List<OrderItemDto> Items { get; set; }
    public decimal TotalAmount { get; set; }
}

// ✅ 命令处理器
public class CreateOrderCommandHandler : IRequestHandler<CreateOrderCommand, OrderDto>
{
    private readonly IOrderRepository _orderRepository;
    private readonly IUnitOfWork _unitOfWork;
    private readonly ILogger<CreateOrderCommandHandler> _logger;

    public async Task<OrderDto> Handle(CreateOrderCommand request, CancellationToken cancellationToken)
    {
        _logger.LogInformation("处理创建订单命令：{@Command}", request);

        var order = new Order
        {
            MerchantId = request.MerchantId,
            CustomerId = request.CustomerId,
            TotalAmount = request.TotalAmount
        };

        await _orderRepository.AddAsync(order);
        await _unitOfWork.SaveChangesAsync(cancellationToken);

        return _mapper.Map<OrderDto>(order);
    }
}
```

### 8.2 查询（Query）- 读操作
```csharp
// ✅ 查询定义
public class GetOrderByIdQuery : IRequest<OrderDto>
{
    public Guid OrderId { get; set; }
}

// ✅ 查询处理器
public class GetOrderByIdQueryHandler : IRequestHandler<GetOrderByIdQuery, OrderDto>
{
    private readonly IOrderRepository _orderRepository;
    private readonly IMapper _mapper;

    public async Task<OrderDto> Handle(GetOrderByIdQuery request, CancellationToken cancellationToken)
    {
        var order = await _orderRepository.GetByIdAsync(request.OrderId);

        if (order == null)
            throw new BusinessException(404, "订单不存在");

        return _mapper.Map<OrderDto>(order);
    }
}
```

## 9. 验证规范（FluentValidation）

### 9.1 验证器定义
```csharp
// ✅ 使用FluentValidation
public class CreateOrderRequestValidator : AbstractValidator<CreateOrderRequest>
{
    public CreateOrderRequestValidator()
    {
        RuleFor(x => x.MerchantId)
            .NotEmpty().WithMessage("商家ID不能为空");

        RuleFor(x => x.CustomerId)
            .NotEmpty().WithMessage("客户ID不能为空");

        RuleFor(x => x.Items)
            .NotEmpty().WithMessage("订单项不能为空")
            .Must(items => items.Count <= 50).WithMessage("订单项不能超过50个");

        RuleFor(x => x.TotalAmount)
            .GreaterThan(0).WithMessage("订单金额必须大于0");

        RuleFor(x => x.DeliveryAddress)
            .NotEmpty().WithMessage("配送地址不能为空")
            .MaximumLength(200).WithMessage("配送地址不能超过200个字符");
    }
}
```

### 9.2 验证器注册
```csharp
// ✅ 在Program.cs中注册
builder.Services.AddValidatorsFromAssemblyContaining<CreateOrderRequestValidator>();
builder.Services.AddFluentValidationAutoValidation();
```

## 10. 缓存策略规范


### 10.1 缓存时间策略
```csharp
// ✅ 缓存时间常量
public static class CacheTimeouts
{
    public static readonly TimeSpan MerchantInfo = TimeSpan.FromMinutes(30);
    public static readonly TimeSpan DishInfo = TimeSpan.FromMinutes(15);
    public static readonly TimeSpan UserSession = TimeSpan.FromHours(2);
    public static readonly TimeSpan ConfigInfo = TimeSpan.FromHours(1);
    public static readonly TimeSpan HotData = TimeSpan.FromMinutes(5);
}
```

### 10.2 缓存使用示例
```csharp
// ✅ 使用分布式缓存（Redis）
public class MerchantService : IMerchantService
{
    private readonly IMerchantRepository _merchantRepository;
    private readonly IDistributedCache _cache;
    private readonly ILogger<MerchantService> _logger;

    public async Task<MerchantDto> GetMerchantAsync(Guid merchantId)
    {
        var cacheKey = $"merchant:{merchantId}";

        // 1. 尝试从缓存获取
        var cachedData = await _cache.GetStringAsync(cacheKey);
        if (!string.IsNullOrEmpty(cachedData))
        {
            _logger.LogDebug("从缓存获取商家信息：{MerchantId}", merchantId);
            return JsonSerializer.Deserialize<MerchantDto>(cachedData);
        }

        // 2. 缓存未命中，从数据库查询
        var merchant = await _merchantRepository.GetByIdAsync(merchantId);
        if (merchant == null)
            throw new BusinessException(404, "商家不存在");

        var dto = _mapper.Map<MerchantDto>(merchant);

        // 3. 写入缓存
        var cacheOptions = new DistributedCacheEntryOptions
        {
            AbsoluteExpirationRelativeToNow = CacheTimeouts.MerchantInfo
        };
        await _cache.SetStringAsync(cacheKey, JsonSerializer.Serialize(dto), cacheOptions);

        _logger.LogDebug("商家信息已缓存：{MerchantId}", merchantId);
        return dto;
    }

    public async Task UpdateMerchantAsync(Guid merchantId, UpdateMerchantRequest request)
    {
        // 更新数据库
        var merchant = await _merchantRepository.GetByIdAsync(merchantId);
        // ... 更新逻辑
        await _unitOfWork.SaveChangesAsync();

        // ✅ 更新后清除缓存
        var cacheKey = $"merchant:{merchantId}";
        await _cache.RemoveAsync(cacheKey);
        _logger.LogDebug("已清除商家缓存：{MerchantId}", merchantId);
    }
}
```

## 11. 日志规范（Serilog）

### 11.1 日志级别使用
```csharp
// ✅ 正确的日志级别使用
public class OrderService
{
    private readonly ILogger<OrderService> _logger;

    public async Task<OrderDto> CreateOrderAsync(CreateOrderRequest request)
    {
        // Trace: 非常详细的调试信息（生产环境不记录）
        _logger.LogTrace("进入CreateOrderAsync方法");

        // Debug: 调试信息（生产环境不记录）
        _logger.LogDebug("订单请求参数：{@Request}", request);

        // Information: 一般信息（重要业务流程）
        _logger.LogInformation("开始创建订单，商家ID：{MerchantId}，客户ID：{CustomerId}",
            request.MerchantId, request.CustomerId);

        try
        {
            // ... 业务逻辑

            // Information: 成功完成
            _logger.LogInformation("订单创建成功：{OrderId}，订单号：{OrderNo}",
                order.Id, order.OrderNo);

            return dto;
        }
        catch (BusinessException ex)
        {
            // Warning: 业务异常（预期内的错误）
            _logger.LogWarning(ex, "创建订单失败（业务异常）：{Message}", ex.Message);
            throw;
        }
        catch (Exception ex)
        {
            // Error: 系统异常（非预期错误）
            _logger.LogError(ex, "创建订单失败（系统异常）：{@Request}", request);
            throw;
        }
    }
}
```

### 11.2 结构化日志
```csharp
// ✅ 使用结构化日志（推荐）
_logger.LogInformation("用户 {UserId} 创建了订单 {OrderId}，金额 {Amount}",
    userId, orderId, amount);

// ✅ 记录对象（使用@符号）
_logger.LogInformation("订单详情：{@Order}", order);

// ❌ 不要使用字符串拼接
_logger.LogInformation("用户 " + userId + " 创建了订单 " + orderId);
```

### 11.3 敏感信息处理
```csharp
// ✅ 不要记录敏感信息
public class PaymentService
{
    public async Task ProcessPaymentAsync(PaymentRequest request)
    {
        // ❌ 错误：记录了密码、支付密码等敏感信息
        _logger.LogInformation("支付请求：{@Request}", request);

        // ✅ 正确：只记录非敏感信息
        _logger.LogInformation("处理支付，订单ID：{OrderId}，金额：{Amount}",
            request.OrderId, request.Amount);
    }
}
```

## 12. API控制器规范

### 12.1 控制器结构（标准模板）
```csharp
/// <summary>
/// 订单管理API
/// </summary>
[ApiController]
[Route("api/[controller]")]
[Authorize]
public class OrdersController : ControllerBase
{
    private readonly IMediator _mediator;
    private readonly ILogger<OrdersController> _logger;

    public OrdersController(IMediator mediator, ILogger<OrdersController> logger)
    {
        _mediator = mediator;
        _logger = logger;
    }

    /// <summary>
    /// 创建订单
    /// </summary>
    /// <param name="request">订单创建请求</param>
    /// <returns>订单信息</returns>
    /// <response code="200">创建成功</response>
    /// <response code="400">请求参数错误</response>
    /// <response code="422">业务验证失败</response>
    [HttpPost]
    [ProducesResponseType(typeof(ApiResponse<OrderDto>), StatusCodes.Status200OK)]
    [ProducesResponseType(typeof(ApiResponse<object>), StatusCodes.Status400BadRequest)]
    [ProducesResponseType(typeof(ApiResponse<object>), StatusCodes.Status422UnprocessableEntity)]
    public async Task<IActionResult> CreateOrder([FromBody] CreateOrderRequest request)
    {
        _logger.LogInformation("API调用：创建订单");

        var command = new CreateOrderCommand
        {
            MerchantId = request.MerchantId,
            CustomerId = request.CustomerId,
            Items = request.Items,
            TotalAmount = request.TotalAmount
        };

        var result = await _mediator.Send(command);

        return Ok(ApiResponse<OrderDto>.SuccessResult(result));
    }

    /// <summary>
    /// 获取订单详情
    /// </summary>
    /// <param name="id">订单ID</param>
    /// <returns>订单详情</returns>
    [HttpGet("{id}")]
    [ProducesResponseType(typeof(ApiResponse<OrderDto>), StatusCodes.Status200OK)]
    [ProducesResponseType(typeof(ApiResponse<object>), StatusCodes.Status404NotFound)]
    public async Task<IActionResult> GetOrder(Guid id)
    {
        var query = new GetOrderByIdQuery { OrderId = id };
        var result = await _mediator.Send(query);
        return Ok(ApiResponse<OrderDto>.SuccessResult(result));
    }

    /// <summary>
    /// 获取订单列表
    /// </summary>
    /// <param name="request">查询参数</param>
    /// <returns>订单列表</returns>
    [HttpGet]
    [ProducesResponseType(typeof(ApiResponse<PagedResult<OrderDto>>), StatusCodes.Status200OK)]
    public async Task<IActionResult> GetOrders([FromQuery] GetOrdersRequest request)
    {
        var query = new GetOrdersQuery
        {
            PageIndex = request.PageIndex,
            PageSize = request.PageSize,
            Status = request.Status
        };

        var result = await _mediator.Send(query);
        return Ok(ApiResponse<PagedResult<OrderDto>>.SuccessResult(result));
    }
}
```

### 12.2 统一返回结果（ApiResponse）
```csharp
// ✅ 统一返回结果（泛型）
public class ApiResponse<T>
{
    public bool Success { get; set; }
    public int Code { get; set; } = 200;
    public string? Message { get; set; }
    public T? Data { get; set; }
    public DateTime Timestamp { get; set; } = DateTime.UtcNow;

    // 工厂方法：成功
    public static ApiResponse<T> SuccessResult(T data, string? message = "操作成功") => new()
    {
        Success = true,
        Code = 200,
        Message = message,
        Data = data
    };

    // 工厂方法：失败
    public static ApiResponse<T> Failure(int code, string message) => new()
    {
        Success = false,
        Code = code,
        Message = message
    };
}

// ✅ 分页结果
public class PagedResult<T>
{
    public List<T> Items { get; set; }
    public int TotalCount { get; set; }
    public int PageIndex { get; set; }
    public int PageSize { get; set; }
    public int TotalPages => (int)Math.Ceiling(TotalCount / (double)PageSize);
    public bool HasPreviousPage => PageIndex > 1;
    public bool HasNextPage => PageIndex < TotalPages;
}
```

### 12.3 非泛型便捷封装（推荐在仅返回消息时使用）
```csharp
public static class ApiResponse
{
    // ✅ 仅返回成功/消息（无数据载荷）
    public static ApiResponse<object> Success(string? message = "操作成功")
        => new ApiResponse<object> { Success = true, Code = 200, Message = message, Data = null };

    // ✅ 错误（配合统一错误码）
    public static ApiResponse<object> Failure(int code, string message)
        => new ApiResponse<object> { Success = false, Code = code, Message = message, Data = null };
}
```

### 12.4 统一错误码（ErrorCodes）
```csharp
public static class ErrorCodes
{
    public const int BadRequest = 400;
    public const int Unauthorized = 401;
    public const int Forbidden = 403;
    public const int NotFound = 404;
    public const int Conflict = 409;
    public const int ValidationFailed = 422; // 业务/验证不通过
    public const int InternalServerError = 500;

    // 业务自定义区间（10000+）
    public const int BusinessError = 10001;
}
```

### 12.5 错误响应的ProblemDetails映射（全局异常处理中间件）
```csharp
public class BusinessException : Exception
{
    public int ErrorCode { get; }
    public BusinessException(int errorCode, string message) : base(message) => ErrorCode = errorCode;
}

public class ValidationException : Exception
{
    public IDictionary<string, string[]> Errors { get; }
    public ValidationException(IDictionary<string, string[]> errors) : base("一个或多个验证错误") => Errors = errors;
}

public class ExceptionHandlingMiddleware
{
    private readonly RequestDelegate _next;
    private readonly ILogger<ExceptionHandlingMiddleware> _logger;

    public ExceptionHandlingMiddleware(RequestDelegate next, ILogger<ExceptionHandlingMiddleware> logger)
    { _next = next; _logger = logger; }

    public async Task InvokeAsync(HttpContext context)
    {
        try
        {
            await _next(context);
        }
        catch (BusinessException ex)
        {
            await WriteProblemDetailsAsync(context, StatusCodes.Status422UnprocessableEntity, "业务异常", ex.Message, ex.ErrorCode);
        }
        catch (ValidationException ex)
        {
            await WriteProblemDetailsAsync(context, StatusCodes.Status422UnprocessableEntity, "验证异常", ex.Message, ErrorCodes.ValidationFailed, ex.Errors);
        }
        catch (Exception ex)
        {
            _logger.LogError(ex, "系统异常");
            await WriteProblemDetailsAsync(context, StatusCodes.Status500InternalServerError, "系统异常", "服务器发生错误，请稍后重试", ErrorCodes.InternalServerError);
        }
    }

    private static Task WriteProblemDetailsAsync(HttpContext context, int status, string title, string detail, int code, object? errors = null)
    {
        var problem = new ProblemDetails
        {
            Status = status,
            Title = title,
            Detail = detail,
            Instance = context.Request.Path,
            Type = $"https://httpstatuses.com/{status}"
        };
        problem.Extensions["code"] = code;
        if (errors != null) problem.Extensions["errors"] = errors;

        context.Response.StatusCode = status;
        context.Response.ContentType = "application/problem+json";
        return context.Response.WriteAsJsonAsync(problem);
    }
}

// Program.cs 中注册
app.UseMiddleware<ExceptionHandlingMiddleware>();
```


## 13. 实体和DTO规范

### 13.1 实体类（Domain Entity）
```csharp
// ✅ 领域实体
public class Order : BaseEntity
{
    public Guid Id { get; private set; }
    public string OrderNo { get; private set; }
    public Guid MerchantId { get; private set; }
    public Guid CustomerId { get; private set; }
    public decimal TotalAmount { get; private set; }
    public OrderStatus Status { get; private set; }
    public DateTime CreatedAt { get; private set; }
    public DateTime? UpdatedAt { get; private set; }

    // 导航属性
    public virtual Merchant Merchant { get; private set; }
    public virtual Customer Customer { get; private set; }
    public virtual ICollection<OrderItem> OrderItems { get; private set; }

    // 私有构造函数（用于EF Core）
    private Order() { }

    // 工厂方法
    public static Order Create(Guid merchantId, Guid customerId, decimal totalAmount)
    {
        return new Order
        {
            Id = Guid.NewGuid(),
            OrderNo = GenerateOrderNo(),
            MerchantId = merchantId,
            CustomerId = customerId,
            TotalAmount = totalAmount,
            Status = OrderStatus.Pending,
            CreatedAt = DateTime.UtcNow
        };
    }

    // 业务方法
    public void Confirm()
    {
        if (Status != OrderStatus.Pending)
            throw new BusinessException(400, "只有待确认的订单才能确认");

        Status = OrderStatus.Confirmed;
        UpdatedAt = DateTime.UtcNow;
    }

    public void Cancel(string reason)
    {
        if (Status == OrderStatus.Completed)
            throw new BusinessException(400, "已完成的订单不能取消");

        Status = OrderStatus.Cancelled;
        UpdatedAt = DateTime.UtcNow;
    }

    private static string GenerateOrderNo()
    {
        return $"ORD{DateTime.UtcNow:yyyyMMddHHmmss}{Random.Shared.Next(1000, 9999)}";
    }
}
```

### 13.2 DTO（数据传输对象）
```csharp
// ✅ 请求DTO
public class CreateOrderRequest
{
    public Guid MerchantId { get; set; }
    public Guid CustomerId { get; set; }
    public List<OrderItemDto> Items { get; set; }
    public decimal TotalAmount { get; set; }
    public string DeliveryAddress { get; set; }
    public string ContactPhone { get; set; }
    public string Remark { get; set; }
}

// ✅ 响应DTO
public class OrderDto
{
    public Guid Id { get; set; }
    public string OrderNo { get; set; }
    public Guid MerchantId { get; set; }
    public string MerchantName { get; set; }
    public Guid CustomerId { get; set; }
    public string CustomerName { get; set; }
    public decimal TotalAmount { get; set; }
    public OrderStatus Status { get; set; }
    public string StatusText { get; set; }
    public List<OrderItemDto> Items { get; set; }
    public DateTime CreatedAt { get; set; }
}
```

### 13.3 AutoMapper配置
```csharp
// ✅ AutoMapper Profile
public class OrderMappingProfile : Profile
{
    public OrderMappingProfile()
    {
        CreateMap<Order, OrderDto>()
            .ForMember(dest => dest.MerchantName, opt => opt.MapFrom(src => src.Merchant.Name))
            .ForMember(dest => dest.CustomerName, opt => opt.MapFrom(src => src.Customer.Name))
            .ForMember(dest => dest.StatusText, opt => opt.MapFrom(src => src.Status.ToString()));

        CreateMap<CreateOrderRequest, Order>()
            .ForMember(dest => dest.Id, opt => opt.Ignore())
            .ForMember(dest => dest.OrderNo, opt => opt.Ignore())
            .ForMember(dest => dest.CreatedAt, opt => opt.Ignore());
    }
}
```


## 14. Git工作流规范

### 14.1 分支管理
```
main            # 主分支，生产环境代码
├── develop     # 开发分支
│   ├── feature/order-management    # 功能分支
│   ├── feature/payment-integration # 功能分支
│   └── bugfix/order-calculation    # 修复分支
└── hotfix/critical-bug             # 紧急修复分支
```

### 14.2 分支命名规范
- **功能分支**：`feature/功能名称`（如：`feature/order-management`）
- **修复分支**：`bugfix/问题描述`（如：`bugfix/order-calculation`）
- **紧急修复**：`hotfix/问题描述`（如：`hotfix/payment-error`）
- **发布分支**：`release/版本号`（如：`release/v1.0.0`）

### 14.3 提交信息规范（严格遵守）
```bash
# 格式：<type>(<scope>): <subject>

# type类型（必须使用以下之一）：
# feat: 新功能
# fix: 修复bug
# docs: 文档更新
# style: 代码格式调整（不影响代码运行）
# refactor: 重构（既不是新功能也不是修复bug）
# perf: 性能优化
# test: 测试相关
# chore: 构建/工具相关

# 示例（必须遵循）：
git commit -m "feat(order): 添加订单创建功能"
git commit -m "fix(payment): 修复支付回调处理错误"
git commit -m "docs(api): 更新API文档"
git commit -m "refactor(service): 重构订单服务"
git commit -m "perf(query): 优化订单查询性能"
```

## 15. 单元测试规范

### 15.1 测试命名规范
```csharp
// ✅ 测试命名格式：MethodName_Scenario_ExpectedResult
[Fact]
public async Task CreateOrder_ValidRequest_ReturnsOrderDto()
{
    // Arrange（准备）
    var request = new CreateOrderRequest
    {
        MerchantId = Guid.NewGuid(),
        CustomerId = Guid.NewGuid(),
        Items = new List<OrderItemDto>
        {
            new OrderItemDto { DishId = Guid.NewGuid(), Quantity = 2, Price = 50.00m }
        },
        TotalAmount = 100.00m
    };

    // Act（执行）
    var result = await _orderService.CreateOrderAsync(request);

    // Assert（断言）
    result.Should().NotBeNull();
    result.OrderNo.Should().NotBeNullOrEmpty();
    result.TotalAmount.Should().Be(100.00m);
}

[Fact]
public async Task CreateOrder_InvalidMerchantId_ThrowsBusinessException()
{
    // Arrange
    var request = new CreateOrderRequest
    {
        MerchantId = Guid.Empty, // 无效的商家ID
        CustomerId = Guid.NewGuid(),
        TotalAmount = 100.00m
    };

    // Act & Assert
    await Assert.ThrowsAsync<BusinessException>(
        async () => await _orderService.CreateOrderAsync(request));
}
```

### 15.2 Mock使用
```csharp
// ✅ 使用Moq进行Mock
public class OrderServiceTests
{
    private readonly Mock<IOrderRepository> _orderRepositoryMock;
    private readonly Mock<IUnitOfWork> _unitOfWorkMock;
    private readonly Mock<ILogger<OrderService>> _loggerMock;
    private readonly Mock<IMapper> _mapperMock;
    private readonly OrderService _orderService;

    public OrderServiceTests()
    {
        _orderRepositoryMock = new Mock<IOrderRepository>();
        _unitOfWorkMock = new Mock<IUnitOfWork>();
        _loggerMock = new Mock<ILogger<OrderService>>();
        _mapperMock = new Mock<IMapper>();

        _orderService = new OrderService(
            _orderRepositoryMock.Object,
            _unitOfWorkMock.Object,
            _loggerMock.Object,
            _mapperMock.Object,
            Options.Create(new OrderSettings())
        );
    }

    [Fact]
    public async Task GetOrder_ExistingId_ReturnsOrder()
    {
        // Arrange
        var orderId = Guid.NewGuid();
        var order = new Order { Id = orderId, OrderNo = "ORD001" };
        var orderDto = new OrderDto { Id = orderId, OrderNo = "ORD001" };

        _orderRepositoryMock
            .Setup(x => x.GetByIdAsync(orderId))
            .ReturnsAsync(order);

        _mapperMock
            .Setup(x => x.Map<OrderDto>(order))
            .Returns(orderDto);

        // Act
        var result = await _orderService.GetOrderAsync(orderId);

        // Assert
        result.Should().NotBeNull();
        result.Id.Should().Be(orderId);
        _orderRepositoryMock.Verify(x => x.GetByIdAsync(orderId), Times.Once);
    }
}
```

### 15.3 测试覆盖率要求
- **核心业务逻辑**：>= 80%
- **服务层**：>= 70%
- **仓储层**：>= 60%
- **控制器层**：>= 50%

## 16. 性能优化规范

### 16.1 数据库查询优化
```csharp
// ❌ 错误：N+1查询问题
public async Task<List<OrderDto>> GetOrdersAsync()
{
    var orders = await _context.Orders.ToListAsync();

    foreach (var order in orders)
    {
        // 每次循环都会查询数据库！
        order.Customer = await _context.Customers.FindAsync(order.CustomerId);
        order.Merchant = await _context.Merchants.FindAsync(order.MerchantId);
    }

    return _mapper.Map<List<OrderDto>>(orders);
}

// ✅ 正确：使用Include预加载
public async Task<List<OrderDto>> GetOrdersAsync()
{
    var orders = await _context.Orders
        .Include(o => o.Customer)
        .Include(o => o.Merchant)
        .Include(o => o.OrderItems)
            .ThenInclude(oi => oi.Dish)
        .ToListAsync();

    return _mapper.Map<List<OrderDto>>(orders);
}

// ✅ 更好：大数据量使用Dapper
public async Task<List<OrderDto>> GetOrdersAsync()
{
    var sql = @"
        SELECT
            o.id, o.order_no, o.total_amount,
            c.id as customer_id, c.name as customer_name,
            m.id as merchant_id, m.name as merchant_name
        FROM orders o
        INNER JOIN customers c ON o.customer_id = c.id
        INNER JOIN merchants m ON o.merchant_id = m.id
        WHERE o.status = @Status
        ORDER BY o.created_at DESC
        LIMIT @Limit OFFSET @Offset";

    return await _connection.QueryAsync<OrderDto>(sql, new { Status = 1, Limit = 100, Offset = 0 });
}
```

### 16.2 异步编程规范
```csharp
// ✅ 正确：使用async/await
public async Task<OrderDto> CreateOrderAsync(CreateOrderRequest request)
{
    var order = new Order { /* ... */ };
    await _orderRepository.AddAsync(order);
    await _unitOfWork.SaveChangesAsync();
    return _mapper.Map<OrderDto>(order);
}

// ❌ 错误：不要使用.Result或.Wait()
public OrderDto CreateOrder(CreateOrderRequest request)
{
    var order = new Order { /* ... */ };
    _orderRepository.AddAsync(order).Wait(); // 可能导致死锁！
    _unitOfWork.SaveChangesAsync().Result;  // 可能导致死锁！
    return _mapper.Map<OrderDto>(order);
}

// ❌ 错误：不要混用同步和异步
public async Task<OrderDto> CreateOrderAsync(CreateOrderRequest request)
{
    var order = new Order { /* ... */ };
    _orderRepository.AddAsync(order).Wait(); // 错误！
    await _unitOfWork.SaveChangesAsync();
    return _mapper.Map<OrderDto>(order);
}
```

### 16.3 批量操作优化
```csharp
// ❌ 错误：逐条插入
public async Task ImportOrdersAsync(List<Order> orders)
{
    foreach (var order in orders)
    {
        await _context.Orders.AddAsync(order);
        await _context.SaveChangesAsync(); // 每次都保存，性能差！
    }
}

// ✅ 正确：批量插入
public async Task ImportOrdersAsync(List<Order> orders)
{
    await _context.Orders.AddRangeAsync(orders);
    await _context.SaveChangesAsync(); // 一次性保存
}

// ✅ 更好：使用Dapper批量插入（大数据量）
public async Task ImportOrdersAsync(List<Order> orders)
{
    var sql = @"
        INSERT INTO orders (id, order_no, merchant_id, total_amount, created_at)
        VALUES (@Id, @OrderNo, @MerchantId, @TotalAmount, @CreatedAt)";

    await _connection.ExecuteAsync(sql, orders);
}
```

## 17. 安全规范

### 17.1 SQL注入防护
```csharp
// ❌ 错误：字符串拼接SQL（SQL注入风险）
public async Task<Order> GetOrderByNoAsync(string orderNo)
{
    var sql = $"SELECT * FROM orders WHERE order_no = '{orderNo}'"; // 危险！
    return await _connection.QueryFirstOrDefaultAsync<Order>(sql);
}

// ✅ 正确：使用参数化查询
public async Task<Order> GetOrderByNoAsync(string orderNo)
{
    var sql = "SELECT * FROM orders WHERE order_no = @OrderNo";
    return await _connection.QueryFirstOrDefaultAsync<Order>(sql, new { OrderNo = orderNo });
}
```

### 17.2 敏感数据加密
```csharp
// ✅ 密码加密存储
public class UserService
{
    private readonly IPasswordHasher<User> _passwordHasher;

    public async Task<User> CreateUserAsync(string username, string password)
    {
        var user = new User { Username = username };

        // ✅ 使用密码哈希
        user.PasswordHash = _passwordHasher.HashPassword(user, password);

        await _userRepository.AddAsync(user);
        await _unitOfWork.SaveChangesAsync();

        return user;
    }

    public async Task<bool> ValidatePasswordAsync(User user, string password)
    {
        var result = _passwordHasher.VerifyHashedPassword(user, user.PasswordHash, password);
        return result == PasswordVerificationResult.Success;
    }
}
```

### 17.3 授权验证
```csharp
// ✅ 使用授权特性
[Authorize(Roles = "Admin")]
public class AdminController : ControllerBase
{
    [HttpGet("users")]
    public async Task<IActionResult> GetUsers()
    {
        // 只有Admin角色可以访问
    }
}

// ✅ 基于策略的授权
[Authorize(Policy = "MerchantOwner")]
public class MerchantController : ControllerBase
{
    [HttpPut("{id}")]
    public async Task<IActionResult> UpdateMerchant(Guid id, UpdateMerchantRequest request)
    {
        // 只有商家所有者可以更新
    }
}

// ✅ 在服务层也要验证权限
public async Task UpdateMerchantAsync(Guid merchantId, Guid userId, UpdateMerchantRequest request)
{
    var merchant = await _merchantRepository.GetByIdAsync(merchantId);

    // 验证用户是否有权限
    if (merchant.OwnerId != userId)
    {
        throw new BusinessException(403, "无权限操作");
    }

    // ... 更新逻辑
}
```

## 18. 代码审查清单

### 18.1 必查项目
- [ ] 代码符合命名规范（PascalCase、camelCase、_camelCase）
- [ ] 所有公共API有XML文档注释
- [ ] 复杂业务逻辑有注释说明
- [ ] 异常处理完善（try-catch、自定义异常）
- [ ] 使用异步方法（async/await）
- [ ] 使用依赖注入（构造函数注入）
- [ ] 使用仓储模式（不直接操作DbContext）
- [ ] 使用工作单元模式（事务管理）
- [ ] 日志记录完善（Information、Warning、Error）
- [ ] 参数验证（FluentValidation）
- [ ] 返回DTO而不是实体
- [ ] 无硬编码配置（使用IOptions）
- [ ] 无SQL注入风险（参数化查询）
- [ ] 敏感数据加密
- [ ] 权限验证完善

### 18.2 性能检查
- [ ] 避免N+1查询（使用Include）
- [ ] 大数据量使用Dapper
- [ ] 合理使用缓存
- [ ] 批量操作使用批量方法
- [ ] 异步方法不使用.Result或.Wait()

### 18.3 安全检查
- [ ] 无SQL注入风险
- [ ] 密码已加密
- [ ] 授权验证完善
- [ ] 敏感信息不记录日志
- [ ] HTTPS传输

## 19. 禁止事项（严格禁止）

### 19.1 绝对禁止
```csharp
// ❌ 禁止：直接在控制器或服务中使用DbContext
public class OrderController
{
    private readonly AppDbContext _context; // 禁止！
}

// ❌ 禁止：硬编码配置
var deliveryFee = 5.0m; // 禁止！应该从配置读取

// ❌ 禁止：返回实体类
public Order GetOrder(Guid id) // 禁止！应该返回DTO
{
    return _context.Orders.Find(id);
}

// ❌ 禁止：字符串拼接SQL
var sql = $"SELECT * FROM orders WHERE id = '{id}'"; // 禁止！SQL注入风险

// ❌ 禁止：吞掉异常
try
{
    // ...
}
catch (Exception)
{
    // 什么都不做 - 禁止！
}

// ❌ 禁止：使用.Result或.Wait()
var result = _service.GetOrderAsync(id).Result; // 禁止！可能死锁

// ❌ 禁止：记录敏感信息
_logger.LogInformation("用户密码：{Password}", password); // 禁止！

// ❌ 禁止：不使用异步方法
public Order CreateOrder(CreateOrderRequest request) // 禁止！应该使用async
{
    _context.Orders.Add(order);
    _context.SaveChanges(); // 应该使用SaveChangesAsync
}
```

## 20. 最佳实践总结

### 20.1 核心原则
1. **SOLID原则**：单一职责、开闭原则、里氏替换、接口隔离、依赖倒置
2. **DRY原则**：不要重复自己（Don't Repeat Yourself）
3. **KISS原则**：保持简单（Keep It Simple, Stupid）
4. **YAGNI原则**：你不会需要它（You Aren't Gonna Need It）

### 20.2 编码习惯
- ✅ 使用有意义的变量名
- ✅ 方法保持简短（不超过50行）
- ✅ 类保持单一职责
- ✅ 优先使用组合而不是继承
- ✅ 编写可测试的代码
- ✅ 先写测试再写代码（TDD）
- ✅ 持续重构，保持代码整洁

### 20.3 团队协作
- ✅ 遵循统一的代码规范
- ✅ 代码审查必须通过
- ✅ 提交前运行测试
- ✅ 提交信息清晰明确
- ✅ 及时更新文档
- ✅ 主动分享知识

---

## 附录：快速参考

### A. 常用命名模式
- 类：`OrderService`、`MerchantRepository`
- 接口：`IOrderService`、`IMerchantRepository`
- 方法：`CreateOrderAsync`、`GetOrderByIdAsync`
- 字段：`_orderRepository`、`_logger`
- 属性：`OrderNo`、`TotalAmount`
- 变量：`orderTotal`、`merchantId`

### B. 常用文件夹结构
```
Controllers/
Services/
Repositories/
DTOs/
Entities/
Validators/
Mappings/
Exceptions/
Constants/
Extensions/
```

### C. 必须使用的NuGet包
- Microsoft.EntityFrameworkCore
- Dapper
- AutoMapper.Extensions.Microsoft.DependencyInjection
- FluentValidation.AspNetCore
- Serilog.AspNetCore
- MediatR
- Swashbuckle.AspNetCore
- xUnit
- Moq
- FluentAssertions

---

**文档版本**：v1.0
**最后更新**：2025-11-22
**适用项目**：外卖SaaS系统
**目标读者**：AI编程助手、开发人员