[![构建](https://yellow-cdn.veclightyear.com/835a84d5/f0deeb91-215a-48c8-8314-304e776d1606.svg)](https://github.com/amantinband/clean-architecture/actions/workflows/build.yml) [![发布模板到NuGet](https://yellow-cdn.veclightyear.com/835a84d5/e737d71a-4fc4-45c0-a1dc-c9e194ebbf26.svg)](https://github.com/amantinband/clean-architecture/actions/workflows/publish.yml) [![GitHub贡献者](https://img.shields.io/github/contributors/amantinband/clean-architecture)](https://GitHub.com/amantinband/clean-architecture/graphs/contributors/) [![GitHub星标](https://yellow-cdn.veclightyear.com/835a84d5/01271902-192f-4499-b9dd-467939cc5f41.svg)](https://github.com/amantinband/clean-architecture/stargazers) [![GitHub许可证](https://img.shields.io/github/license/amantinband/clean-architecture)](https://github.com/amantinband/clean-architecture/blob/main/LICENSE) [![codecov](https://yellow-cdn.veclightyear.com/835a84d5/bc8f2c25-86b9-4831-90ad-4dacb6cfab70.svg?token=DR2EBIWK7B)](https://codecov.io/gh/amantinband/clean-architecture) --- ![清洁架构模板标题](https://yellow-cdn.veclightyear.com/835a84d5/ed40f005-eff9-4dde-b3c1-18dae277e389.png) ---

```shell dotnet new install Amantinband.CleanArchitecture.Template

dotnet new clean-arch -o CleanArchitecture

- [️重要通知 ⚠️](#️重要通知-️)
- [给个星标 ⭐](#给个星标-)
- [领域概览 🌍](#领域概览-)
- [基础订阅](#基础订阅)
- [专业订阅](#专业订阅)
- [用例/功能 🤓](#用例功能-)
- [订阅](#订阅)
- [提醒](#提醒)
- [开始使用 🏃](#开始使用-)
- [YouTube教程](#youtube教程)
- [安装模板或克隆项目](#安装模板或克隆项目)
- [使用Docker或.NET CLI运行服务](#使用docker或net-cli运行服务)
- [生成令牌](#生成令牌)
- [创建订阅](#创建订阅)
- [创建提醒](#创建提醒)
- [文件夹结构 📁](#文件夹结构-)
- [授权 🔐](#授权-)
- [授权类型](#授权类型)
- [基于角色的授权](#基于角色的授权)
- [基于权限的授权](#基于权限的授权)
- [基于策略的授权](#基于策略的授权)
- [混合授权类型](#混合授权类型)
- [测试 📝](#测试-)
- [测试类型](#测试类型)
- [领域层单元测试](#领域层单元测试)
- [应用层单元测试](#应用层单元测试)
- [应用层皮下测试](#应用层皮下测试)
- [表现层集成测试](#表现层集成测试)
- [有趣的功能 💃🕺](#有趣的功能-)
- [领域事件与最终一致性](#领域事件与最终一致性)
- [最终一致性机制](#最终一致性机制)
- [发送邮件提醒的后台服务](#发送邮件提醒的后台服务)
- [配置邮件设置](#配置邮件设置)
- [手动配置邮件设置](#手动配置邮件设置)
- [通过用户机密配置邮件设置](#通过用户机密配置邮件设置)
- [贡献 🤲](#贡献-)
- [致谢 🙏](#致谢-)
- [许可证 🪪](#许可证-)
# ️重要通知 ⚠️

此模板仍在建设中 👷。

查看我在Dometrain上的全面[课程](https://dometrain.com/bundle/from-zero-to-hero-clean-architecture/?coupon_code=GITHUB)，我在其中涵盖了构建遵循清洁架构的生产应用程序时需要了解的所有内容。使用专属优惠码 `GITHUB` 可获得5%的折扣（顺便说一下，这是该套装唯一的促销代码，而该套装本已享有20%的折扣）。

<img src="https://yellow-cdn.veclightyear.com/835a84d5/3a9f4bb8-3b9d-44f8-9cbb-f89ebd1757b2.png" height=30px >
# 给个星星吧 ⭐

喜欢这个项目吗？给它点个星来表示支持吧！
# 领域概述 🌍

这是一个简单的提醒应用程序。它允许用户创建和管理他们的提醒事项。

要创建提醒，用户必须拥有有效的订阅。

## 基础订阅

拥有基础订阅的用户每天最多可以创建3个提醒。

## 专业订阅

拥有专业订阅的用户对每日创建的提醒数量没有限制。
# 使用场景/功能 🤓

## 订阅
1. 创建订阅
2. 获取订阅信息
3. 取消订阅

## 提醒
1. 设置提醒
2. 获取提醒信息
3. 删除提醒
4. 忽略提醒
5. 列出所有提醒
# 开始使用 🏃  
## YouTube 教程  
[![Clean Architecture 教程](https://yellow-cdn.veclightyear.com/835a84d5/403ee0ad-fa9a-4d03-b2da-2d477b86dc62.jpg)](https://www.youtube.com/watch?v=DTmlhHu8tHA)  
## 安装模板或克隆项目  
```shell
dotnet new install Amantinband.CleanArchitecture.Template

dotnet new clean-arch -o CleanArchitecture

或者

git clone https://github.com/amantinband/clean-architecture

使用 Docker 或 .NET CLI 运行服务

docker compose up

或者

dotnet run --project src/CleanArchitecture.Api

生成令牌

导航到 requests/Tokens/GenerateToken.http 并生成令牌。

注意：由于大多数系统使用外部身份提供商，本项目使用一个简单的令牌生成器端点，根据您提供的详细信息生成令牌。这是一种用于测试目的生成令牌的简单方法，更接近于使用外部身份提供商时系统的设计方式。

POST {{host}}/tokens/generate
Content-Type: application/json

{
"Id": "bae93bf5-9e3c-47b3-aace-3034653b6bb2",
"FirstName": "Amichai",
"LastName": "Mantinband",
"Email": "amichai@mantinband.com",
"Permissions": [
"set:reminder",
"get:reminder",
"dismiss:reminder",
"delete:reminder",
"create:subscription",
"delete:subscription",
"get:subscription"
],
"Roles": [
"Admin"
]
}

注意：替换 http 文件变量 (`{{variableName}}`)

选项 1（推荐）- 使用 VS Code 的 REST Client 扩展

使用 VS Code 的 REST Client 扩展 + 更新 .vscode/settings.json 下的值。这将更新所有 http 文件的值。

{
   "rest-client.environmentVariables": {
       "$shared": { // 这些将在所有 http 文件中共享，不受环境影响
           "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJuYW1lIjoiTGlvciIsImZhbWlseV9uYW1lIjoiRGFnYW4iLCJlbWFpbCI6Imxpb3JAZGFnYW4uY29tIiwiaWQiOiJhYWU5M2JmNS05ZTNjLTQ3YjMtYWFjZS0zMDM0NjUzYjZiYjIiLCJodHRwOi8vc2NoZW1hcy5taWNyb3NvZnQuY29tL3dzLzIwMDgvMDYvaWRlbnRpdHkvY2xhaW1zL3JvbGUiOiJBZG1pbiIsInBlcm1pc3Npb25zIjpbInNldDpyZW1pbmRlciIsImdldDpyZW1pbmRlciIsImRpc21pc3M6cmVtaW5kZXIiLCJkZWxldGU6cmVtaW5kZXIiLCJjcmVhdGU6c3Vic2NyaXB0aW9uIiwiZGVsZXRlOnN1YnNjcmlwdGlvbiIsImdldDpzdWJzY3JpcHRpb24iXSwiZXhwIjoxNzA0MTM0MTIzLCJpc3MiOiJSZW1pbmRlclNlcnZpY2UiLCJhdWQiOiJSZW1pbmRlclNlcnZpY2UifQ.wyvn9cq3ohp-JPTmbBd3G1cAU1A6COpiQd3C_e_Ng5s",
           "userId": "aae93bf5-9e3c-47b3-aace-3034653b6bb2",
           "subscriptionId": "c8ee11f0-d4bb-4b43-a448-d511924b520e",
           "reminderId": "08233bb1-ce29-49e2-b346-5f8b7cf61593"
       },
       "dev": { // 当环境设置为 dev 时，将使用这些值
           "host": "http://localhost:5001",
       },
       "prod": { // 当环境设置为 prod 时，将使用这些值
           "host": "http://your-prod-endpoint.com",
       }
   }
}

选项 2 - 在 http 文件本身定义变量

在 http 文件本身定义变量。这只会更新当前 http 文件的值。

@host = http://localhost:5001

POST {{host}}/tokens/generate

选项 3 - 手动

手动替换变量。

POST {{host}}/tokens/generate

👇

POST http://localhost:5001/tokens/generate

创建订阅

POST {{host}}/users/{{userId}}/subscriptions
Content-Type: application/json
Authorization: Bearer {{token}}

{
"SubscriptionType": "Basic"
}

创建提醒

POST {{host}}/users/{{userId}}/subscriptions/{{subscriptionId}}/reminders
Content-Type: application/json
Authorization: Bearer {{token}}

{
"text": "让我们开始吧",
"dateTime": "2025-2-26"
}

文件夹结构 📁

文件夹结构

你可以使用这个 Figma 社区文件来探索或创建你自己的文件夹结构表示。

授权 🔐

本项目着重于复杂的授权场景，支持基于角色、基于权限和基于策略的授权。

授权类型

基于角色的授权

要应用基于角色的授权，请使用带有Roles参数的Authorize特性，并实现IAuthorizeableRequest接口。

例如：

[Authorize(Roles = "Admin")]
public record CancelSubscriptionCommand(Guid UserId, Guid SubscriptionId) : IAuthorizeableRequest<ErrorOr<Success>>;

这将只允许具有Admin角色的用户取消订阅。

基于权限的授权

要应用基于权限的授权，请使用带有Permissions参数的Authorize特性，并实现IAuthorizeableRequest接口。

例如：

[Authorize(Permissions = "get:reminder")]
public record GetReminderQuery(Guid UserId, Guid SubscriptionId, Guid ReminderId) : IAuthorizeableRequest<ErrorOr<Reminder>>;

这将只允许具有get:reminder权限的用户获取提醒。

基于策略的授权

要应用基于策略的授权，请使用带有Policy参数的Authorize特性，并实现IAuthorizeableRequest接口。

例如：

[Authorize(Policies = "SelfOrAdmin")]
public record GetReminderQuery(Guid UserId, Guid SubscriptionId, Guid ReminderId) : IAuthorizeableRequest<ErrorOr<Reminder>>;

这将只允许通过SelfOrAdmin策略的用户获取提醒。

每个策略都在PolicyEnforcer类中以简单方法的形式实现。

例如，"SelfOrAdmin"策略可以如下实现：

public class PolicyEnforcer : IPolicyEnforcer
{
    public ErrorOr<Success> Authorize<T>(
        IAuthorizeableRequest<T> request,
        CurrentUser currentUser,
        string policy)
    {
        return policy switch
        {
            "SelfOrAdmin" => SelfOrAdminPolicy(request, currentUser),
            _ => Error.Unexpected(description: "Unknown policy name"),
        };
    }

    private static ErrorOr<Success> SelfOrAdminPolicy<T>(IAuthorizeableRequest<T> request, CurrentUser currentUser) =>
        request.UserId == currentUser.Id || currentUser.Roles.Contains(Role.Admin)
            ? Result.Success
            : Error.Unauthorized(description: "Requesting user failed policy requirement");
}

混合授权类型

您可以混合搭配授权类型来创建复杂的授权场景。

例如：

[Authorize(Permissions = "get:reminder,list:reminder", Policies = "SelfOrAdmin", Roles = "ReminderManager")]
public record ListRemindersQuery(Guid UserId, Guid SubscriptionId, Guid ReminderId) : IAuthorizeableRequest<ErrorOr<Reminder>>;

这将只允许同时具有get:reminder和list:reminder权限，通过SelfOrAdmin策略，并拥有ReminderManager角色的用户列出提醒。

另一种选择是多次指定Authorize特性：

[Authorize(Permissions = "get:reminder")]
[Authorize(Permissions = "list:reminder")]
[Authorize(Policies = "SelfOrAdmin")]
[Authorize(Roles = "ReminderManager")]
public record ListRemindersQuery(Guid UserId, Guid SubscriptionId, Guid ReminderId) : IAuthorizeableRequest<ErrorOr<Reminder>>;

测试 📝

本项目注重可测试性，并附带全面的测试套件。

测试类型

领域层单元测试

领域层使用单元测试进行测试。至少，每个领域实体都应该有一个验证其不变量的测试。

领域层单元测试

应用层单元测试

应用层使用单元测试和表层测试进行测试。由于应用层的每个用例都有相应的表层测试，单元测试用于测试应用层的独立组件，如ValidationBehavior和AuthorizationBehavior。

应用层单元测试

应用层表层测试

表层测试是在表现层正下方进行操作的测试。这些测试负责测试我们应用程序的核心逻辑，即应用层和领域层。之所以有这么多这样的测试，是因为应用层的每个用例都有相应的表层测试。这使我们能够根据实际预期用途测试应用层和领域层，让我们确信我们的应用程序按预期工作，并且系统不会被以我们不允许的方式操纵。我建议在这些测试上投入更多精力，因为它们编写成本不高，而且提供的价值巨大。

表现层集成测试

API层使用集成测试进行测试。这里我们希望覆盖整个系统，包括数据库、外部依赖和表现层。与表层测试不同，这些测试的重点是确保我们系统的各个组件之间以及与其他系统的集成。

集成测试

有趣的功能 💃🕺

领域事件与最终一致性

注意：最终一致性和领域事件模式会增加一层复杂性。如果你不需要它，就不要使用它。如果你需要它，请确保你的系统设计得当，并且你有合适的工具来管理故障。

领域设计使得每个操作数据的用例在单个事务中只更新一个领域对象。

例如，当用户取消订阅时，唯一的原子性变化就是将订阅标记为已取消：

public ErrorOr<Success> CancelSubscription(Guid subscriptionId)
{
    if (subscriptionId != Subscription.Id)
    {
        return Error.NotFound("找不到订阅");
    }

    Subscription = Subscription.Canceled;

    _domainEvents.Add(new SubscriptionCanceledEvent(this, subscriptionId));

    return Result.Success;
}

然后，系统会以最终一致性的方式更新所有相关数据。这包括：

从数据库中删除订阅并将所有提醒标记为已删除（Subscriptions/Events/SubscriptionDeletedEventHandler.cs）
从数据库中删除所有标记为已删除的提醒（Reminders/Events/ReminderDeletedEventHandler.cs）

注意：除了性能优势外，这还允许重用响应式行为。例如，当订阅被删除和提醒被删除时，都会调用ReminderDeletedEventHandler。

最终一致性机制

每个不变量都封装在单个领域对象中。这允许通过在单个事务中更新单个领域对象来执行更改。
如果领域对象B需要对领域对象A的变化做出反应，则在领域对象A的更改中添加一个领域事件。
将领域对象A的更改持久化到数据库时，领域事件被提取并添加到队列中以进行离线处理：

private void AddDomainEventsToOfflineProcessingQueue(List<IDomainEvent> domainEvents)
{
    Queue<IDomainEvent> domainEventsQueue = new();
    domainEvents.ForEach(domainEventsQueue.Enqueue);

    _httpContextAccessor.HttpContext.Items["DomainEvents"] = domainEventsQueue;
}

用户收到响应后，EventualConsistencyMiddleware被调用并处理领域事件：

public async Task InvokeAsync(HttpContext context, IEventualConsistencyProcessor eventualConsistencyProcessor)
{
    context.Response.OnCompleted(async () =>
    {
        if (context.Items.TryGetValue("DomainEvents", out var value) ||
            value is not Queue<IDomainEvent> domainEvents)
        {
            return;
        }

        while (domainEvents.TryDequeue(out var nextEvent))
        {
            await publisher.Publish(nextEvent);
        }
    });
}

注意：上面的代码片段是实际实现的简化版本。

发送电子邮件提醒的后台服务

有一个简单的后台服务，每分钟运行一次，为所有到期的提醒发送电子邮件（ReminderEmailBackgroundService）：

private async void SendEmailNotifications(object? state)
{
    await _fluentEmail
        .To(user.Email)
        .Subject($"{dueReminders.Count} 个提醒到期！")
        .Body($"""
            亲爱的 {user.FirstName} {user.LastName}：

            希望这封邮件能让你安好。

            我写这封邮件是为了提醒你以下几件事：
            {string.Join('\n', dueReminders.Select((reminder, i) => $"{i + 1}. {reminder.Text}"))}

            祝好，
            来自过去的 {user.FirstName}
            """)
        .SendAsync();
}

配置电子邮件设置

要配置服务以发送电子邮件，请确保更新appsettings.json/appsettings.Development.json文件中的电子邮件设置：

你可以使用自己的SMTP服务器或使用像Brevo这样的服务。

手动配置电子邮件设置

{
    "EmailSettings": {
        "EnableEmailNotifications": false,
        "DefaultFromEmail": "your-email@gmail.com（同时，将EnableEmailNotifications改为true 👆）",
        "SmtpSettings": {
            "Server": "smtp.gmail.com",
            "Port": 587,
            "Username": "your-email@gmail.com",
            "Password": "your-password"
        }
    }
}

注意：你可能需要允许不太安全的应用访问你的电子邮件账户。

通过用户机密配置电子邮件设置

dotnet user-secrets --project src/CleanArchitecture.Api set EmailSettings:EnableEmailNotifications true
dotnet user-secrets --project src/CleanArchitecture.Api set EmailSettings:DefaultFromEmail amantinband@gmail.com
dotnet user-secrets --project src/CleanArchitecture.Api set EmailSettings:SmtpSettings:Server smtp-relay.brevo.com
dotnet user-secrets --project src/CleanArchitecture.Api set EmailSettings:SmtpSettings:Port 587
dotnet user-secrets --project src/CleanArchitecture.Api set EmailSettings:SmtpSettings:Username amantinband@gmail.com
dotnet user-secrets --project src/CleanArchitecture.Api set EmailSettings:SmtpSettings:Password your-password