HelloShop on Hi Work Notes

Model Binding

Tue, 10 Mar 2026 15:55:34 +0800

模型绑定最佳实践

实体对象是 EF 中的概念，每个实体对象对应数据库中的一张表。模型对象是 MVC 中的概念，是 HTTP 请求和响应的数据结构。HTTP 请求中通过 URL 参数、表单、标头、 JSON 数据等方式传递数据，这些数据最终会被绑定为模型对象中，模型经过转换为实体对象后，被持久化到数据库中。

public class Product
{
 public int Id { get; set; }
 public string Name { get; set; }
 public decimal Price { get; set; }
}

public class ProductModel
{
 public string Name { get; set; }
 public decimal Price { get; set; }
}

public class ProductController : Controller
{
 private readonly ShopDbContext _context;

 public ProductController(ShopDbContext context)
 {
 _context = context;
 }

 [HttpPost]
 public async Task<IActionResult> Create(ProductModel model)
 {
 if (!ModelState.IsValid)
 {
 return BadRequest(ModelState);
 }

 var product = new Product
 {
 Name = model.Name,
 Price = model.Price
 };

 _context.Products.Add(product);
 await _context.SaveChangesAsync();

 return CreatedAtAction(nameof(Get), new { id = product.Id }, product);
 }
}

针对不同 HTTP 操作，应该使用不同的模型对象，比如创建模型、更新模型、查询模型、删除模型等，这样的好处是可以更好的区分模型对象的职责，比如创建模型只需要包含创建所需的字段，更新模型只需要包含更新所需的字段，查询模型只需要包含查询所需的字段，删除模型只需要包含删除所需的字段，职责单一，维护性好，还可以针对不同的模型提供不同的验证规则。

PostgreSQL 高可用性和读写分离

Tue, 10 Mar 2026 15:55:34 +0800

基本概念

一个操作系统可以安装多个 PostgreSQL 实例，每个实例都有自己的配置文件、数据目录和端口号。每个实例中可以创建多个数据库，每个数据库中可以创建多个表。使用 Docker 可以方便的创建多个 PostgreSQL 实例。

安装主从服务器

docker run --name postgres1 -e POSTGRES_PASSWORD=postgres -d -p 5431:5432 -v ${pwd}/postgres1/data:/var/lib/postgresql/data postgres
docker run --name postgres2 -e POSTGRES_PASSWORD=postgres -d -p 5432:5432 -v ${pwd}/postgres2/data:/var/lib/postgresql/data postgres

逻辑复制

逻辑复制是根据复制标识（通常是主键）复制数据对象及其更改的一种方法。我们使用术语逻辑与物理复制相比，逻辑复制使用发布和订阅模型，其中一个或多个订阅者订阅发布者节点上的一个或多个发布。订阅者从他们订阅的发布中提取数据，并可能随后重新发布数据以允许级联复制或更复杂的配置。

创建主数据库和从数据库

在 postgres1 中创建数据库 mydb1 数据库。

CREATE DATABASE mydb1;

在 postgres2 中创建数据库 mydb2 数据库。

CREATE DATABASE mydb2;

在 mydb1 和 mydb2 数据库中创建结构相同的表 mytable。

CREATE TABLE mytable (id int PRIMARY KEY, name text NOT NULL);

将服务器日志级别设置为逻辑

在 postgres1 的 mydb1 数据库中设置服务器日志级别为逻辑。

Readme

Tue, 10 Mar 2026 15:55:34 +0800

朋友们，零度新一代基架今日正式开始搭建。我们非常激动地宣布，新一代基架起名为 HelloShop 项目，这个基架将演示新一代 .NET 技术栈开发架构，之所以起名为 HelloShop 是以为简单的商店应用能够演示出一个系统的所有技术，当然，这个商城系统也可以是其它系统，只要你能够理解这个基架的设计思想，你就能够快速搭建一个系统，以下文档由 AI 生成，可能会有一些语法错误，我们会在后期进行修正。

业务场景

本商店应用旨在演示一个系统的所有技术，帮助开发者以最小的依赖和代码搭建一个系统，将不同的技术置于微服务架构中。开发者可以根据自己的业务需求快速复用代码并搭建一个系统，而不是花费大量时间在一个通用的框架上。

我们的目标是提供细粒度的微服务架构和最佳实践，让您可以自行组合各种技术。统一的身份认证和授权系统，服务发现，负载均衡，容错，分布式跟踪，分布式缓存，分布式事务，分布式消息，分布式日志，分布式配置，分布式定时任务等等。

此外，我们还提供了界面，包括基于 Blazor 的 Web 应用和基于 MAUI 的混合应用，可以在不同的平台上运行，包括桌面应用，安卓应用和 IOS 应用。

{class=“img-responsive w-100”}

所含技术

Visual Studio 2022、 .NET 8、C# 12.0、Aspire、ASP.NET Core，EF Core、WebApi、gPRC、Blazor、MAUI、PostgreSQL、MonngDB、Redis、SignalR、Identity、Orleans、日志记录、密钥管理、后台定时任务、服务发现、发布订阅、分布式跟踪、健康检查、性能指标探测、配置管理、容器化技术、单元测试和集成测试、基于 Roslyn 的源代码自动生成器和增量生成器。

仓库结构

在仓库的结构上，我们跟随了微软惯用的风格，目录结构如下：

assets 静态资源，包括图片，图标，视频，音频等。

build 构建脚本，包括编译脚本，打包脚本，发布脚本等。

docs 相关文档，包括设计文档，架构文档，开发文档，部署文档等。`

samples 演示示例，包括代码示例，配置示例，数据示例，文档示例等。

src 源代码，包括源代码，配置文件，资源文件，脚本文件等。

tests 测试代码，包括单元测试，集成测试，端到端测试等。

tools 项目所使用的一些工具。

代码仓库

国外仓库：https://github.com/bit365/hello-shop{target="_blank"}

国内仓库：https://gitee.com/bit365/hello-shop{target="_blank"}

后续计划

我们刚刚还注册了 helloshopnet.com 和 helloshopnet.cn 两个域名用于后期的基架部署，也算是给 HelloShop 安一个家，目前还是正在备案。

技术探讨

本套基架会有一些配套视频在 www.xcode.me 上发布。如果你想要获取最新的视频可以关注我们的微信订阅号 zerostack，我们会在公众号上发布最新的动态，如果你觉得这套基架对你有帮助，你可以给我们一个 Star，这是对我们最大的鼓励。

最后我们希望这套基架能帮助到你，如果你有任何问题可以在 Github 上提出我们会尽快回复，坚持优雅的编码是我们一直所追求的，希望你也能够参与这种优雅。

创建代码仓库

Tue, 10 Mar 2026 15:55:34 +0800

仓库命名规范

在 Github 上创建一个名为 HelloShop 的代码仓库，关于代码仓库的命名规范使用，使用 SnakeCaseLower 命名法。

Naming policy	Original	Converted
PascalCase	HelloShop	HelloShop
CamelCase	HelloShop	helloShop
SnakeCaseLower	HelloShop	hello_shop
SnakeCaseUpper	HelloShop	HELLO_SHOP
KebabCaseLower	HelloShop	hello-shop
KebabCaseUpper	HelloShop	HELLO-SHOP

仓库文件夹结构

在仓库中创建一个名为 src 的文件夹，用于存放源代码。

说明文件

在仓库中创建一个名为 README.md 的文件，用于存放仓库的说明文档，当然如果可能每个文件夹都应该有一个说明文档。

忽略文件

gitignore 文件的作用是指定不需要提交到代码仓库的文件，例如编译后的文件、日志文件等。

https://github.com/github/gitignore/blob/main/VisualStudio.gitignore

属性文件

gitattributes 文件的作用是指定文件的属性，例如文件的换行符、文件的编码等。

目录结构

assets 静态资源，包括图片，图标，视频，音频等。

build 构建脚本，包括编译脚本，打包脚本，发布脚本等。

docs 相关文档，包括设计文档，架构文档，开发文档，部署文档等。`

samples 演示示例，包括代码示例，配置示例，数据示例，文档示例等。

src 源代码，包括源代码，配置文件，资源文件，脚本文件等。

tests 测试代码，包括单元测试，集成测试，端到端测试等。

tools 项目所使用的一些工具。

仓库分支

仓库分支用于管理仓库的版本，例如 master，develop，release，hotfix, feature 等。

仓库标签

仓库标签用于标记仓库的版本，例如 v1.0.0，v1.0.1，v1.1.0，v2.0.0 等。

订单微服务架构概述

Tue, 10 Mar 2026 15:55:34 +0800

订单部分使用了很多技术点，这包括 CQRS 模式、MediatR 本地命令分发、本地事件处理、分布式事件的抽象和实现、发件箱模式、分布式锁等技术。

订单服务架构图

微服务通信

客户端部分

客户端部分主要包括了订单的创建、支付、取消、查询等功能。客户端通过 API Gateway 调用订单微服务，订单微服务通过 MediatR 处理命令，然后通过事件总线发布事件，事件总线将事件分发到事件处理器，事件处理器处理事件，然后将事件持久化到数据库。

订单 WebApi 部分

使用 WebApi 作为订单微服务的入口，接收客户端的请求，然后通过 MediatR 处理命令，然后通过事件总线发布事件。

Queries 部分

使用从库来处理查询，从库是一个独立的数据库，用于处理查询，从库的数据是通过流式复制从主库同步过来的，从库的数据是只读的，从库的数据是最终一致的。

Commands 部分

使用命令模式处理订单的创建、支付、取消等命令，命令模式是一个行为设计模式，命令数据最终会被持久化到主数据库。

本地事件

本地事件是指在微服务内部的事件，本地事件是通过 MediatR 发布的，只能在当前微服务内部使用。

分布式事件

分布式事件是指在微服务之间的事件，分布式事件是通过事件总线发布的，可以在多个微服务之间使用，事件的发布和处理是异步的，使用 Dapr 的 Pub/Sub 组件实现事件的发布和订阅，可使用很多种消息队列来实现。

使用分布式锁

使用分布式锁来处理并发问题，分布式锁是通过 Dapr 组件实现的，分布式锁是一个分布式系统中的同步工具，用于解决并发问题，目前 Dapr 的分布式锁是基于 Redis 实现的。

多租户应用程序设计

Tue, 10 Mar 2026 15:55:34 +0800

什么是多租户应用程序

多租户应用程序是一种软件架构设计，允许单个实例的软件服务多个客户，每个客户被称为一个租户，租户之间的数据自动隔离的，租户之间的数据不会相互影响。

零度编程官网搜索「多租户」查看多租户设计视频教程。

单表字段隔离租户数据

单表多租户设计是指在一个表中存储多个租户的数据，通过在表中增加一个租户 TenantId 字段来区分不同租户的数据。

多租户数据查询

public class FieldIsolationServiceDbContext(DbContextOptions<FieldIsolationServiceDbContext> options, ICurrentTenant currentTenant) : DbContext(options)
{
 protected override void OnModelCreating(ModelBuilder modelBuilder)
 {
 modelBuilder.Entity<Product>().Property(p => p.Name).HasMaxLength(32);

 foreach (IMutableEntityType entityType in modelBuilder.Model.GetEntityTypes())
 {
 if (entityType.ClrType.IsAssignableTo(typeof(IMultiTenant)))
 {
 modelBuilder.Entity(entityType.ClrType).AddQueryFilter<IMultiTenant>(e => e.TenantId == currentTenant.TenantId);
 }
 }

 base.OnModelCreating(modelBuilder);
 }

 protected override void OnConfiguring(DbContextOptionsBuilder optionsBuilder)
 {
 optionsBuilder.AddInterceptors(new TenantSaveChangesInterceptor(currentTenant));

 base.OnConfiguring(optionsBuilder);
 }
}

保存数据时自动设置租户编号

private void MultiTenancyTracking(DbContext dbContext)
{
 IEnumerable<EntityEntry<IMultiTenant>> multiTenancyEntries = dbContext.ChangeTracker.Entries<IMultiTenant>().Where(entry => entry.State == EntityState.Added || entry.State == EntityState.Modified);

 multiTenancyEntries?.ToList().ForEach(entityEntry =>
 {
 entityEntry.Entity.TenantId ??= currentTenant.TenantId;
 });
}

多数据库隔离租户数据

多数据库多租户设计是指为每个租户创建一个独立的数据库，通过数据库连接字符串来区分不同租户的数据。


protected override void OnConfiguring(DbContextOptionsBuilder optionsBuilder)
{
 if (currentTenant.TenantId != null)
 {
 string? connectionString = configuration.GetConnectionString(currentTenant.TenantId);

 optionsBuilder.UseNpgsql(connectionString);
 }

 base.OnConfiguring(optionsBuilder);
}

ZeroFramework TenantDbConnectionInterceptor

基于 Schema 的多租户设计

基于 Schema 的多租户设计是指为每个租户创建一个独立的 Schema，通过 Schema 来区分不同租户的数据。

protected override void OnModelCreating(ModelBuilder modelBuilder)
{
 if (currentTenant.TenantId != null)
 {
 modelBuilder.HasDefaultSchema(currentTenant.TenantId);
 }

 base.OnModelCreating(modelBuilder);
}

