---
applyTo: "src/Fengling.Member.Web/Application/Commands/**/*.cs"
---

# 命令与命令处理器开发指南

## 开发原则

### 必须

- **命令定义**：
    - 使用 `record` 类型定义命令。
    - 无返回值命令实现 `ICommand` 接口。
    - 有返回值命令实现 `ICommand<TResponse>` 接口。
    - 必须为每个命令创建验证器，继承 `AbstractValidator<TCommand>`。
    - 命令处理器实现对应的 `ICommandHandler` 接口。
    - 命令处理器中必须通过仓储存取聚合数据。
    - 优先使用异步方法，所有仓储操作都应使用异步版本。
    - 将 `CancellationToken` 传递给所有异步操作。
    - 使用主构造函数注入所需的仓储或服务。
- **异常处理**：
    - 使用 `KnownException` 处理业务异常。
    - 业务验证失败时抛出明确的错误信息。

### 必须不要

- **事务管理**：
    - 不要手动调用 `SaveChanges`，框架会自动在命令处理完成后调用。
    - 不要手动调用 `UpdateAsync`，如果实体是从仓储取出，则会自动跟踪变更。
- **仓储使用**：
    - 避免在命令处理器中进行复杂的查询操作（应使用查询端）。
    - 仓储方法名不应是通用数据访问，而应体现业务意图。
- **重复引用**：无需重复添加 `GlobalUsings` 中已定义的 `using` 语句。

## 文件命名规则

- 类文件应放置在 `src/Fengling.Member.Web/Application/Commands/{Module}s/` 目录下（以模块复数形式命名，避免命名空间与聚合类名冲突）。
- 命令文件名格式为 `{Action}{Entity}Command.cs`。
- 同一个命令及其对应的验证器和处理器定义在同一文件中。
- 不同的命令放在不同文件中。

## 代码示例

**文件**: `src/Fengling.Member.Web/Application/Commands/Users/CreateUserCommand.cs`

```csharp
using Fengling.Member.Domain.AggregatesModel.UserAggregate;
using Fengling.Member.Infrastructure.Repositories;

namespace Fengling.Member.Web.Application.Commands.Users;

public record CreateUserCommand(string Name, string Email) : ICommand<UserId>;

public class CreateUserCommandValidator : AbstractValidator<CreateUserCommand>
{
    public CreateUserCommandValidator()
    {
        RuleFor(x => x.Name)
            .NotEmpty()
            .WithMessage("用户名不能为空")
            .MaximumLength(50)
            .WithMessage("用户名不能超过50个字符");
            
        RuleFor(x => x.Email)
            .NotEmpty()
            .WithMessage("邮箱不能为空")
            .EmailAddress()
            .WithMessage("邮箱格式不正确")
            .MaximumLength(100)
            .WithMessage("邮箱不能超过100个字符");
    }
}

public class CreateUserCommandHandler(IUserRepository userRepository)
    : ICommandHandler<CreateUserCommand, UserId>
{
    public async Task<UserId> Handle(CreateUserCommand command, CancellationToken cancellationToken)
    {
        if (await userRepository.EmailExistsAsync(command.Email, cancellationToken))
        {
            throw new KnownException("邮箱已存在");
        }
        
        var user = new User(command.Name, command.Email);
        await userRepository.AddAsync(user, cancellationToken);
        return user.Id;
    }
}
```