目前 EF Core 不支持在迁移时自动创建 Schema，需要手动创建 Schema。

分页排序和多条件查询

Tue, 10 Mar 2026 15:55:34 +0800

分页参数

请求应使用 GET 方法

http://localhost:8080/api/products?keyword=test&pagenumber=1&pagesize=5&orderby=id desc,price asc

响应返回如下

{
 "totalCount": 100,
 "items": [
 {
 "id": 1,
 "name": "test",
 "price": 100
 },
 {
 "id": 2,
 "name": "test",
 "price": 200
 }
 ]
}

分页请求模型

public class PagedAndSortedRequest : PagedRequest
{
 public string? OrderBy { get; init; }
}

分页响应模型

public class PagedResponse<T>(IReadOnlyList<T> items, int totalCount)
{
 public IReadOnlyList<T> Items { get; init; } = items;

 public int TotalCount { get; init; } = totalCount;
}

扩展 IQueryable 以便通过属性名称排序

QueryableOrderByExtensions.cs

将字符串条件转化为排序表达式

IOrderedQueryable<TSource> OrderBy(IQueryable<TSource> source, string propertyName)

扩展 IQueryable 以便搜索和排序

QueryableExtensions.cs

扩展分页和排序方法

IQueryable<TEntity> SortBy<TEntity>(this IQueryable<TEntity> query, string? orderBy = null);
IQueryable<TEntity> PageBy<TEntity>(this IQueryable<TEntity> query, PagedRequest pagedRequest)
IQueryable<TEntity> SortAndPageBy<TEntity>(this IQueryable<TEntity> query, PagedAndSortedRequest? pagedAndSortedRequest = null);

再扩展一个 WhereIf 条件查询

IQueryable<TSource> WhereIf<TSource>(this IQueryable<TSource> source, bool condition, Expression<Func<TSource, bool>> predicate);

在 API 控制器中使用扩展方法

[HttpGet]
[Authorize(IdentityPermissions.Users.Default)]
public async Task<ActionResult<PagedResponse<UserListItem>>> GetUsers([FromQuery] UserListRequest model)
{
 IQueryable<User> users = dbContext.Set<User>();

 if (model.Keyword is not null)
 {
 users = users.Where(e => e.UserName != null && e.UserName.Contains(model.Keyword));
 }

 users = users.WhereIf(model.PhoneNumber is not null, e => e.PhoneNumber == model.PhoneNumber);

 var pagedUsers = users.SortAndPageBy(model);

 var list = new List<UserListItem>();

 return new PagedResponse<UserListItem>(mapper.Map<List<UserListItem>>(await pagedUsers.ToListAsync()), await users.CountAsync());
}

实现灵活的复杂查询

可以使用 OData 或者 GraphQL 来实现更复杂的查询。

负载测试和压力测试

Tue, 10 Mar 2026 15:55:34 +0800

负载测试

测试应用是否可以在特定情况下处理指定的用户负载，同时仍满足响应目标，应用在正常状态下运行。

压力测试

在极端条件下（通常为长时间）运行时测试应用的稳定性，测试会对应用施加高用户负载（峰值或逐渐增加的负载）或限制应用的计算资源。压力测试可确定压力下的应用是否能够从故障中恢复，并正常返回到预期的行为，在压力下，应用在异常高的压力下运行。

测试工具

云端测试和 Apache JMeter 是两种流行的负载测试工具。负载测试和压力测试应在发布和生产模式下完成，而不是在调试和开发模式下进行。

使用 Apache JMeter 工具

Apache JMeter 是一个开源的 Java 应用程序，用于执行负载测试、功能测试和性能测试。JMeter 可以模拟多种类型的负载，包括负载测试、压力测试、功能测试、基准测试等。

提供强大的图形化界面，可以通过图形化界面创建测试计划，然后执行测试计划。JMeter 支持多种协议，包括 HTTP、HTTPS、FTP、JMS、SOAP、TCP 和 LDAP，还可以通过插件支持其他协议。

https://jmeter.apache.org/usermanual/build-web-test-plan.html

基准测试

基准测试是一种测试方法，用于确定应用程序的性能基准，以便在应用程序的生命周期中进行性能优化。使用 BenchmarkDotNet 可以在 .NET 应用程序中进行基准测试。

dotnet add package BenchmarkDotNet

public class Md5VsSha256
{
 [Benchmark]
 public byte[] Sha256() => sha256.ComputeHash(data);

 [Benchmark]
 public byte[] Md5() => md5.ComputeHash(data);
}

public class Program
{
 public static void Main(string[] args)
 {
 BenchmarkRunner.Run<Md5VsSha256>();
 }
}

更新 .NET 8.0 到 .NET 9.0

Tue, 10 Mar 2026 15:55:34 +0800

更新 Visual Studio 最新预览版

下载并安装 Visual Studio 预览版，安装 .NET 9.0 SDK。

更新项目文件

打开项目文件，将 <TargetFramework>net8.0</TargetFramework> 更新为 <TargetFramework>net9.0</TargetFramework>。

更新 NuGet 包

打开 NuGet 包管理器，更新所有 NuGet 包到最新版本。

更新 Aspire 和 MAUI 工作负载

打开 Aspire 工作负载，更新所有 Aspire 包到最新版本。

dotnet workload install aspire android ios maccatalyst maui-android maui-desktop maui-mobile maui-windows

若要将 Tab 自动补全添加到适用于 .NET CLI 的 PowerShell

https://learn.microsoft.com/zh-cn/dotnet/core/tools/enable-tab-autocomplete

关于 Aspire 应用宿主的编排

Tue, 10 Mar 2026 15:55:34 +0800

通过 Add 方法添加应用组件

通过 AddProject、AddContainer、AddExecutable、AddParameter，AddConnectionString 等方法，可以将应用宿主编排为一个完整的应用。

配置显式资源启动

builder.AddProject<Projects.MyApp>("dbmigration").WithExplicitStart();

使用 WithExplicitStart 方法，可以配置显式资源启动，显式资源启动的资源需要手动启动。

资源的引用通过 WithReference 方法

builder.AddProject<Projects.MyApp>("myapp").WithReference(postgresdb);

被引用资源可以是一个终结点，连接字符串，或者其他资源，所引用的资源会通过环境变量的方式传递给引用资源。

等待资源启动和完成

builder.AddProject<Projects.MyApp>("myapp").WithWaitFor(postgresdb);

builder.AddProject<Projects.MyApp>("myapp").WithWaitForCompletion("dbmigration");

自定义容器的启动参数

var cache = builder.AddRedis("cache").WithImageTag("latest");

容器资源生存期

var cache1 = builder.AddRedis("cache1").WithLifetime(ContainerLifetime.Persistent);
var cache2 = builder.AddRedis("cache1").WithLifetime(ContainerLifetime.Session);

Persistent 表示容器资源的生存期为持久，Session 表示容器资源的生存期为会话。

外部参数

在 Host 项目的 appsettings.json 配置文件中添加如下节点。

{
 "Parameters": {
 "myvalue": "local-value"
 }
}

var value1 = builder.AddParameter("myvalue");
var value2 = builder.AddParameter("myvalue", secret: true);

builder.AddProject<Projects.ApiService>("api").WithEnvironment("EXAMPLE_VALUE", value1);

外部连接字符串

在 Host 项目的 appsettings.json 配置文件中添加如下节点。

{
 "ConnectionStrings": {
 "myconnection": "Server=myserver;Database=mydb;User=myuser;Password=mypassword;"
 }
}

var connection = builder.AddConnectionString("myconnection");

builder.AddProject<Projects.ApiService>("api").WithReference(connection);

终结点引用

var builder = DistributedApplication.CreateBuilder(args);

var customContainer = builder.AddContainer("myapp", "mycustomcontainer").WithHttpEndpoint(port: 9043, name: "endpoint");

var endpoint = customContainer.GetEndpoint("endpoint");

var apiservice = builder.AddProject<Projects.AspireApp_ApiService>("apiservice").WithReference(endpoint);

在 Redis 组件上启用管理扩展

var redis = builder.AddRedis("redis").WithRedisInsight();
var redis = builder.AddRedis("redis").WithRedisCommander();

注册生命周期钩子

using Aspire.Hosting.Lifecycle;
using Microsoft.Extensions.Logging;

var builder = DistributedApplication.CreateBuilder(args);

builder.Services.AddLifecycleHook<LifecycleLogger>();

builder.Build().Run();

class LifecycleLogger(ILogger<LifecycleLogger> logger): IDistributedApplicationLifecycleHook
{
 public Task BeforeStartAsync(DistributedApplicationModel appModel, CancellationToken cancellationToken = default)
 {
 logger.LogInformation("BeforeStartAsync");
 return Task.CompletedTask;
 }

 public Task AfterEndpointsAllocatedAsync(
 DistributedApplicationModel appModel, CancellationToken cancellationToken = default)
 {
 logger.LogInformation("AfterEndpointsAllocatedAsync");
 return Task.CompletedTask;
 }

 public Task AfterResourcesCreatedAsync(
 DistributedApplicationModel appModel, CancellationToken cancellationToken = default)
 {
 logger.LogInformation("AfterResourcesCreatedAsync");
 return Task.CompletedTask;
 }
}

网络模型和多副本启动

builder.AddProject<Projects.Networking_Frontend>("frontend")
 .WithHttpEndpoint(port: 5066, IsExternal: true, IsProxied: true)
 .WithReplicas(2);

IsExternal 和 IsProxied 属性决定了终结点的管理和公开方式，IsExternal 为 true 时，终结点会被公开，IsProxied 为 true 时，终结点会被代理。

基于策略和资源的授权机制

Tue, 10 Mar 2026 15:55:34 +0800

身份认证完成后 HttpContext.User 中包含了用户的身份信息，但是用户的身份信息并不包含用户的权限信息。用户的权限信息需要通过授权系统来获取。

ASP.NET Core 中的授权系统

ASP.NET Core 中的授权系统是基于策略的授权系统，可以通过声明式的方式来定义授权策略。授权策略可以基于角色，也可以基于资源，也可以基于其他的条件。授权策略可以通过声明式的方式来定义，也可以通过代码的方式来定义。

使用 IAuthorizationService 接口

IAuthorizationService 接口是 ASP.NET Core 中的授权服务接口，可以通过该接口来进行授权操作。IAuthorizationService 接口提供了多个授权方法，可以通过这些方法来进行授权操作。

public interface IAuthorizationService
{
 Task<AuthorizationResult> AuthorizeAsync(ClaimsPrincipal user, object resource, IEnumerable<IAuthorizationRequirement> requirements);
 Task<AuthorizationResult> AuthorizeAsync(ClaimsPrincipal user, object resource, string policyName);
 Task<AuthorizationResult> AuthorizeAsync(ClaimsPrincipal user, object resource, AuthorizationPolicy policy);
}

AuthorizationResult 是授权结果，包含了授权的结果和失败的原因。

实现授权策略提供者

使用 OperationAuthorizationRequirement 表示授权条件，将上一期视频中的权限定义转成授权条件提供给系统，一个策略中本可以有多个条件，但为了简单这里的策略中只加一个条件。

需要注意的是，多个策略是 OR 的关系，多个条件是 AND 的关系。


public class CustomAuthorizationPolicyProvider(IOptions<AuthorizationOptions> options, IPermissionDefinitionManager permissionDefinitionManager) : DefaultAuthorizationPolicyProvider(options)

实现资源表示

public interface IAuthorizationResource
{
 string ResourceType => GetType().Name;

 string ResourceId => GetType().GetProperty("Id")?.GetValue(this)?.ToString() ?? throw new NotImplementedException();
}

设计一个表示资源的记录类

一般来说，实体类型就是一种资源，可以直接从 IAuthorizationResource 接口实现，但为了方便表示资源，可以设计一个表示资源的记录类。

public record struct ResourceInfo : IAuthorizationResource

实现授权条件处理器

public class PermissionRequirementHandler(IPermissionChecker permissionChecker) : AuthorizationHandler<OperationAuthorizationRequirement>
public class ResourcePermissionRequirementHandler(IPermissionChecker permissionChecker) : AuthorizationHandler<OperationAuthorizationRequirement, IAuthorizationResource>

protected abstract Task HandleRequirementAsync(AuthorizationHandlerContext context, TRequirement requirement);
protected abstract Task HandleRequirementAsync(AuthorizationHandlerContext context, TRequirement requirement, TResource resource);

在授权处理器中使用 IPermissionChecker

public class PermissionRequirementHandler(IPermissionChecker permissionChecker) : AuthorizationHandler<OperationAuthorizationRequirement>
{
 private readonly IPermissionChecker _permissionChecker;

 public PermissionRequirementHandler(IPermissionChecker permissionChecker)
 {
 _permissionChecker = permissionChecker;
 }

 protected override async Task HandleRequirementAsync(AuthorizationHandlerContext context, OperationAuthorizationRequirement requirement)
 {
 if (await _permissionChecker.IsGrantedAsync(context.User, requirement.Name))
 {
 context.Succeed(requirement);
 }
 }
}

基于资源授权的最佳实践

Tue, 10 Mar 2026 15:55:34 +0800

在 Identity Service 中提供权限检查接口

[HttpHead]
public async Task<IActionResult> CheckPermission(string permissionName, string? resourceType = null, string? resourceId = null
{
 if (await permissionChecker.IsGrantedAsync(permissionName, resourceType, resourceId))
 {
 return Ok();
 }

 return Forbid();
}

远程权限检查器

Dictionary<string, string?> parameters = new()
{
 [nameof(name)] = name,
 [nameof(resourceType)] = resourceType,
 [nameof(resourceId)] = resourceId
};

string queryString = QueryHelpers.AddQueryString(string.Empty, parameters);

HttpRequestMessage request = new(HttpMethod.Head, queryString);

using HttpResponseMessage response = await httpClient.SendAsync(request);

return response.IsSuccessStatusCode;

重新实现权限处理程序

public class PermissionRequirementHandler(IPermissionChecker permissionChecker) : AuthorizationHandler<OperationAuthorizationRequirement>
{
 protected override async Task HandleRequirementAsync(AuthorizationHandlerContext context, OperationAuthorizationRequirement requirement)
 {
 if (context.Resource is IAuthorizationResource resource)
 {
 if (await permissionChecker.IsGrantedAsync(context.User, requirement.Name, resource.ResourceType, resource.ResourceId))
 {
 context.Succeed(requirement);
 }
 else
 {
 context.Fail();
 }

 return;
 }

 if (await permissionChecker.IsGrantedAsync(context.User, requirement.Name))
 {
 context.Succeed(requirement);
 return;
 }

 context.Fail();
 }
}

取消缓存以便测试

await distributedCache.SetObjectAsync(cacheKey, new PermissionGrantCacheItem(isGranted), new DistributedCacheEntryOptions
{
 AbsoluteExpiration = DateTimeOffset.Now
});

可读性重构

重新生成演示数据，并将授权中的 Name 改为 PermissionName，具有更强的可读性。

聚合 API 网关

Tue, 10 Mar 2026 15:55:34 +0800

使用网关可将多个单独请求聚合成一个请求。当客户端必须向不同的后端系统发出多个调用来执行某项操作时，此模式非常有用。

上下文和问题

在某些情况下，客户端需要向多个后端系统发出多个请求。例如，客户端可能需要从多个服务中检索数据，然后将这些数据聚合到一个响应中。在这种情况下，客户端必须发出多个请求，这可能会导致性能问题。此外，客户端还必须处理多个响应，这可能会导致复杂性问题。

解决方案

使用网关减少客户端与服务之间的通信频率。网关会接收客户端请求，将请求分派到不同的后端系统，然后聚合结果并将其返回给请求客户端。此模式可以减少应用程序向后端服务发出的请求数，并通过高延迟网络改进应用程序的性能。

权限聚合

public interface IPermissionService
{
 Task<IReadOnlyList<PermissionGroupDefinitionResponse>> GetAllPermissionDefinitionsAsync(CancellationToken cancellationToken=default);
}

重构用户和角色控制器

修改 UsersController 从 IdentityServiceDbContext 更改为 UserManager<User>

实现 RolesController 使用 RoleManager<Role>

UserCreateRequestValidator 从 IdentityServiceDbContext 更改为 UserManager<User>

权限定义端点返回的 Json 中 name 属性更改为 groupName

远程权限检查 BUG 修复

public async Task<IActionResult> CheckPermission(int roleId, string permissionName, string? resourceType = null, string? resourceId = null)

注意事项

网关不应在后端服务之间造成服务耦合。
网关应靠近后端服务，以尽量降低延迟。
网关服务可能会造成单一故障点。请确保网关设计合理，符合应用程序的可用性要求。
网关可能造成瓶颈。请确保网关可提供足够的性能来处理负载，并可根据预期的发展进行缩放。
对网关执行负载测试，确保不会对服务造成连锁故障。
使用隔舱、断路、重试和超时等技术实施弹性设计。
如果一个或多个服务调用花费的时间过长，那么超时并返回部分数据集是可以接受的。请考虑应用程序处理这种情况的方式。
使用异步 I/O 来确保后端延迟不会导致应用程序中出现性能问题。
使用关联 ID 实施分布式跟踪，以跟踪每个调用。
监视请求指标和响应大小。
考虑返回缓存的数据（作为故障转移策略）来处理故障。
不要在网关中内置聚合，而应考虑将聚合服务放在网关后面。请求聚合的资源要求可能与网关中其他服务不同，并可能影响网关的路由和卸载功能。

聚合 OpenApi 文档

Tue, 10 Mar 2026 15:55:34 +0800

每个微服务都有自己的 OpenApi 文档，但是在实际开发中，我们更希望能够将所有微服务的 OpenApi 文档聚合到一起，以便于查看和调试，微服务都是基于 Aspire 框架开发的，所以我们可以使用 Aspire 框架提供的服务发现功能来自动聚合所有微服务的 OpenApi 文档。

使用 Aspire 服务发现自动配置 OpenApi 文档

public class OpenApiConfigureOptions() : IConfigureOptions<SwaggerUIOptions>

builder.Services.AddTransient<IConfigureOptions<SwaggerUIOptions>, OpenApiConfigureOptions>();

定制 OpenApi 文档样式

在 Resource/OpenApi 文件夹下创建 Custom.css 文件。

.swagger-ui .topbar-wrapper img {
 content: url('https://test.com/logo.svg');
}

.swagger-ui .topbar-wrapper .link::after {
 margin-left: 0.5rem;
 content: "HelloWorld";
}

关联 CSS 文件到 OpenApi 文档

public static class OpenApiExtensions
{
 public static IServiceCollection AddOpenApi(this IServiceCollection)
 {
 services.Configure<SwaggerUIOptions>(options =>
 {
 options.DocumentTitle = Assembly.GetExecutingAssembly().GetName().Name;
 options.InjectStylesheet("/ServiceDefaults/Resources/OpenApi/Custom.css");
 });
 }
}

public static IApplicationBuilder UseOpenApi(this IApplicationBuilder app)
{
 // Configure the HTTP request pipeline.
 app.UseSwagger(apiConfigureOptions)
 app.Map("/ServiceDefaults", appBuilder => appBuilder.UseStaticFiles(new StaticFileOptions
 {
 FileProvider = new EmbeddedFileProvider(Assembly.GetExecutingAssembly())
 }))

 return app;
}

零度框架升级到 Aspire 13.0 版本

Tue, 10 Mar 2026 15:55:34 +0800

简化解决方案文件格式

从 sln 到 slnx，新的 slnx 格式更易于阅读和维护，减少了冗余信息，使得项目结构更加清晰。

dotnet sln migrate

同时修改 slnf 中引用的 sln 文件为 slnx 文件。

将项目目标框架升级到 .NET 10 版本

在项目文件中将目标框架从 net9.0 修改为 net10.0：

<TargetFramework>net10.0</TargetFramework>

将 Aspire 升级到 13.0.0 版本

在项目文件中将 Aspire 包的版本号更新为 13.0.0

- <Project Sdk="Microsoft.NET.Sdk">
+ <Project Sdk="Aspire.AppHost.Sdk/13.0.0">

- <Sdk Name="Aspire.AppHost.Sdk" Version="9.5.2" />

 <PropertyGroup>
 <OutputType>Exe</OutputType>
- <TargetFramework>net9.0</TargetFramework>
+ <TargetFramework>net10.0</TargetFramework>
 <ImplicitUsings>enable</ImplicitUsings>
 <Nullable>enable</Nullable>
- <IsAspireHost>true</IsAspireHost>
 <UserSecretsId>0afc20a6-cd99-4bf7-aae1-1359b0d45189</UserSecretsId>
 </PropertyGroup>

 <ItemGroup>
- <PackageReference Include="Aspire.Hosting.AppHost" Version="9.5.2" />
+ <!-- Aspire.Hosting.AppHost is now included automatically by the SDK -->
 </ItemGroup>

</Project>

将中央包 Directory.Packages.props 中的包更到最新

列出所有需要更新的包

零度框架升级到 Aspire 9.0 版本

Tue, 10 Mar 2026 15:55:34 +0800

升级 Visual Studio 开发工具

使用 Visual Studio Installer 升级，升级到 v17.12 后，自动安装 .NET 9.0 SDK 和 Aspire 9.0 工作负载。

非 Visual Studio 开发环境

安装 .NET Core SDK 9.0 版本

安装最新 .NET SDK 9.0 版

查看 .NET SDK 版本：

dotnet --version
dotnet --list-sdks

升级 Aspire 工作负载

在项目目录下执行以下命令：

dotnet workload uninstall aspire
dotnet workload install aspire
dotnet workload list
dotnet workload update

升级项目文件

Host 项目添加新节点：

<Sdk Name="Aspire.AppHost.Sdk" Version="9.0.0" />

所有项目文件的目标框架改为 net9.0：

<TargetFramework>net9.0</TargetFramework>

安装 EF Core 基础包

零度框架升级到 Aspire 9.3 版本

Tue, 10 Mar 2026 15:55:34 +0800

从 Host 项目删除 IsAspireHost 属性

<IsAspireHost>true</IsAspireHost>

工作负载升级

dotnet workload update

升级 Visual Studio 到最新版

通过 Visual Studio Installer 升级到最新版本。

可使用 AI 升级项目

GitHub Copilot 应用现代化 - 适用于 .NET 的升级是一个功能强大的 Visual Studio 扩展，可与你配合使用，将项目升级到较新版本的 .NET、升级依赖项并应用代码修复。

GitHub Copilot 应用程序现代化作为 Visual Studio 扩展分发，是一个交互式升级过程。

GitHub Copilot app modernization - upgrade for .NET

更新项目模板

dotnet new update

使用升级助手将项目升级到最新

dotnet tool install -g UpgradeAssistant
dotnet upgrade-assistant upgrade

也可以使用 Visual Studio 的升级助手。

关于 CPM 中央包管理的升级

CPM 中央包管理的升级是一个重要的更新，允许您在项目中使用中央包版本管理，升级 CPM 目前需要手动更新。

零度框架中的测试

Tue, 10 Mar 2026 15:55:34 +0800

使用自动测试是确保应用程序代码按作者期望执行操作的一种绝佳方式。零度框架中提供单元测试、集成测试和负载测试，.NET 平台上的测试框架有 xUnit、NUnit 和 MSTest，用的最多的是 xUnit，无论使用任何一种测试框架，都可以通过命令行或者 IDE 来运行测试。

单元测试

单元测试是一种试验单个软件组件或方法（也称为“工作单元”）的测试。单元测试仅应测试开发人员控件内的代码。它们不测试基础结构问题。基础结构问题包括与数据库、文件系统和网络资源的交互，零度框架中的单元测试使用 xUnit 框架，

项目命名规范： <ProjectName>.UnitTests。

public class Calculator
{
 public int Add(int a, int b)
 {
 return a + b;
 }
}

public class CalculatorTests
{
 [Fact]
 public void Add_WhenCalled_ReturnsTheSumOfArguments()
 {
 // Arrange
 var calculator = new Calculator();

 // Act
 var result = calculator.Add(1, 2);

 // Assert
 Assert.Equal(3, result);
 }
}

单元测试最佳做法

https://learn.microsoft.com/zh-cn/dotnet/core/testing/unit-testing-best-practices

集成测试

集成测试也称为功能测试，与单元测试的不同之处在于，它试验两个或更多软件组件一同工作集成能力。这些测试在更广泛范围的受测系统上运行，而单元测试则侧重于单个组件函数，通常，集成测试会包括对基础结构问题的测试，例如数据库、文件系统和网络资源的交互。

项目命名规范： <ProjectName>.FunctionalTests。

public class Controller: ControllerBase
{
 private readonly IService _service;

 public Controller(IService service)
 {
 _service = service;
 }

 [HttpGet]
 public async Task<IActionResult> Get(int id)
 {
 var result = await _service.Get(id);
 return Ok(result);
 }
}

public class Service: IService
{
 public async Task<Model> Get(int id)
 {
 return await _repository.Get(id);
 }
}

public class ServiceTest: IClassFixture<WebApplicationFactory<Startup>>
{
 private readonly WebApplicationFactory<Startup> _factory;

 public ServiceTest(WebApplicationFactory<Startup> factory)
 {
 _factory = factory;
 }

 [Fact]
 public async Task Get_WhenCalled_ReturnsModel()
 {
 // Arrange
 var client = _factory.CreateClient();
 var response = await client.GetAsync("/api/controller/1");
 response.EnsureSuccessStatusCode();
 var model = await response.Content.ReadAsAsync<Model>();

 // Assert
 Assert.NotNull(model);
 }
}

模型自动验证机制

Tue, 10 Mar 2026 15:55:34 +0800

模型验证是 ASP.NET Core MVC 中的一个重要特性，它可以帮助我们验证用户输入的数据是否符合预期。

基于数据注解的验证

参考微软数据注解文档。

public class User
{
 [Required]
 [StringLength(32)]
 public string Name { get; set; }

 [Required]
 [EmailAddress]
 public string Email { get; set; }
}

基于链式调用的验证

FluentValidation 是一个.NET库，用于构建类型安全的验证规则。它的设计目标是提供一个简单、清晰的API，同时还能够支持复杂的验证规则。

参考 FluentValidation 官方文档。

dotnet add package FluentValidation.AspNetCore

实现验证器

public class UserValidator : AbstractValidator<User>
{
 public UserValidator()
 {
 RuleFor(x => x.Name).NotEmpty().MaximumLength(32);
 RuleFor(x => x.Email).NotEmpty().EmailAddress();
 }
}

自动依赖注入

services.AddValidatorsFromAssembly(assembly).AddFluentValidationAutoValidation();

ValidatorOptions.Global.LanguageManager = new CustomFluentValidationLanguageManager();

自定义验证错误消息

public class UserValidator : AbstractValidator<User>
{
 public UserValidator()
 {
 RuleFor(x => x.Name).NotEmpty().MaximumLength(32).WithMessage("Name is required and must be less than 32 characters.");
 RuleFor(x => x.Email).NotEmpty().EmailAddress().WithMessage("Email is required and must be a valid email address.");
 }
}

自定义验证逻辑

public class UserCreateRequestValidator : AbstractValidator<UserCreateRequest>
{
 public UserCreateRequestValidator(IdentityDbContext context)
 {
 RuleFor(m => m.UserName).NotNull().NotEmpty().Length(5, 20).Matches("^[a-zA-Z]+$");
 RuleFor(m => m.PhoneNumber).NotNull().NotEmpty().Length(11).Matches(@"^1\d{10}$").Must((model, phoneNumber) =>
 {
 return !context.Users.Any(e => e.PhoneNumber == phoneNumber);
 });
 RuleFor(m => m.Password).NotNull().NotEmpty().Length(5, 20);
 RuleFor(m => m.Email).EmailAddress().Length(5, 50);
 }
}

通用错误消息

public class CustomFluentValidationLanguageManager : FluentValidation.Resources.LanguageManager
{
 public CustomFluentValidationLanguageManager()
 {
 AddTranslation("en", "NotNullValidator", "The {PropertyName} field is required.");
 AddTranslation("en", "MaximumLengthValidator", "The {PropertyName} field must be less than {MaxLength} characters.");
 AddTranslation("en", "EmailAddressValidator", "The {PropertyName} field must be a valid email address.");
 }
}

全球化与本地化

Tue, 10 Mar 2026 15:55:34 +0800

全球化是指 Web 应用程序能够适应不同的文化和地区，而不需要修改代码。本地化是指 Web 应用程序能够根据用户的文化和地区显示不同的内容。全球化和本地化是两个不同的概念，但是经常一起使用。

实现多语言的方法有很多种，可以使用资源文件、数据库、配置文件等方式，本文主要介绍使用资源文件的方式实现多语言，也是微软官方推荐的方式。其它的比如 PO 文件、JSON 文件等也可以实现多语言，但是不如资源文件方便.

创建资源文件

Welcome.en-US.resx
Welcome.zh-CN.resx

添加本地化服务和资源定位

public static IServiceCollection AddCustomLocalization(this IServiceCollection services)
{
 services.AddLocalization(options => options.ResourcesPath = "Resources");

 return services;
}

使用本地化服务

public class HelloWorldController(IStringLocalizerFactory stringLocalizerFactory) : ControllerBase
{
 [HttpGet]
 public IActionResult Get()
 {
 var location = Assembly.GetExecutingAssembly().FullName;

 ArgumentException.ThrowIfNullOrWhiteSpace(location);

 var localizer = stringLocalizerFactory.Create("Welcome", location);

 return Ok(localizer["HelloWorld"].Value);
 }
}

使用 HTTP 请求设置语言

UseRequestLocalization 中间件从请求中获取语言设置，然后设置当前线程的语言，以便在后续的请求中使用，这样就可以实现全局的本地化，而不需要在每个控制器中设置本地化。

public static IApplicationBuilder UseCustomLocalization(this IApplicationBuilder app)
{
 var supportedCultures = new[] { "zh-CN", "en-US" };

 var localizationOptions = new RequestLocalizationOptions().SetDefaultCulture(supportedCultures.First())
 .AddSupportedCultures(supportedCultures)
 .AddSupportedUICultures(supportedCultures);

 app.UseRequestLocalization(localizationOptions);

 return app;
}

使用下面的方式从 Header 、 QueryString 或者 Cookie 中获取语言设置：

Accept-Language: en-US

http://localhost:5000/?culture=en-Us

.AspNetCore.Culture=en-US

OpenApi 设置 Accept-Language 以实现多语言

services.Configure<SwaggerGenOptions>(options => options.OperationFilter<AcceptLanguageHeaderOperationFilter>());

public class AcceptLanguageHeaderOperationFilter : IOperationFilter
{
 public void Apply(OpenApiOperation operation, OperationFilterContext context)
 {
 var parameter = new OpenApiParameter
 {
 Name = HeaderNames.AcceptLanguage,
 In = ParameterLocation.Header,
 Required = false,
 Schema = new OpenApiSchema
 {
 Default = new OpenApiString("zh-CN"),
 Type = "string",
 Enum = [new OpenApiString("zh-CN"), new OpenApiString("en-US")]
 }
 };

 operation.Parameters.Add(parameter);
 }
}

实现数据展示的全球化


public class HelloWorldController(IStringLocalizerFactory stringLocalizerFactory) : ControllerBase
{
 [HttpGet("time")]
 public IActionResult GetTime(
 {
 //string amount=88.88.ToString("C");
 return Ok(TimeProvider.System.GetUtcNow().ToString());
 }
}

实现模型和属性的本地化

 IStringLocalizerFactory localizerFactory = app.ApplicationServices.GetRequiredService<IStringLocalizerFactory>();

 ValidatorOptions.Global.DisplayNameResolver = (type, memberInfo, lambdaExpression) =>
 {
 string displayName = memberInfo.Name;

 DisplayAttribute? displayAttribute = memberInfo.GetCustomAttribute<DisplayAttribute>(true);

 displayName = displayAttribute?.Name ?? displayName;

 DisplayNameAttribute? displayNameAttribute = memberInfo.GetCustomAttribute<DisplayNameAttribute>(true);

 displayName = displayNameAttribute?.DisplayName ?? displayName;

 var localizer = localizerFactory.Create(type);

 return localizer[displayName];
 };

本地化验证错误消息

public UserCreateRequestValidator(IdentityServiceDbContext dbContext, IStringLocalizer<UserCreateRequest> localizer)
{
 RuleFor(m => m.PhoneNumber).NotNull().NotEmpty().Length(11).Matches(@"^1\d{10}$").Must((model, phoneNumber) =>
 {
 return !dbContext.Users.Any(e => e.PhoneNumber == phoneNumber);
 }).WithMessage(localizer["PhoneNumberExists"]);
}

微软 Resx 编辑工具

必应搜索 Resx Editor 关键字可以找到很多工具，可以编辑 Resx 文件。

设计权限定义和权限提供者

Tue, 10 Mar 2026 15:55:34 +0800

权限定义

每个微服务是自治的，权限定义也是每个微服务的职责，各自定义自己的权限，权限管理器会自动合并权限定义，权限定义上下文是微服务内的权限定义和全局权限定义的合集，权限提供者会根据权限定义上下文提供权限数据，权限分组是为了方便权限定义的管理，权限分组是权限定义的一部分，权限提供者自动注入到容器，提供权限查询端点。

架构设计

权限扩展方法

IServiceCollection AddPermissionDefinitions(this IServiceCollection services)

EndpointRouteBuilder MapPermissionDefinitions(this IEndpointRouteBuilder endpoints, params string[] tags)

身份认证系统

Tue, 10 Mar 2026 15:55:34 +0800

ASP.NET Core Identity 体系结构

ASP.NET Core Identity 是一个成熟的身份认证系统，它提供了用户管理、角色管理、声明管理、密码管理、登录管理、外部登录管理、双重身份认证、电子邮件确认、电话号码确认、安全令牌管理、用户锁定、用户解锁、用户注销、用户删除、用户恢复等功能。

Identity 体系结构说明

实体类型	说明
`User`	表示用户。
`Role`	表示角色。
`UserClaim`	表示用户拥有的声明。
`UserToken`	表示用户的身份验证令牌。
`UserLogin`	将用户与登录名相关联。
`RoleClaim`	表示向角色内的所有用户授予的声明。
`UserRole`	关联用户和角色的联接实体。

使用 EfCore 存储 Identity 数据

定义实体类型

public class User : IdentityUser<int>
{
 public DateTimeOffset CreationTime { get; set; } = DateTimeOffset.UtcNow;
}

public class Role : IdentityRole<int>
{
 public DateTimeOffset CreationTime { get; set; } = DateTimeOffset.UtcNow;
}

配置实体类型

public class UserEntityTypeConfiguration : IEntityTypeConfiguration<User>
{
 public void Configure(EntityTypeBuilder<User> builder)
 {
 builder.ToTable("Users");
 builder.HasKey(x => x.Id);
 builder.Property(x => x.CreationTime);
 }
}

复用 Identity 数据库上下文

dotnet add package Microsoft.AspNetCore.Identity.EntityFrameworkCore

public class IdentityServiceDbContext(DbContextOptions<IdentityServiceDbContext> options) : IdentityDbContext<User, Role, int>(options)
{
 protected override void OnModelCreating(ModelBuilder builder)
 {
 base.OnModelCreating(builder);
 builder.ApplyConfigurationsFromAssembly(Assembly.GetExecutingAssembly());
 AppContext.SetSwitch("Npgsql.EnableLegacyTimestampBehavior", true);
 AppContext.SetSwitch("Npgsql.DisableDateTimeInfinityConversions", true);
 }
}

使用 Identity API 终结点

builder.Services.AddIdentityApiEndpoints<User>(options => {
 options.Password.RequireDigit = false;
 options.Password.RequireLowercase = false;
 options.Password.RequireUppercase = false;
 options.Password.RequireNonAlphanumeric = false;
 options.Password.RequiredLength = 5;
 options.SignIn.RequireConfirmedAccount = false;
}).AddEntityFrameworkStores<IdentityServiceDbContext>();

app.MapGroup("identity").MapIdentityApi<User>();

操作 Identity 数据

UserManager、RoleManager、SignInManager、PasswordValidator 等服务都可以用来操作 Identity 数据，没有特殊情况不建议使用 DbContext 直接操作 Identity 数据。

实现 CQRS 中的 Query 模式

Tue, 10 Mar 2026 15:55:34 +0800

在 CQRS 模式的全程是 Command Query Responsibility Segregation，即命令查询职责分离。在 CQRS 模式中，命令和查询是分开实现的，命令负责写操作，查询负责读操作，这样可以更好地实现单一职责原则，同时也可以更好地实现性能优化。

https://learn.microsoft.com/zh-cn/azure/architecture/patterns/cqrs

https://www.xcode.me/Training/UnitNote/576

定义订单查询接口

public interface IOrderQueries
{
 Task<OrderDetails> GetOrderAsync(int id);
}

实现订单查询接口

public class OrderQueries : IOrderQueries
{
 private readonly OrderingContext _context;

 public OrderQueries(OrderingContext context)
 {
 _context = context;
 dbContext.Database.SetConnectionString("db2_connection_string");
 }

 public async Task<OrderDetails> GetOrderAsync(int id)
 {
 // do something
 }
}

注册订单查询接口

services.AddScoped<IOrderQueries, OrderQueries>();

使用订单查询接口

public class OrderController : ControllerBase
{
 private readonly IOrderQueries _orderQueries;

 public OrderController(IOrderQueries orderQueries)
 {
 _orderQueries = orderQueries;
 }

 [HttpGet("{id}")]
 public async Task<IActionResult> GetOrderAsync(int id)
 {
 var order = await _orderQueries.GetOrderAsync(id);
 return Ok(order);
 }
}

实现产品管理微服务

Tue, 10 Mar 2026 15:55:34 +0800

创建实体

HelloWorld.ProductService.Entities.Products

Product & CatalogBrand

EfCore 使用 PostgreSQL 数据库

dotnet add package Npgsql.EntityFrameworkCore.PostgreSQL

创建 DbContext 上下文

namespace HelloWorld.ProductService.EntityFrameworks
{
 public class ProductServiceDbContext(DbContextOptions<ProductServiceDbContext> options) : DbContext(options)
 {
 protected override void OnModelCreating(ModelBuilder builder)
 {
 base.OnModelCreating(builder);

 builder.ApplyConfigurationsFromAssembly(Assembly.GetExecutingAssembly());
 }
 }
}

创建实体配置类

namespace HelloWorld.ProductService.EntityFrameworks.EntityConfigurations.Products
{
 public class ProductEntityTypeConfiguration : IEntityTypeConfiguration<Product>
 {
 public void Configure(EntityTypeBuilder<Product> builder)
 {
 builder.ToTable("Products");

 builder.Property(x => x.Name).HasMaxLength(32);

 builder.HasOne(x => x.Brand).WithMany();
 }
 }
}

数据库连接字符串

{
 "ConnectionStrings": {
 "ProductDatabase": "Host=localhost;Port=5432;Database=ProductService;Username=postgres;Password=postgres"
 }
}

注册数据库上下文

builder.Services.AddDbContext<ProductServiceDbContext>(options =>
{
 options.UseNpgsql(builder.Configuration.GetConnectionString(DbConstants.ConnectionStringName));
});

迁移数据库

dotnet tool install --global dotnet-ef
dotnet add package Microsoft.EntityFrameworkCore.Design

dotnet ef migrations add InitialCreate --output-dir EntityFrameworks/Migrations
dotnet ef database update

创建模型

namespace HelloWorld.ProductService.Models.Products
{
 public class ProductCreateRequest
 {
 public required string Name { get; init; }

 public string? Description { get; init; }

 public decimal Price { get; init; }

 public int BrandId { get; init; }

 public string? ImageUrl { get; init; }
 }
}

创建自动映射

namespace HelloWorld.ProductService.AutoMapper
{
 public class ProductsMapConfiguration : Profile
 {
 public ProductsMapConfiguration()
 {
 CreateMap<ProductCreateRequest, Product>();
 CreateMap<ProductUpdateRequest, Product>();
 CreateMap<Product, ProductListItem>().AfterMap((src, dest) => dest.BrandName = src.Brand.Name);
 CreateMap<Product, ProductDetailsResponse>();

 CreateMap<BrandCreateRequest, Brand>();
 CreateMap<BrandUpdateRequest, Brand>();
 CreateMap<Brand, BrandDetailsResponse>();
 CreateMap<Brand, BrandListItem>();
 }
 }
}

创建验证器

namespace HelloWorld.ProductService.Validations.Products
{
 public class BrandUpdateRequestValidator : AbstractValidator<BrandUpdateRequest>
 {
 public BrandUpdateRequestValidator()
 {
 RuleFor(x => x.Id).GreaterThan(0);
 RuleFor(x => x.Name).NotNull().NotEmpty().Length(8, 32);
 }
 }
}

创建控制器


namespace HelloWorld.ProductService.Controllers
{
 [Route("api/[controller]")]
 [ApiController]
 public class ProductsController : ControllerBase
}

定义权限

namespace HelloWorld.ProductService.PermissionProviders
{
 public static class CatalogPermissions

 public class CatalogPermissionDefiitionProvider : IPermissionDefinitionProvider
}

权限本地化

CatalogPermissionDefinitionProvider.en-US.resx
CatalogPermissionDefinitionProvider.zh-CN.resx

实体属性本地化

namespace HelloWorld.ProductService.Entities.Products
{
 public class Product
 {
 [Display(Name = "ProductName")]
 public string Name { get; set; }
 }
}

重复性工作

重复性工作可以通过代码生成工具来减少，例如 Visual Studio 插件， T4 模板， Roslyn 等。

实现权限访问控制列表

Tue, 10 Mar 2026 15:55:34 +0800

授权三要素

主体、资源、操作。例如：用户（主体）对文件（资源）的读写（操作）。主体、资源、操作三者之间的关系称为授权关系，基于这种关系，我们可以将授权关系抽象为一个三元组（主体，资源，操作），这个三元组就是授权的基本单位。

基于角色的访问控制

基于角色的访问控制（Role-Based Access Control，简称 RBAC）是一种访问控制模型，通过角色来控制用户对资源的访问权限。角色是一组权限的集合，用户通过分配角色来获取相应的权限。基于角色的访问控制模型简单易用。还有其它的访问控制模型，如基于属性的访问控制（Attribute-Based Access Control，简称 ABAC）。

权限访问控制列表

权限访问控制列表（Access Control List，简称 ACL）是一种权限控制模型，用于控制用户对资源的访问权限。ACL 通过为每个资源定义一个访问控制列表，来控制用户对资源的操作权限。

ACL 存储设计

public class PermissionGranted
{
 public int Id { get; set; }

 public int RoleId { get; set; }

 public required string PermissionName { get; set; }

 public string? ResourceType { get; set; }

 public string? ResourceId { get; set; }
}

在 DbContext 中配置 ACL 实体

public void Configure(EntityTypeBuilder<PermissionGranted> builder)
{
 builder.ToTable("PermissionGranted");

 builder.Property(x => x.Id);
 builder.Property(x => x.PermissionName).HasMaxLength(64);
 builder.Property(x => x.ResourceType).HasMaxLength(16);
 builder.Property(x => x.ResourceId).HasMaxLength(32);

 builder.HasOne<Role>().WithMany().HasForeignKey(x => x.RoleId).IsRequired();

 builder.HasIndex(x => new { x.RoleId, x.PermissionName, x.ResourceType, x.ResourceId }).IsUnique();
}

权限 ACL 存储设计

public class PermissionGranted
{
 public int Id { get; set; }

 public int RoleId { get; set; }

 public required string PermissionName { get; set; }

 public string? ResourceType { get; set; }

 public string? ResourceId { get; set; }
}

在 DbContext 中配置 ACL 实体

public void Configure(EntityTypeBuilder<PermissionGranted> builder)
{
 builder.ToTable("PermissionGranted");

 builder.Property(x => x.Id);
 builder.Property(x => x.PermissionName).HasMaxLength(64);
 builder.Property(x => x.ResourceType).HasMaxLength(16);
 builder.Property(x => x.ResourceId).HasMaxLength(32);

 builder.HasOne<Role>().WithMany().HasForeignKey(x => x.RoleId).IsRequired();

 builder.HasIndex(x => new { x.RoleId, x.PermissionName, x.ResourceType, x.ResourceId }).IsUnique();
}

设计一个权限检查器

public interface IPermissionChecker
{
 Task<bool> IsGrantedAsync(string name, string? resourceType = null, string? resourceId = null);

 Task<bool> IsGrantedAsync(ClaimsPrincipal claimsPrincipal, string name, string? resourceType = null, string? resourceId = null);
}

实现抽象的权限检查器

遍历每个角色的权限，如果有一个角色拥有该权限，则返回 true，表示授权通过。

使用 Aspire 启动分布式微服务

Tue, 10 Mar 2026 15:55:34 +0800

准备数据库

docker run --name postgres -e POSTGRES_PASSWORD=postgres -e TZ=Asia/Shanghai -d -p 5432:5432 postgres

docker run --name pgadmin -e PGADMIN_DEFAULT_EMAIL=test@test.com -e PGADMIN_DEFAULT_PASSWORD=test -e TZ=Asia/Shanghai -d -p 5050:80 dpage/pgadmin4

初始化 Dapr 运行时

dapr init -s --from-dir C:\dapr

延长等待 RabbitMQ 启动时间

public static IResourceBuilder<IDaprSidecarResource> WithReference(this IResourceBuilder<IDaprSidecarResource> builder, IResourceBuilder<IResourceWithConnectionString> resourceBuilder, int waitInSeconds = 10)

修改 MediatR 依赖注入

之前使用 options.AddBehavior 方法注册行为，现在使用 options.AddOpenBehavior 方法注册行为。


builder.Services.AddMediatR(options =>
{
 options.RegisterServicesFromAssembly(Assembly.GetExecutingAssembly());
 options.AddOpenBehavior(typeof(LoggingBehavior<,>));
 options.AddOpenBehavior(typeof(ValidatorBehavior<,>));
 options.AddOpenBehavior(typeof(TransactionBehavior<,>));
});

使用分布式事件的微服务需要依赖注入上下文

builder.Services.AddHttpContextAccessor();

Azure Data Studio 删除数据库

-- 终止所有连接到目标数据库的会话
SELECT pg_terminate_backend(pg_stat_activity.pid)
FROM pg_stat_activity
WHERE pg_stat_activity.datname = 'my_database'
 AND pid <> pg_backend_pid();

-- 删除数据库
DROP DATABASE my_database;

IdentityService 演示数据生成前自动创建数据库

await serviceProvider.GetRequiredService<IdentityServiceDbContext>().Database.EnsureCreatedAsync(cancellationToken);

统一使用 DateTimeOffset 类型而不是 DateTime 类型

使用 UTC 时间的优点是可以在不同的时区之间进行转换，而不会丢失时间信息，让程序更好的处理时间，有利于跨时区的应用程序国际化本地化。

使用 Azure Data Studio 管理数据库

Tue, 10 Mar 2026 15:55:34 +0800

Azure Data Studio 是一个轻量级的跨平台数据库工具，提供了一个现代化的用户界面，可以帮助用户更轻松地管理数据库。

全部代码开源

Azure Data Studio 是一个开源项目，全部代码都托管在 GitHub 上，用户可以自由查看源代码，也可以参与到项目中来。

https://github.com/Microsoft/azuredatastudio

可管理的数据库

Azure Data Studio 支持多种数据库，包括 SQL Server、PostgreSQL、MySQL 、TimescaleDB、Oracle 等，通过安装相应的扩展，可以支持更多的数据库。

带有智能感知的查询编辑器

丰富的 SQL 编辑器、IntelliSense、关键字完成、代码片段、代码导航和源代码管理集成 (Git)）提供一种基于键盘的新式 SQL 编码体验。

智能 SQL 代码片段

Azure Data Studio 提供了大量的 SQL 代码片段，可以帮助用户快速编写 SQL 代码。

使用服务器组

借助服务器组，可以分类管理服务器，方便用户更轻松地管理多个服务器。

使用集成终端

用户界面中的“集成终端”窗口中使用常用的命令行工具，例如：sqlcmd 命令。

使用表设计器

Azure Data Studio 提供了一个表设计器，可以帮助用户更轻松地设计表。

备份和还原数据库

Azure Data Studio 提供了备份和还原数据库的功能，可以帮助用户更轻松地备份和还原数据库。

使用 Copilot 插件

Copilot 插件可以借助强大的 AI 帮助用户更轻松地编写 SQL 代码，提高编码效率。

可使用 Git 管理 SQL 脚本

Azure Data Studio 集成了 Git，可以帮助用户更轻松地管理 SQL 脚本。

使用 CQRS 模式实现订单服务

Tue, 10 Mar 2026 15:55:34 +0800

CQRS 是命令和查询责任分离的英文缩写，它是一种将读取操作和更新操作分离的模式，查询返回结果，不改变系统的状态，没有副作用。命令执行更改系统状态，幂等性是指相同的命令多次执行，结果是一样的，不会有副作用。

为什么要使用 CQRS 模式

在传统的体系结构中，使用同一数据模型查询和更新数据库。这十分简单，非常适用于基本的 CRUD 操作。

CQRS 将读取和写入分离到不同的模型，使用命令来更新数据，使用查询来读取数据。读取存储可以是写入存储的只读副本，或者读取和写入存储可以具有完全不同的结构。使用多个只读副本可以提高查询性能，尤其是在只读副本靠近应用程序实例的分布式方案中。

使用 MediatR 实现 CQRS 中的 Command 模式

dotnet add package MediatR

public class CreateOrderCommand : IRequest<bool>
{
 public string Product { get; set; }
 public int Quantity { get; set; }
}

public class CreateOrderCommandHandler1 : IRequestHandler<CreateOrderCommand, bool>
{
 public Task<bool> Handle(CreateOrderCommand request, CancellationToken cancellationToken)
 {
 return Task.FromResult(1);
 }
}

public class CreateOrderCommandHandler2 : IRequestHandler<CreateOrderCommand, bool>
{
 public Task<bool> Handle(CreateOrderCommand request, CancellationToken cancellationToken)
 {
 return Task.FromResult(2);
 }
}


public class OrdersController : ControllerBase
{
 private readonly IMediator _mediator;

 public OrdersController(IMediator mediator)
 {
 _mediator = mediator;
 }

 [HttpPost]
 public async Task<IActionResult> CreateOrder(CreateOrderCommand command)
 {
 var orderId = await _mediator.Send(command);
 return Ok(orderId);
 }
}

builder.Services.AddMediatR(options => options.RegisterServicesFromAssembly(Assembly.GetExecutingAssembly()));

使用 Mediator 请求管道处理 CQRS 中的命令

LoggingBehavior、ValidatorBehavior 和 TransactionBehavior

使用 Dapr 实现分布式事件总线

Tue, 10 Mar 2026 15:55:34 +0800

抽象分布式总线

使用设计模式，将分布式总线的使用方式进行抽象，定义了总线的基本功能。

基于事件总线的组件

使用组件化的方式实现分布式事件总线，将总线的实现细节封装在组件中。

基于 RabbbitMQ 实现：https://github.com/dotnet/eShop/tree/main/src/EventBusRabbitMQ

事件总线的 Dapr 实现

Dapr 是一个开源的分布式应用程序运行时，发布和订阅模块使微服务能够使用事件驱动架构的消息相互通信，Dapr 提供了一个事件总线的实现，使用 Dapr 发布事件，提供 Dapr 订阅终结点，将消息路由到不同的事件处理程序。

使用 Dpar 发布订阅配置分布式事件

Tue, 10 Mar 2026 15:55:34 +0800

Dapr 技术架构

https://docs.dapr.io/concepts/overview

安装 Dapr CLI 脚手架工具

https://docs.dapr.io/zh-hans/getting-started/install-dapr-cli

基于容器初始化 Dapr 运行时

https://docs.dapr.io/zh-hans/getting-started/install-dapr-selfhost

dapr init

不用容器离线初始化 Dapr 运行时

dapr init -s

使用离线包初始化 Dapr 运行时

https://docs.dapr.io/zh-hans/operations/hosting/self-hosted/self-hosted-airgap/

dapr init --from-dir C:\daprbundle

打开默认初始化目录

explorer "$env:USERPROFILE\.dapr"
explorer "%USERPROFILE%\.dapr"

使用 Dashboard 查看 Dapr 运行状态

dapr dashboard

发布订阅配置分布式事件

/components/redis-pubsub.yaml

基于 Redis 发布订阅配置

apiVersion: dapr.io/v1alpha1
kind: Component
metadata:
 name: pubsub
spec:
 type: pubsub.redis
 version: v1
 metadata:
 - name: redisHost
 value: localhost:6379
 - name: redisPassword
 value: ""

基于 RabbitMQ 发布订阅配置

/components/rabbitmq-pubsub.yaml

apiVersion: dapr.io/v1alpha1
kind: Component
metadata:
 name: pubsub
spec:
 type: pubsub.rabbitmq
 version: v1
 metadata:
 - name: host
 value: "amqp://guest:guestpwd@localhost:5672"
 - name: durable
 value: "false"
 - name: deletedWhenUnused
 value: "false"
 - name: autoAck
 value: "false"
 - name: reconnectWait
 value: "0"
 - name: concurrency
 value: parallel

使用 Dapr 命令启动 Sidecar 和应用程序

dapr run --app-id myapp --dapr-http-port 3500 --dapr-grpc-port 50001 --app-port 5000 --log-level debug --config ./configuration/config.yaml --components-path ./components dotnet run

使用 Aspire 命令启动 Sidecar 和应用程序

dotnet add package Aspire.Hosting.Dapr

var pubsub = builder.AddDaprPubSub("pubsub", new DaprComponentOptions { LocalPath = "./DaprComponents/" });

var productService = builder.AddProject<Projects.HelloWorld_ProductService>("productservice")
 .WithReference(identityService)
 .WithDaprSidecar()
 .WithReference(pubsub);

使用 RabbitMQ 发布订阅配置

var username = builder.AddParameter("username", secret: true);
var password = builder.AddParameter("password", secret: true);

var messaging = builder.AddRabbitMQ("messaging", username, password);

// Service consumption
builder.AddProject<Projects.ExampleProject>()
 .WithReference(messaging);

使用 gRPC 实现购物车服务

Tue, 10 Mar 2026 15:55:34 +0800

什么是 gRPC 通信框架

gRPC 是一个高性能、开源和通用的 RPC 框架，由 Google 开发，基于 HTTP/2 协议，支持多种语言（如 Go、Java、Python、C++、Node.js、Ruby、C#、Objective-C、PHP 和 Dart）。

gRPC 使用 Protocol Buffers 作为接口定义语言（IDL），Protocol Buffers 是一种轻便高效的结构化数据序列化方法，类似于 XML 或 JSON，但更小、更快、更简单。

ASP.NET Core 中使用 gRPC 实现服务

定义一个 gRPC 服务，需要创建一个 gRPC 服务定义文件（.proto 文件），然后使用 gRPC 工具生成服务端和客户端代码。

带有 OpenAPI 的 gRPC 服务

dotnet add package Microsoft.AspNetCore.Grpc.Swagger

<IncludeHttpRuleProtos>true</IncludeHttpRuleProtos>

var builder = WebApplication.CreateBuilder(args);
builder.Services.AddGrpc().AddJsonTranscoding();
builder.Services.AddGrpcSwagger();
builder.Services.AddSwaggerGen(c =>
{
 c.SwaggerDoc("v1",
 new OpenApiInfo { Title = "gRPC transcoding", Version = "v1" });
});

var app = builder.Build();
app.UseSwagger();
if (app.Environment.IsDevelopment())
 app.UseSwaggerUI(c =>
 {
 c.SwaggerEndpoint("/swagger/v1/swagger.json", "My API V1");
 });
}
app.MapGrpcService<GreeterService>();

app.Run();

// My amazing greeter service.
service Greeter {
 // Sends a greeting.
 rpc SayHello (HelloRequest) returns (HelloReply) {
 option (google.api.http) = {
 get: "/v1/greeter/{name}"
 };
 }
}

message HelloRequest {
 // Name to say hello to.
 string name = 1;
}
message HelloReply {
 // Hello reply message.
 string message = 1;
}

单元测试 gRPC 服务

dotnet add package moq

public class GreeterServiceTests
{
 [Fact]
 public async Task SayHello_ReturnsHello()
 {
 // Arrange
 var mockLogger = new Mock<ILogger<GreeterService>>();
 var service = new GreeterService(mockLogger.Object);
 var request = new HelloRequest { Name = "Unit Test" };
 var context = new ServerCallContext();

 // Act
 var reply = await service.SayHello(request, context);

 // Assert
 Assert.Equal("Hello Unit Test", reply.Message);
 }
}

集成测试 gRPC 服务

dotnet add package Microsoft.AspNetCore.TestHost

public class GreeterServiceIntegrationTests
{
 private readonly TestServer _server;
 private readonly Greeter.GreeterClient _client;

 public GreeterServiceIntegrationTests()
 {
 _server = new TestServer(new WebHostBuilder()
 .ConfigureServices(services =>
 {
 services.AddGrpc();
 })
 .Configure(app =>
 {
 app.UseRouting();
 app.UseEndpoints(endpoints =>
 {
 endpoints.MapGrpcService<GreeterService>();
 });
 }));
 _client = new Greeter.GreeterClient(_server.CreateGrpcChannel());
 }

 [Fact]
 public async Task SayHello_ReturnsHello()
 {
 // Arrange
 var request = new HelloRequest { Name = "Integration Test" };

 // Act
 var reply = await _client.SayHelloAsync(request);

 // Assert
 Assert.Equal("Hello Integration Test", reply.Message);
 }
}

使用 HybridCache 混合缓存库

Tue, 10 Mar 2026 15:55:34 +0800

混合缓存可以同时使用内存缓存和分布式缓存，它可以提高缓存的命中率，减少对分布式缓存的访问，从而提高性能。

当从缓存中获取数据时，它首先会从内存缓存中获取数据，如果内存缓存中没有数据，它会从分布式缓存中获取数据。
当向缓存中写入数据时，它会同时向内存缓存和分布式缓存中写入数据。


Service 1 ----> HybridCache ----> MemoryCache ----> DistributedCache

https://learn.microsoft.com/zh-cn/azure/architecture/best-practices/caching

安装程序包

dotnet add package Microsoft.Extensions.Caching.Hybrid

配置服务

builder.Services.AddHybridCache();

使用服务

public class SomeService(HybridCache cache)
{
 private HybridCache _cache = cache;

 public async Task<string> GetSomeInfoAsync(string name, int id, CancellationToken token = default)
 {
 return await _cache.GetOrCreateAsync( $"{name}-{id}",async cancel => await GetDataFromTheSourceAsync(name, id, cancel),cancellationToken: token );
 }

 public async Task<string> GetDataFromTheSourceAsync(string name, int id, CancellationToken token)
 {
 string someInfo = $"someinfo-{name}-{id}";
 return someInfo;
 }
}

按标记移除缓存条目

public class SomeService(HybridCache cache)
{
 private HybridCache _cache = cache;

 public async Task<string> GetSomeInfoAsync(string name, int id, CancellationToken token = default)
 {
 var tags = new List<string> { "tag1", "tag2", "tag3" };
 var entryOptions = new HybridCacheEntryOptions
 {
 Expiration = TimeSpan.FromMinutes(1),
 LocalCacheExpiration = TimeSpan.FromMinutes(1)
 };
 return await _cache.GetOrCreateAsync(
 $"{name}-{id}", // Unique key to the cache entry
 async cancel => await GetDataFromTheSourceAsync(name, id, cancel),
 entryOptions,
 tags,
 cancellationToken: token
 );
 }

 public async Task<string> GetDataFromTheSourceAsync(string name, int id, CancellationToken token)
 {
 string someInfo = $"someinfo-{name}-{id}";
 return someInfo;
 }

 public async Task RemoveByTagAsync(string tag)
 {
 await _cache.RemoveByTagAsync(tag);
 }
}

使用 JwtBearer 令牌进行身份验证

Tue, 10 Mar 2026 15:55:34 +0800

介绍

JwtBearer 令牌身份验证是一种基于 JSON Web 令牌的身份验证方法, 用于验证用户的身份, 它是一种无状态的身份验证方法, 适用于 Web API 和 Web 应用程序。

安装 NuGet 包

dotnet add package Microsoft.AspNetCore.Authentication.JwtBearer

自建 Identity Api 终结点

builder.Services.AddIdentity<User, Role>(options =>
{
 options.SignIn.RequireConfirmedAccount = false;
 options.Password.RequireDigit = false;
 options.Password.RequireLowercase = false;
 options.Password.RequireUppercase = false;
 options.Password.RequireNonAlphanumeric = false;
 options.Password.RequiredLength = 5;
}).AddEntityFrameworkStores<IdentityServiceDbContext>();

使用 JwtBearer 验证令牌


builder.Services.AddAuthentication(options =>
{
 options.DefaultChallengeScheme = JwtBearerDefaults.AuthenticationScheme;
 options.DefaultAuthenticateScheme = JwtBearerDefaults.AuthenticationScheme;
 options.DefaultSignInScheme = CustomJwtBearerDefaults.AuthenticationScheme;
}).AddJwtBearer(options =>
{
 options.TokenValidationParameters.ValidateIssuer = false;
 options.TokenValidationParameters.ValidateAudience = false;
 options.TokenValidationParameters.IssuerSigningKey = new SymmetricSecurityKey(Encoding.Default.GetBytes(issuerSigningKey));

})

自定义身份认证处理程序

public class CustomJwtBearerDefaults

public class CustomJwtBearerOptions

public class CustomJwtBearerHandler

public class CustomJwtBearerExtensions

配置令牌生成

builder.Services.AddAuthentication().AddJwtBearer().AddCustomJwtBearer(options =>
{
 options.IssuerSigningKey = issuerSigningKey;
 options.SecurityAlgorithm = SecurityAlgorithms.HmacSha256;
});

在容器中运行 pgAdmin 管理工具


docker pull dpage/pgadmin4

docker run --name pgadmin -e PGADMIN_DEFAULT_EMAIL=test@test.com -e PGADMIN_DEFAULT_PASSWORD=test -e TZ=Asia/Shanghai -d -p 5050:80 dpage/pgadmin4

使用 OpenAPI 规范生成 API 文档

Tue, 10 Mar 2026 15:55:34 +0800

Swagger 是一个与语言无关的规范，用于描述 REST API。它使计算机和用户无需直接访问源代码即可了解 REST API 的功能，Swagger 项目已于捐赠给 OpenAPI 计划，自此它被称为 OpenAPI 规范。

Swashbuckle 是一个用于 .NET Core 的开源项目，它是 OpenAPI 工具的集合，用于生成 OpenAPI 规范的文档。它可以自动生成 API 文档，包括 API 的描述、请求和响应的格式、参数的描述等。

安装 Swashbuckle.AspNetCore

在 .NET Core 项目中，可以通过 NuGet 安装 Swashbuckle.AspNetCore 包。

dotnet add package Swashbuckle.AspNetCore

配置 Swashbuckle

在 Startup.cs 文件中，可以通过以下方式配置 Swagger：

builder.Services.AddEndpointsApiExplorer();
builder.Services.AddSwaggerGen();

if (app.Environment.IsDevelopment())
{
 app.UseSwagger();
 app.UseSwaggerUI();
}

使用 PostgreSQL 数据库存储数据

Tue, 10 Mar 2026 15:55:34 +0800

在 Docker 中启动 PostgreSQL 数据库

https://www.postgresql.org

docker pull postgres
docker run --name postgres -e POSTGRES_PASSWORD=postgres -e TZ=Asia/Shanghai -d -p 5432:5432 postgres

使用 PgAdmin 连接 PostgreSQL 数据库

https://www.pgadmin.org

SHOW timezone;

EfCore 使用 PostgreSQL 数据库

dotnet add package Npgsql.EntityFrameworkCore.PostgreSQL

定义实体类型

public class User
{
 public int Id { get; set; }
 public string UserName { get; set; }
 public string PasswordHash { get; set; }
 public DateTimeOffset CreationTime { get; set; } = DateTimeOffset.UtcNow;
}

配置实体类型

public class UserEntityTypeConfiguration : IEntityTypeConfiguration<User>
{
 public void Configure(EntityTypeBuilder<User> builder)
 {
 builder.ToTable("Users");
 builder.HasKey(x => x.Id);
 builder.Property(x => x.UserName).IsRequired().HasMaxLength(50);
 builder.Property(x => x.PasswordHash).IsRequired().HasMaxLength(50);
 builder.Property(x => x.CreationTime);
 }
}

创建 DbContext 上下文

public class IdentityServiceDbContext : DbContext
{
 public IdentityServiceDbContext(DbContextOptions<IdentityServiceDbContext> options) : base(options)
 {
 }

 protected override void OnModelCreating(ModelBuilder builder)
 {
 base.OnModelCreating(builder);

 builder.ApplyConfigurationsFromAssembly(Assembly.GetExecutingAssembly());

 AppContext.SetSwitch("Npgsql.EnableLegacyTimestampBehavior", true);
 AppContext.SetSwitch("Npgsql.DisableDateTimeInfinityConversions", true);
 }
}

数据库连接字符串

{
 "ConnectionStrings": {
 "IdentityDatabase": "Host=localhost;Port=5432;Database=IdentityService;Username=postgres;Password=postgres"
 }
}

注册数据库上下文

builder.Services.AddDbContext<IdentityServiceDbContext>(options =>
{
 options.UseNpgsql(builder.Configuration.GetConnectionString("IdentityDatabase"));
});

迁移数据库

dotnet tool install --global dotnet-ef
dotnet add package Microsoft.EntityFrameworkCore.Design

dotnet ef migrations add InitialCreate --output-dir EntityFrameworks/Migrations
dotnet ef database update

PostgreSQL 数据库命名约定

https://github.com/efcore/EFCore.NamingConventions

使用 TimeProvider 获取时间

Tue, 10 Mar 2026 15:55:34 +0800

传统方式获取时间

我们通常使用 DateTime.Now 和 DateTimeOffset.Now 来获取当前时间，但是这样的代码很难测试，时间依赖于系统时间，很难控制和重现，只能修改系统时间。

var now1 = DateTime.Now;
var nowUtc1 = DateTime.UtcNow;

var now2 = DateTimeOffset.Now;
var nowUtc2 = DateTimeOffset.UtcNow;

重写 TimeProvider 模拟时间

我们可以重写 TimeProvider 类型，模拟时间，方便测试。

public class MyTimeProvider : TimeProvider
{
 public override DateTimeOffset GetUtcNow() => DateTimeOffset.UtcNow;
}

依赖注入 TimeProvider 实现

默认实现 TimeProvider.System 使用系统时间。

builder.Services.AddSingleton(TimeProvider.System);

注入 MyTimeProvider 使用自定义时间。

builder.Services.AddSingleton<TimeProvider, MyTimeProvider>();

使用 TimeProvider 的代码

public class MyService(TimeProvider timeProvider)
{

 public void DoSomething()
 {
 var now = timeProvider.GetLocalNow();
 var nowUtc = timeProvider.GetUtcNow();
 }
}

演示零度框架中使用 TimeProvider 代码。

关于时间的单元测试

Microsoft.Extensions.TimeProvider.Testing

使用 TimeProvider 类注入时间

Tue, 10 Mar 2026 15:55:34 +0800

System.TimeProvider 是一种时间抽象，它以 DateTimeOffset 类型的形式提供时间点。通过使用 TimeProvider，可确保代码可测试且可预测。 TimeProvider 已在 .NET 8 中引入。

默认实现

默认情况下，TimeProvider 使用 DateTimeOffset.UtcNow 作为时间源。

Console.WriteLine($"Local: {TimeProvider.System.GetLocalNow()}");
Console.WriteLine($"Utc: {TimeProvider.System.GetUtcNow()}");

自定义实现

public class CustomTimeProvider: TimeProvider
{
 public override DateTimeOffset GetUtcNow() => DateTimeOffset.UtcNow.AddHours(1);
}

builder.Services.AddSingleton(TimeProvider.System);
builder.Services.AddSingleton<TimeProvider, CustomTimeProvider>();

public class MyService
{
 private readonly TimeProvider _timeProvider;

 public MyService(TimeProvider timeProvider)
 {
 _timeProvider = timeProvider;
 }

 public void DoSomething()
 {
 var now = _timeProvider.Now;
 Console.WriteLine(now);
 }
}

FakeTimeProvider 实现

dotnet add package Microsoft.Extensions.TimeProvider.Testing

FakeTimeProvider fakeTimeProvider = new();
fakeTimeProvider.SetUtcNow(fakeTimeProvider.GetUtcNow().AddHours(1));

MyService service = new (timeProvider);
service.DoSomething();

使用分布式锁解决并发问题

Tue, 10 Mar 2026 15:55:34 +0800

单进程应用程序中的锁

在单机环境下，我们可以使用线程锁来解决并发问题，但是在分布式系统中，线程锁无法解决并发问题，因为分布式系统中的线程锁只能锁住当前进程，无法锁住其他进程。

在 .NET 中，我们可以使用 lock 关键字来实现线程锁。

https://learn.microsoft.com/zh-cn/dotnet/csharp/language-reference/statements/lock

private static readonly object _lock = new object();

public void DoSomething()
{
 lock (_lock)
 {
 // 业务逻辑
 }
}

C# 13 引入了新的线程同步类型 System.Threading.Lock，它通过作用域管理的方式简化了锁的使用，使代码更加清晰可靠。

using System.Threading.Lock;

private static readonly Lock _lock = new Lock();

public void DoSomething()
{
 using (_lock.EnterScope())
 {
 // 业务逻辑
 }
}

开源分布式锁的实现

DistributedLock 是一个 .NET 库，它基于各种底层技术提供强大且易于使用的分布式互斥锁、读写器锁和信号量。

https://github.com/madelson/DistributedLock

零度框架中的分布式锁

零度框架中提供分布式锁的基本抽象，并基于 Dapr 实现了分布式锁。

https://docs.dapr.io/developing-applications/building-blocks/distributed-lock/distributed-lock-api-overview

Redis 分布式锁原理

Redis 分布式锁的实现原理是通过 SETNX 命令，SETNX 是 Redis 的一个原子性操作，它会在键不存在时设置键的值，如果键已经存在，则不做任何操作。

使用缓存提高系统性能

Tue, 10 Mar 2026 15:55:34 +0800

缓存是一种常见的技术，目标是提高系统的性能和伸缩性。为缓存数据，它会暂时会经常访问的数据复制到位置靠近应用程序的快速存储。如果这种快速数据存储比原始源更靠近应用程序，则缓存可以通过更快速提供数据，大幅改善客户端应用程序的响应时间。

缓存类型

私有专用缓存

专用缓存是指缓存服务运行在应用程序的同一台服务器上，它是应用程序的一部分，通常是一个库或模块。专用缓存通常是一个内存缓存，如 MemoryCache 或 ConcurrentDictionary，它是一个轻量级的缓存，适用于小型应用程序。专用缓存的优点是简单易用，缺点是无法跨服务器共享数据，不适用于大型应用程序，使用 IMemoryCache 接口可以在 .NET 中使用专用缓存。


services.AddMemoryCache();

public class MyService(IMemoryCache cache) : IService
{
 public async Task Test()
 {
 cache.Set("key", "value");
 var value = cache.Get("key");
 }
}

分布式共享缓存

分布式缓存是指缓存服务运行在多台服务器上，它是一个独立的服务，可以跨服务器共享数据。分布式缓存通常是一个内存缓存，如 Redis、Memcached、Garnet 等，它是一个高性能、低延迟的缓存，适用于大型应用程序。分布式缓存的优点是高性能、低延迟，支持大规模数据存储和访问，缺点是复杂度高，需要额外的服务器资源，使用 IDistributedCache 接口可以在 .NET 中使用分布式缓存。


services.AddMemoryDistributedCache();

public class MyService(IDistributedCache cache) : IService
{
 public async Task Test()
 {
 await cache.SetStringAsync("key", "value");
 var value = await cache.GetStringAsync("key");
 }
}

使用 Redis 分布式缓存

Redis 是一个高性能、开源的分布式缓存系统，它是一个内存数据库，支持多种数据结构，如字符串、列表、哈希表、集合等，Redis 的设计目标是提供一个高性能、低延迟的分布式缓存系统，以支持大规模的数据存储和访问，同时提供高可用性和可扩展性。Redis 采用 RESP 协议，使用 C 语言编写，支持多种语言，如 C、C++、C#、Java、Python、Node.js 等，可以在 .NET 中使用 StackExchange.Redis 开源库对缓存进行操作。

Windows 下 Redis 不再维护，可以使用 WSL2 安装 Redis，或者使用 Docker 安装 Redis。也可使用 Memurai 替代 Redis，Memurai 是一个 Windows 下的 Redis 服务，支持 Redis 的大部分功能，可以在 Windows 下运行 Redis 服务。

数据库对象命名约定

Tue, 10 Mar 2026 15:55:34 +0800

不同数据库对象的命名约定不同，EF Core 为了适配不同数据库，提供了一些命名约定的配置选项。

常见的命名方法

Naming policy	Original	Converted
PascalCase	HelloShop	HelloShop
CamelCase	HelloShop	helloShop
SnakeCaseLower	HelloShop	hello_shop
SnakeCaseUpper	HelloShop	HELLO_SHOP
KebabCaseLower	HelloShop	hello-shop
KebabCaseUpper	HelloShop	HELLO-SHOP

可使用 Humanizr 库将字符串转换为不同的命名风格。

表名使用单数还是复数

EF Core 默认情况下，表名使用单数形式，可以通过约定器或者手动指定复数表名，社区对单数和复数表名的争论一直存在，没有统一的标准，但零度推荐使用单数形式。

手动指定表名和列名

表名

默认情况下，EF Core 使用实体类型的名称作为表名。可以通过重写 OnModelCreating 方法来修改表名：

protected override void OnModelCreating(ModelBuilder modelBuilder)
{
 modelBuilder.Entity<Blog>().ToTable("blogs");
}

列名

默认情况下，EF Core 使用属性名作为列名。可以通过 HasColumnName 方法来修改列名：

protected override void OnModelCreating(ModelBuilder modelBuilder)
{
 modelBuilder.Entity<Blog>().Property(b => b.Url).HasColumnName("blog_url");
}

PostgreSQL 命名约定

PostgreSQL 的命名约定采用小写蛇形命名法，即单词之间使用下划线分隔，如 blog_url，表名使用单数形式。

使用 EFCore.NamingConventions 库

EFCore.NamingConventions 库提供了一些命名约定的配置选项，可以方便地配置表名、列名等。

安装 EFCore.NamingConventions 库

dotnet add package EFCore.NamingConventions

配置命名约定

使用 OnConfiguring 方法配置命名约定：

网关和服务发现

Tue, 10 Mar 2026 15:55:34 +0800

构建和设计 API 网关

API 网关是一个服务器，它是客户端和后端服务之间的中介。它接收来自客户端的请求，然后将这些请求转发到后端服务。API 网关还可以执行其他任务，例如身份验证、监视、负载平衡、缓存、请求分析和日志记录。

BFF 模式聚合多个服务

API 网关可以聚合多个服务，基于 BFF（后端用于前端）模式，当客户端请求数据时，API 网关可以调用多个服务来获取数据，然后将数据聚合到一个响应中返回给客户端，以减少客户端与后端服务之间的通信次数，从而提高性能。

常见的 API 网关

Nginx、Envoy、Ocelot、Yarp、Zuul、Kong、Traefik、Tyk、Ambassador、Gloo、AWS API Gateway、Azure API Management、Google Cloud Endpoints、Apigee、MuleSoft Anypoint API Gateway、WSO2 API Manager、TIBCO Mashery、3scale API Management、Akana、CA API Gateway、Dell Boomi、DreamFactory、IBM API Connect、Mashape、Mashery、MuleSoft Anypoint Platform、OpenLegacy、Oracle API Platform Cloud Service、Repre。

基于.NET 的开源 API 网关

Ocelot 和 Yarp 是一个基于.NET 的开源 API 网关，它可以用于构建和设计微服务架构中的 API 网关。Yarp 提供了很多功能，例如路由、负载平衡、认证、授权、限流、熔断、重试、缓存、请求转发、请求重写、请求日志、响应缓存、响应压缩、响应缓存、响应重写、响应日志、监视、跟踪、跨域、安全、性能、可扩展性、可配置性、可管理性、可监视性、可测试性、可部署性、可维护性、可扩展性、可升级。

Github 开源仓库

官方参考文档

使用 Yarp 构建和设计 API 网关

dotnet add package Yarp.ReverseProxy

使用配置文件配置 Yarp

{
 "ReverseProxy": {
 "Routes": {
 "testserviceRoute": {
 "ClusterId": "testServiceCluster",
 "Match": {
 "Path": "testservice/{**remainder}"
 },
 "Transforms": [
 { "PathPattern": "{**remainder}" }
 ]
 }
 },
 "Clusters": {
 "testServiceCluster": {
 "Destinations": {
 "testServiceCluster/destination1": {
 "Address": "http://identityservice"
 }
 }
 }
 }
 }
}

.NET 中的服务发现

服务发现是一种用于发现和定位服务的机制，它可以帮助客户端找到服务的位置和地址。服务发现可以用于构建和设计微服务架构中的 API 网关，以便客户端可以通过 API 网关访问后端服务。

用户界面和设计语言

Tue, 10 Mar 2026 15:55:34 +0800

用户体验

用户体验（User Experience，简称 UX）是用户在使用产品时的感受，是一个综合性的概念，包括用户对产品的感知、情感、态度、情绪等。用户体验设计（User Experience Design，简称 UXD）是一种以用户为中心的设计方法，目的是提高用户满意度，提高用户对产品的认知和使用。

颜色、字体、布局、交互等因素都会影响用户体验，因此在设计用户界面时需要考虑用户体验，提供简洁、直观、易用的界面，以提高用户满意度。

扁平化和拟物化

扁平化设计（Flat Design）是一种简洁、直观的设计风格，强调简单、明了的界面设计，去除了繁琐的装饰和冗余的元素，使用户更容易理解和操作。拟物化设计（Skeuomorphism）是一种仿真真实物体的设计风格，强调真实感和细节，使用户更容易理解和操作。

搜索 Flat vs Skeuomorphism 了解更多信息。

常见的设计语言

Google Material Design、Microsoft Fluent Design System、Alibaba Ant Design …

Material Design

设计语言

https://material.io/design

组件库

https://github.com/MudBlazor/MudBlazor

https://github.com/MudBlazor/

Fluent Design System

设计语言

https://www.microsoft.com/design/fluent

组件库

https://github.com/microsoft/fast-blazor

Ant Design

设计语言

https://ant.design

组件库

https://github.com/ant-design-blazor/ant-design-blazor

商业组件库

https://github.com/radzenhq/radzen-blazor

原型工具

MasterGo 和 Figma 是两个常用的原型工具，可以用来设计和制作用户界面原型，提供了丰富的组件库和交互效果，可以帮助设计师快速制作用户界面原型。

设计令牌

设计令牌（Design Tokens）是一种用来定义设计系统的方法，包括颜色、字体、间距、阴影等设计元素，可以帮助设计师和开发者快速创建一致的设计风格，提高设计效率。

选择组件

风格统一、易用性、可定制性、性能优化、文档完善、社区活跃、维护更新、商业授权等因素都会影响组件库的选择。

互补色

互补色是指在色彩环中相对位置相反的两种颜色，当两种互补色放在一起时，会产生强烈的对比效果，使得两种颜色更加突出。互补色的组合通常会产生视觉冲击，因此在设计中需要谨慎使用，浏览器开发者工具监测对比度，以确保用户体验。

应用案例

Aspire 的仪表盘设计是基于 Fluent Design 的，采用了扁平化设计风格，简洁、直观、易用，提高了用户体验。

用于生成初始数据的提供程序

Tue, 10 Mar 2026 15:55:34 +0800

数据播种是使用一组初始数据填充数据库的过程，通常在数据库首次创建时执行，这些数据通常是静态的，不会随时间变化，数据播种通常用于填充一些基本数据，例如用户、角色、权限、商品、分类等。

通用接口设计

public interface IDataSeedingProvider
{
 Task SeedingAsync(IServiceProvider serviceProvider);
}

实现具体接口

public class DataSeedingProvider(UserManager<User> userManager) : IDataSeedingProvider
{
 public async Task SeedingAsync(IServiceProvider ServiceProvider)
 {
 var user = await userManager.FindByNameAsync("admin");

 if (user == null)
 {
 await userManager.CreateAsync(new User
 {
 UserName = "admin",
 Email = "admin@test.com"
 }, "admin");
 }
 }
}

在容器中注册

builder.Services.AddTransient<IDataSeedingProvider, DataSeedingProvider>();

自动执行扩展

public static class DataSeedingExtensions
{
 public static IApplicationBuilder UseDataSeedingProviders(this IApplicationBuilder app)
 {
 using var serviceScope = app.ApplicationServices.CreateScope();

 var dataSeedingProviders = serviceScope.ServiceProvider.GetServices<IDataSeedingProvider>();

 foreach (IDataSeedingProvider dataSeedingProvider in dataSeedingProviders)
 {
 dataSeedingProvider.SeedingAsync(serviceScope.ServiceProvider).Wait();
 }

 return app;
 }
}

自动注册实现

public static class DataSeedingExtensions
{
 public static IServiceCollection AddDataSeedingProviders(this IServiceCollection services, Assembly? assembly = null)
 {
 assembly ??= Assembly.GetCallingAssembly();

 var dataSeedProviders = assembly.ExportedTypes.Where(t => t.IsAssignableTo(typeof(IDataSeedingProvider)) && t.IsClass);

 dataSeedProviders.ToList().ForEach(t => services.AddTransient(typeof(IDataSeedingProvider), t));

 return services;
 }
}

执行顺序问题

自动注册的提供程序的执行顺序是不确定的，如果需要确定执行顺序，可以设计 Order 属性，然后在 UseDataSeedingProviders 方法中按照 Order 属性排序执行。

在微服务中使用

builder.Services.AddDataSeedingProviders();
app.UseDataSeedingProviders();

在 Aspire 中集成 PostgreSQL 数据库

Tue, 10 Mar 2026 15:55:34 +0800

在 Host 项目中添加 PostgreSQL 数据库

dotnet add package Aspire.Hosting.PostgreSQL

var builder = DistributedApplication.CreateBuilder(args);

var postgres = builder.AddPostgres("postgres");
var postgresdb = postgres.AddDatabase("postgresdb");

var exampleProject = builder.AddProject<Projects.ExampleProject>().WithReference(postgresdb);

添加 PostgreSQL pgAdmin 资源

var postgres = builder.AddPostgres("postgres").WithPgAdmin();

添加 PostgreSQL pgWeb 资源

var postgres = builder.AddPostgres("postgres").WithPgWeb();

在最终的应用中引用 PostgreSQL 数据库

dotnet add package Aspire.Npgsql.EntityFrameworkCore.PostgreSQL

builder.AddNpgsqlDbContext<IdentityServiceDbContext>(connectionName: DbConstants.ConnectionStringName, configureDbContextOptions: options =>
{
 new NpgsqlDbContextOptionsBuilder(options).MigrationsHistoryTable(DbConstants.MigrationsHistoryTableName);
});

在项目中添加文件头注释

Tue, 10 Mar 2026 15:55:34 +0800

文件头注释

版权申明规范

// Copyright (c) HelloShop Corporation. All rights reserved.
// See the license file in the project root for more information.

namespace HelloShop.AppHost
{
 internal class Class1
 {
 }
}

关于 EditorConfig 配置文件

为跨不同编辑器和 IDE 处理同一项目的多个开发人员保持一致的编码风格。

Visual Studio 2019 及更高版本支持 EditorConfig 文件，可以在 Visual Studio 中使用 EditorConfig 文件来定义和维护代码样式设置。

版权说明模板

file_header_template = Copyright (c) HelloShop Corporation. All rights reserved.\nSee the license file in the project root for more information.

对于文件名，可以使用 {fileName} 作为占位符。

制作动态流程图和架构图

Tue, 10 Mar 2026 15:55:34 +0800

微软 Visio 工具

Visio 是微软的画图工具，非常强大，但是收费，而且只能在 Windows 系统上使用，不支持 Mac 和 Linux 系统，虽然微软推出了 Visio Online，但是功能还是比较弱，而且收费。

开源 Drawio 工具

Drawio 是一个开源的画图工具，支持在线和桌面两种方式，支持多种格式，支持多种平台，支持多种语言，支持多种图形，支持多种导出格式，支持多种插件，支持多种集成方式，也支持在 Visual Studio Code 中使用插件的方式画图。

矢量图和位图

矢量图是由数学公式描述的图形，可以无限放大，不会失真，位图是由像素点描述的图形，放大会失真。

画图入口

Drawio 官网

在线画图

容器和容器大小缩放

设置图形 Container 属性为 true，可以将多个图形组合成一个图形，然后可以对这个图形进行缩放，设置 Collapsed 属性为 true，可以将图形折叠起来，只显示标题。设置 Resizable 属性为 false，可以禁止容器子图形缩放。

浮动链接和固定链接

浮动链接是指链接的位置随着图形的移动而移动，固定链接是指链接的位置不随着图形的移动而移动，可以添加自定义连接点。

拖动连接线文字

设置连接线文字可以拖动，可以将连接线文字拖动到连接线的任意位置，可以自定难以连接点的位置。

连接线的样式和反转

可以设置连接线的样式，可以设置连接线的反转，可以设置连接线的弯曲程度。

图形和连接线文字位置

设置文字位置，可以将文字放在图形或连接线左上角，设置文字位置为中心，可以将文字放在图形的中心。

连接线添加航点

可以在连接线上添加航点，可以在连接线上添加箭头，可以在连接线上添加标签。

任何目标可设置链接

可以设置任何对象的超级链接，可以设置连接线的超级链接，可以设置图形的超级链接。

替换图形

可以将新图形拖动到现有图形上替换图形，替换后，图形的属性和连接线都会保留。

对齐方式和分布方式

可以设置图形的对齐方式，可以设置图形的分布方式。

带着样式画图

可以带着样式画图，可以将样式应用到图形上，也可以清除默认样式。

嵌入图像和在线图像

理解几何图形，图形库图形，嵌入图像，在线图像的区别。

嵌入 SVG 图像修改样式

使用阿里图标库 iconfont 找图，可以下载 SVG 图像，然后嵌入到 Drawio 中，可以修改 SVG 图像的样式，但需要配置规则，如下代码。

自动迁移和数据库初始化

Tue, 10 Mar 2026 15:55:34 +0800

生成迁移脚本

dotnet ef migrations add InitialCreate --output-dir Infrastructure/Migrations

手动将最新迁移脚本应用到数据库

dotnet ef database update

使用代码创建数据库

await dbContext.Database.EnsureCreatedAsync();

EnsureCreatedAsync 会创建数据库（如果不存在），并会创建所有表，但不会应用迁移脚本，适用于开发环境。

使用代码将最新迁移脚本应用到数据库

await dbContext.Database.MigrateAsync();

MigrateAsync 会应用迁移脚本，如果数据库不存在，会先创建数据库，适用于生产环境。

注意事项

如果先前已经使用 EnsureCreatedAsync 创建了数据库，再使用 MigrateAsync 会抛出异常，因为数据库和所有表已经存在，因为迁移中有创建表的操作脚本。

如果数据库不存在，使用 MigrateAsync 会先创建数据库，再创建迁移历史表，然后再应用迁移脚本，但这个过程中会打印一些错误警告信息，虽然可以忽略，但不够优雅。

优雅的做法

这里使用到一些 EF Core 的内部服务，注意他们在实现细节上的区别。

private static async ValueTask RunMigrationAsync(TDbContext dbContext, CancellationToken cancellationToken)
{
 var strategy = dbContext.Database.CreateExecutionStrategy();
 var dbCreator = dbContext.GetService<IRelationalDatabaseCreator>();
 var historyRepository = dbContext.GetService<IHistoryRepository>();
 await strategy.ExecuteAsync(async () =>
 {
 if (!await dbCreator.ExistsAsync(cancellationToken))
 {
 await dbCreator.CreateAsync(cancellationToken);
 }
 await historyRepository.CreateIfNotExistsAsync();
 await dbContext.Database.MigrateAsync(cancellationToken);
 });
}

1、使用 dbCreator.ExistsAsync 先检查数据库是否存在，不存在则仅仅创建数据库（它不会创建表），这个时候得到一个空的数据库。

2、再使用 historyRepository.CreateIfNotExistsAsync 在空数据库中创建迁移历史表，用于保存迁移记录。

3、最后使用 dbContext.Database.MigrateAsync 应用迁移脚本，因为迁移脚本中的操作会在空数据库中执行，包括创建表等等操作。

4、迁移完成后，数据库中会有所有表和迁移历史表，迁移历史表中登记了最新的迁移记录。

5、后续再使用 dbContext.Database.MigrateAsync 会检查迁移历史表，如果有新的迁移脚本，会应用新的迁移脚本。

6、这样就实现了自动迁移和数据库初始化。

为了以上操作都在一个事务中执行，我们使用 dbContext.Database.CreateExecutionStrategy 创建一个执行策略，在策略中执行上述操作。

数据库初始化的方式

在最新的 EF 9.0 建议使用 UseSeeding 和 UseAsyncSeeding 并利用初始数据对数据库进行种子设定，这些代码会在迁移时执行。

自动映射实体和模型

Tue, 10 Mar 2026 15:55:34 +0800

使用 AutoMapper 自动映射实体和模型

AutoMapper 是一个对象映射工具，可以自动映射实体对象和模型对象，减少手动映射的工作量，提高开发效率，除此之外 Mapster 也是一个高性能的对象映射工具，支持源生成代码，性能更好。AutoMapper 比 Mapster 更加流行，更加成熟，更加稳定，更加易用，更加灵活，更加强大，更加全面，更加受欢迎。AutoMapper 是 .NET Foundation 的一部分，是一个开源项目，是一个非常优秀的对象映射工具。

安装 NuGet 包

dotnet add package AutoMapper

在依赖注入中注册 AutoMapper

builder.Services.AddAutoMapper(Assembly.GetExecutingAssembly());

创建映射配置文件


public class MappingProfile : Profile
{
 public MappingProfile()
 {
 CreateMap<User, UserDto>();
 CreateMap<UserDto, User>();
 }
}

使用 AutoMapper 映射实体和模型


public class UserService
{
 private readonly IMapper _mapper;

 public UserService(IMapper mapper)
 {
 _mapper = mapper;
 }

 public UserDto GetUser(int id)
 {
 var user = _dbContext.Users.Find(id);
 return _mapper.Map<UserDto>(user);
 }

 public void UpdateUser(UserDto userDto)
 {
 var user = _mapper.Map<User>(userDto);
 _dbContext.Users.Update(user);
 _dbContext.SaveChanges();
 }
}

分页模式

常见的分页模式有两种，一种是基于页码和页大小的分页模式，一种是基于游标和页大小的分页模式。