Posts on Coding with Denglei

.NET 10 使用 Microsoft.AspNetCore.OpenApi 实现 API 版本管理

Tue, 16 Jun 2026 17:04:23 +0800

为什么 API 版本管理如此重要？

API 版本管理的核心目标是：在不破坏现有用户的前提下，持续迭代和改进 API。通过版本管理，我们可以：

引入新功能：在新版本中添加字段、接口等，而不影响旧版本的用户。
修复 bug：在新版本中修复问题，而不冒破坏旧版本的风险。
逐步淘汰：在新版本中移除过时的功能，给用户足够的时间迁移。

常见的版本策略有这几种：

URL 路径版本：/api/v1/users，直观，最常见
查询参数版本：/api/users?api-version=1.0
请求头版本：X-API-Version: 1.0
媒体类型版本：Accept: application/json; v=1.0（GitHub 在用这种方式）

每种方式都有适用场景，没有绝对的优劣。

在 C# 生态中，长期以来的事实标准是 Swashbuckle.AspNetCore，但它并没有内置版本管理支持，需要配合 Asp.Versioning 来实现。

终于，在 .NET 10 中，微软推出了自己的 OpenAPI 库 Microsoft.AspNetCore.OpenApi，并且 Asp.Versioning v10 也正式支持了这个库，版本管理和文档生成终于可以无缝结合了。

上手 Microsoft.AspNetCore.OpenApi 和 Asp.Versioning

要使用 Microsoft.AspNetCore.OpenApi 和 Asp.Versioning 来实现 API 版本管理，首先需要安装相关 NuGet 包：

#package: Asp.Versioning.Http 10.0.0
#package: Asp.Versioning.Mvc 10.0.0
#package: Asp.Versioning.Mvc.ApiExplorer 10.0.0
#package: Microsoft.AspNetCore.OpenApi 10.0.0
#package: Scalar.AspNetCore 2.6.0

安装完成后，在 Program.cs 中进行如下配置：

services
    .AddApiVersioning(options =>
    {
        options.DefaultApiVersion = new ApiVersion(1, 0);
        options.AssumeDefaultVersionWhenUnspecified = true;
        options.ReportApiVersions = true;
        options.ApiVersionReader = new UrlSegmentApiVersionReader();
    })
    .AddMvc()
    .AddApiExplorer(options =>
    {
        options.GroupNameFormat = "'v'V";
        options.SubstituteApiVersionInUrl = true;
    });

services.AddOpenApi("v1", options =>
{
    options.ShouldInclude = apiDescription => apiDescription.GroupName == "v1";
});

services.AddOpenApi("v2", options =>
{
    options.ShouldInclude = apiDescription => apiDescription.GroupName == "v2";
});

app.MapOpenApi();
app.MapScalarApiReference(options =>
{
    options
        .WithTitle("Users API - {documentName}")
        .AddDocuments(new[] { "v1", "v2" });
});

在上面的代码中，我们首先配置了 API 版本管理，指定了默认版本、版本读取方式等。然后，我们为每个版本配置了 OpenAPI 文档生成，确保每个版本都有独立的文档。最后，我们映射了 OpenAPI 和 Scalar API Reference 的路由。

.NET 中 .Result 避坑指南：不同框架下的死锁与线程池饥饿

Tue, 16 Jun 2026 17:04:23 +0800

这篇只讲一个知识点：在 .NET 代码里用 .Result（或 GetAwaiter().GetResult()）同步阻塞异步任务，为什么在不同框架下会触发不同类型的事故。

问题背景

同样一行代码，在两个系统里出现了完全不同的故障：

老系统（ASP.NET MVC 5）请求直接卡死，不返回
新系统（ASP.NET Core）不是直接死锁，而是高峰期吞吐突然掉到很低，请求排队超时

两边都有这段写法：

public string GetData()
{
    return GetDataAsync().Result;
}

private async Task<string> GetDataAsync()
{
    await Task.Delay(50);
    return "ok";
}

原理：同一个坑，两种后果

场景 1：ASP.NET Classic / WinForms / WPF（有 SynchronizationContext）

这类框架默认要求 continuation 回到原上下文（UI 线程或请求上下文）。

.Result 先把当前线程阻塞住，Task 完成后 continuation 又想回到这条线程，结果互相等待：

当前线程在 .Result 处阻塞
continuation 需要回到当前线程继续执行
当前线程被阻塞，continuation 进不来
死锁

所以你会看到"请求一直转圈"或"界面完全卡死"。

场景 2：ASP.NET Core（默认无 SynchronizationContext）

在默认配置下，ASP.NET Core 没有传统的请求级 SynchronizationContext，所以通常不会触发上面的经典互锁。

它会把线程池工作线程同步阻塞住。并发一上来，越来越多线程被卡在 .Result，线程池来不及补充，新请求拿不到线程，就出现线程饥饿：

CPU 不一定高
数据库不一定慢
但接口耗时和超时数暴涨

这就是"看起来不像死锁，但系统几乎不可用"的典型表现。

最小对照示例

public sealed class DemoService
{
    // ❌ 错误：同步包装异步
    public int GetNumber()
    {
        return GetNumberAsync().Result;
    }

    // ✅ 正确：异步到底
    public async Task<int> GetNumberAsync()
    {
        await Task.Delay(10);
        return 42;
    }
}

如何避坑（只保留最关键三条）

不要在任何业务调用链上使用 .Result / .Wait() / GetAwaiter().GetResult()。
API、Service、Repository 全链路改成 async，不要做"同步方法包异步"。
如果历史包袱必须保留同步签名，就让边界层同步，内部仍然异步，避免层层阻塞传染。

一句结论

.Result 在老框架里更容易直接死锁，在 ASP.NET Core 里更容易演化成线程池饥饿；表现不同，本质相同，都是"阻塞等待异步"导致的。

.NET 内存性能优化实战：Span、ArrayPool、GC 与 LOH 控制

Tue, 16 Jun 2026 17:04:23 +0800

很多服务在压测里吞吐不错，一上生产就抖。根因常常不是业务逻辑，而是内存分配模式不健康。

典型表现：

GC 频率偏高
P99 周期性尖峰
单机吞吐不稳定

这篇文章重点讲“如何减少无意义分配”，并把优化控制在团队可维护范围内。

问题背景

真实现场：一次常规版本上线后，接口平均耗时变化不大，但 P99 从 120ms 拉到 380ms，最后定位到的是字符串拼接和临时数组在高峰时段触发了更频繁的 GC。

一个日志清洗或协议解析接口，经常会写出这样的代码：

var parts = line.Split('|');
var user = parts[0].Trim();
var action = parts[1].Trim();
var ts = DateTime.Parse(parts[2]);

逻辑简单，但每次请求都在制造短命对象。高并发下，这些小分配会形成大压力。

原理解析

代际 GC

短命对象主要在 Gen0/Gen1 回收。分配速率过高时，GC 会频繁触发，吞吐被打断。

LOH（大对象堆）

大于约 85KB 的对象进入 LOH。大对象频繁创建和释放，会导致更重的回收成本和内存碎片问题。

`Span<T>` 与 `ArrayPool<T>`

Span<T> 在不额外分配的前提下切片处理内存
ArrayPool<T> 复用数组，避免重复 new 大缓冲区

示例代码

先定义记录：

public sealed record AuditLog(string User, string Action, DateTime Timestamp);

使用 ReadOnlySpan<char> 解析：

public static bool TryParseAuditLog(string line, out AuditLog? log)
{
    log = null;
    ReadOnlySpan<char> span = line.AsSpan();

    var p1 = span.IndexOf('|');
    if (p1 < 0) return false;

    var p2 = span[(p1 + 1)..].IndexOf('|');
    if (p2 < 0) return false;
    p2 += p1 + 1;

    var user = span[..p1].Trim();
    var action = span[(p1 + 1)..p2].Trim();
    var tsText = span[(p2 + 1)..].Trim();

    if (!DateTime.TryParse(tsText, out var ts)) return false;

    log = new AuditLog(user.ToString(), action.ToString(), ts);
    return true;
}

对于大文本拼接，使用池化数组：

ASP.NET Core 内存缓存实战：一篇搞懂该怎么配、怎么避坑

Tue, 16 Jun 2026 17:04:23 +0800

引言

这篇文章我们来聊一聊 asp.net core 的内存缓存。asp.net core 内存缓存（IMemoryCache）是一个轻量级的缓存方案，适用于单实例应用或者分布式环境中的本地缓存。它提供了简单的 API 来存储和检索数据，同时支持过期策略、优先级设置等功能。

什么是缓存

从用户请求到数据库返回数据，这是一个漫长的过程（夸张了点，通常也就是几十毫秒到几百毫秒）。可是又不止一个用户在访问，甚至同一个用户在短时间内发起多个相似请求，这时候每次都走完整个流程就显得很浪费了。缓存的作用就是把之前请求的结果存储起来，下次有相同请求时直接返回缓存结果，省去重复计算和数据库访问的开销。所以，缓存是一个存储机制，使用它的目的是为了提高性能和响应速度。

asp.net core 中的缓存类型

在 asp.net core 中，提供了三种常用的缓存方案：

内存缓存（IMemoryCache）：适用于单实例应用或者分布式环境中的本地缓存。
分布式缓存（IDistributedCache）：适用于分布式环境中的共享缓存，常见实现有 Redis、SQL Server 等。
Hybrid 缓存：结合内存缓存和分布式缓存，先查内存缓存，未命中再查分布式缓存。

每一类的缓存都有自己的使用场景和适用边界，选择合适的缓存方案是非常重要的。

asp.net core 的内存缓存 IMemoryCache

asp.net core 的内存缓存使用本地内存来临时存储数据，所以它的访问速度非常快，通常远快于网络和数据库访问（具体耗时取决于数据大小与序列化开销）。但是内存缓存也有一些限制，不能在多实例中共享数据。此外，内存缓存的数据会随着应用重启而丢失，所以它更适合存储一些临时数据或者不需要持久化的数据。存放在本机内存中，会占用服务器的内存资源，如果缓存的数据量过大或者过期策略设置不当，可能会导致内存压力增大、频繁回收或者性能问题。因此，在使用内存缓存时需要注意以下几点：

不要将外部输入作为缓存键，因为这类输入可能会消耗不可预测的内存资源，导致缓存被恶意攻击或者误用。
设置合理的过期时间限制缓存的增长。
限制缓存的大小，避免占用过多内存资源。

在 asp.net core 中使用 IMemoryCache

在 asp.net core 中使用 IMemoryCache 非常简单，首先需要在 Program.cs 中注册服务：

var builder = WebApplication.CreateBuilder(args);
builder.Services.AddMemoryCache();

然后在需要使用缓存的地方注入 IMemoryCache：

public class MyService
{
    private readonly IMemoryCache _cache;
    public MyService(IMemoryCache cache)
    {
        _cache = cache;
    }
    public async Task<string> GetDataAsync(string key)
    {
        if (_cache.TryGetValue(key, out string value))
        {
            return value; // 从缓存中获取数据
        }
        else
        {
            value = await FetchDataFromDatabaseAsync(key); // 从数据库获取数据
            _cache.Set(key, value, TimeSpan.FromMinutes(5)); // 将数据存入缓存，设置过期时间为5分钟
            return value;
        }
    }
}

在上面的示例中，我们首先尝试从缓存中获取数据，如果缓存命中就直接返回，否则就从数据库获取数据，并将结果存入缓存中，设置过期时间为5分钟。这样下次有相同请求时，就可以直接从缓存中获取数据，提高性能和响应速度。

ASP.NET Core 外部依赖调用治理实战：HttpClientFactory、Polly 与幂等边界

Tue, 16 Jun 2026 17:04:23 +0800

订单服务最容易出现的稳定性问题，不是业务代码写错，而是下游支付、库存、短信网关一抖，整个接口成功率跟着雪崩。看起来只是一次超时，实际上会引发重试风暴、线程池占满、数据库回写积压。今天这篇就只做一件事：把外部依赖调用链路收敛到可控、可观测、可恢复的状态。

1. 问题背景：服务没挂，为什么成功率先掉

线上经常出现这种现象：

API 进程还活着，CPU 占用也不高，可能只有40%（举个例子，非真实数据）。
请求延迟从 200ms 拉到 6s。
失败率增多。

这类故障通常不是单点问题，大概就是遇到下面这些因素了：

HttpClient 使用方式不当。
超时和重试没有预算控制，单次请求被放大成多次慢调用。
对写操作直接重试却没有幂等约束，最终引发重复扣款或重复下单。

对于有多年经验的开发者来说，这不是 API 会不会调的问题，而是如何在高并发场景下把失败控制在局部，不让故障扩散到整条链路。

2. 原理解析：连接、超时、重试和幂等为什么必须一起设计

2.1 连接管理决定了你能扛多久

每次请求都新建 HttpClient，会导致连接池无法稳定复用，遇到峰值时容易把端口和连接资源打爆。更隐蔽的问题是连接存活太久导致 DNS 变更不生效，流量继续打到旧节点。

IHttpClientFactory 的价值不是语法糖，而是把连接池生命周期交给 SocketsHttpHandler 管理。常见配置里至少要有：

PooledConnectionLifetime：定期轮换连接，避免长期粘住旧地址。
MaxConnectionsPerServer：控制单机并发上限，避免瞬时过载。

2.2 超时预算必须先于重试策略

很多团队会先配“重试 3 次”，但没配总预算。结果是每次重试都等满超时，最后一个请求占用十几秒。

更稳妥的做法是分两层：

每次尝试超时（per-try timeout）：避免单次卡死。
整体调用超时（overall timeout）：限制整次业务调用的总耗时。

在 Resilience Pipeline 里，这两层要通过策略顺序明确表达：

outer timeout 放在 retry 外层，控制整次调用预算。
inner timeout 放在 retry 内层，控制单次 attempt。

先定预算，再谈重试次数，否则重试是放大器，不是保护器。

2.3 遵循行业共识，重试只能处理瞬时故障，不能处理业务冲突

可重试的典型对象是：网络抖动、连接中断、429、部分 5xx。不可重试的是：参数错误、鉴权失败、业务规则冲突。

如果把所有非 200 都重试，会把本来可快速失败的请求拖成长尾，最终压垮线程池和连接池。

2.4 写操作重试前必须定义幂等边界

对 POST/PUT 这类有副作用的请求，重试不是默认安全动作。支付创建、库存扣减、优惠券核销这类写操作，必须先定义幂等键和幂等存储，再启用自动重试。

ASP.NET Core 认证与授权实战：JWT、Policy 与权限边界落地

Tue, 16 Jun 2026 17:04:23 +0800

这篇文章不讨论完整身份平台建设，只聚焦 ASP.NET Core 里最常见、也最容易出错的一段：JWT 认证、Policy 授权，以及资源级权限边界该怎么落到代码里。

问题背景

真实现场：一个后台退款接口原本只允许财务角色调用，但线上排查发现，普通运营账号只要拿到有效 token，也能调用成功。

根因并不复杂：

接口加了 [Authorize]
系统只校验“是否登录”
没有继续校验角色、权限和资源归属

结果就是，认证做了，授权却只做了一半。

这也是很多系统的共性问题。认证只是在回答“你是谁”，授权回答的是“你能做什么”。如果这两件事没有拆开设计，接口表面安全，实际边界会很模糊。

原理解析

认证解决身份确认

认证的目标，是确认当前请求对应的是哪个用户、哪个客户端，常见做法就是校验 JWT 的签名、过期时间、签发方和受众。

这一步做完后，系统拿到的是一个 ClaimsPrincipal。它说明“请求身份可信”，但并不说明这个身份就有所有权限。

授权解决操作范围

授权是在认证之后，对用户能力做进一步判断。

在 ASP.NET Core 里，最常见的落点是 Policy。你可以按角色、权限声明、租户、部门或业务规则定义策略，而不是在控制器里到处手写 if 判断。

角色不等于权限模型

很多系统一开始只有 Admin、Operator、User 这几个角色，后来业务一复杂，就会发现角色粒度太粗。

更稳妥的方式通常是：

角色用于粗粒度分组
权限声明用于精细操作控制

例如“财务”和“运营”都属于后台用户，但是否允许退款、导出、调价，应该由权限声明决定，而不是只靠角色名硬编码。

资源级授权才是真正的边界

就算用户具备 orders.refund 权限，也不代表他可以操作所有订单。

很多越权问题出在这里：接口只校验了功能权限，没有校验资源归属，比如租户是否匹配、门店是否匹配、是否只能操作自己负责的数据。

所以完整授权通常分两层：

功能级：你有没有这个动作权限
资源级：你能不能对这条具体数据执行这个动作

示例代码

下面用一个“订单退款接口”来说明一套常见落地方式。

先配置 JWT 认证：

using Microsoft.AspNetCore.Authentication.JwtBearer;
using Microsoft.IdentityModel.Tokens;
using System.Text;

builder.Services
    .AddAuthentication(JwtBearerDefaults.AuthenticationScheme)
    .AddJwtBearer(options =>
    {
        options.TokenValidationParameters = new TokenValidationParameters
        {
            ValidateIssuer = true,
            ValidateAudience = true,
            ValidateIssuerSigningKey = true,
            ValidateLifetime = true,
            ValidIssuer = builder.Configuration["Jwt:Issuer"],
            ValidAudience = builder.Configuration["Jwt:Audience"],
            IssuerSigningKey = new SymmetricSecurityKey(
                Encoding.UTF8.GetBytes(builder.Configuration["Jwt:SigningKey"]!)),
            ClockSkew = TimeSpan.FromSeconds(30)
        };
    });

再定义基于权限声明的授权策略：

C# 异步编程实战：Task、ValueTask、线程池饥饿与背压设计

Tue, 16 Jun 2026 17:04:23 +0800

接口慢，不一定是数据库慢。很多系统在高峰期的核心问题，是异步链路写法导致线程池被慢慢耗空。

这类问题最麻烦的地方在于：

CPU 不一定打满
错误日志不一定明显
本地压测可能复现不出来

这篇文章围绕一个目标展开：让异步代码在高并发下“稳态运行”，而不是“平时很快，高峰崩盘”。

1. 问题背景：为什么会出现线程池饥饿

常见触发方式：

在 ASP.NET Core 请求中使用 .Result / .Wait()
把 I/O 任务包进 Task.Run
下游服务抖动时无限制并发重试

你以为是在“提速”，实际上是在制造排队。

2. 原理解析

2.1 `Task` 与调度

Task 表示异步操作，不等于“新线程”。多数场景下，它复用线程池线程在不同 I/O 等待阶段切换。

2.2 `ValueTask` 的边界

ValueTask 适合高频且经常同步完成的路径，减少分配；但它有使用约束，不应随意替换所有 Task。

2.3 线程池饥饿

当大量请求线程被阻塞等待 I/O，线程池补充速度跟不上时，后续请求只能排队，RT 开始抖动。

2.4 背压

背压本质是“主动限制进入系统的工作量”，通过队列边界和并发上限把峰值削平，换取整体稳定。

3. 示例代码：有边界的后台处理模型

下面是一个可落地的最小模型：Channel + 有界队列 + 固定并发消费者。

using System.Threading.Channels;

public sealed record ExportJob(Guid JobId, long UserId, DateTime CreatedAt);

public sealed class ExportQueue
{
    private readonly Channel<ExportJob> _channel = Channel.CreateBounded<ExportJob>(
        new BoundedChannelOptions(500)
        {
            FullMode = BoundedChannelFullMode.DropWrite,
            SingleWriter = false,
            SingleReader = false
        });

    public bool TryEnqueue(ExportJob job) => _channel.Writer.TryWrite(job);
    public IAsyncEnumerable<ExportJob> ReadAllAsync(CancellationToken ct) => _channel.Reader.ReadAllAsync(ct);
}

public sealed class ExportWorker : BackgroundService
{
    private readonly ExportQueue _queue;
    private readonly ILogger<ExportWorker> _logger;
    private readonly SemaphoreSlim _concurrency = new(4);

    public ExportWorker(ExportQueue queue, ILogger<ExportWorker> logger)
    {
        _queue = queue;
        _logger = logger;
    }

    protected override async Task ExecuteAsync(CancellationToken stoppingToken)
    {
        await foreach (var job in _queue.ReadAllAsync(stoppingToken))
        {
            _ = ProcessOneAsync(job, stoppingToken);
        }
    }

    private async Task ProcessOneAsync(ExportJob job, CancellationToken ct)
    {
        await _concurrency.WaitAsync(ct);
        try
        {
            await Task.Delay(200, ct); // 模拟 I/O
            _logger.LogInformation("export done {JobId}", job.JobId);
        }
        catch (OperationCanceledException)
        {
            // 正常退出
        }
        finally
        {
            _concurrency.Release();
        }
    }
}

API 层只负责入队，不直接做重任务：

EF Core 事务实战：SaveChanges、ExecutionStrategy、Outbox 与一致性边界

Tue, 16 Jun 2026 17:04:23 +0800

“事务加上了，这可不就问了嘛”。真正到线上一跑，问题就冒出来了：

数据库提交成功了，但消息没发出去
外部调用成功了，但本地事务回滚了
SQL 重试机制打开后，一段代码被重复执行了两次
同一个请求里明明都写在一起，最终状态还是不一致

这篇文章不讲抽象理论，直接回答一个工程问题：在 EF Core 里，事务边界到底该怎么画，哪些事情能靠数据库事务兜住，哪些事情必须换一种设计。

问题背景：为什么“写成功了”不等于业务真的成功

先看一个常见场景：下单成功后，需要同时完成三件事。

写入订单表
扣减库存
发出一条订单已创建消息，通知下游做履约

很多项目最开始都会写成这样：

await using var tx = await db.Database.BeginTransactionAsync(ct);

order.Status = OrderStatus.Created;
inventory.Reserve(quantity);

await db.SaveChangesAsync(ct);
await messageBus.PublishAsync(new OrderCreated(order.Id), ct);

await tx.CommitAsync(ct);

这段代码看起来很顺，实际有三个明显风险：

SaveChangesAsync 成功后，PublishAsync 失败，数据库已经提交，但下游不知道这笔订单存在
PublishAsync 成功后，CommitAsync 失败，下游收到消息，但数据库里没有最终结果
如果启用了连接重试，整段逻辑可能被重放，导致消息重复发送

问题的根因不是 EF Core 不行，而是数据库事务的能力边界经常被高估了。

数据库事务能保证的是“同一个数据库连接里的状态一致”，它保证不了消息队列、HTTP 调用、Redis 写入这些外部副作用跟你一起原子提交。

原理解析：EF Core 里的事务到底管到哪一步

`SaveChanges` 默认就带事务，但范围很有限

对关系型数据库来说，EF Core 在一次 SaveChanges 中默认会开启事务，确保这一批 insert/update/delete 要么全部成功，要么全部失败。

也就是说，下面这种写法本身就已经带事务语义：

order.Status = OrderStatus.Created;
inventory.Reserve(quantity);

await db.SaveChangesAsync(ct);

这个默认事务适合的场景很明确：

同一个 DbContext
同一个数据库
同一次提交
没有外部副作用参与

只有当你要把多次 SaveChanges、多段仓储调用、或跨服务动作绑在一起，就要考虑显式事务。

显式事务解决的是“多步数据库写入”

如果业务上需要多次落库，而且这些写入必须成组成功，可以显式开启事务：

await using var tx = await db.Database.BeginTransactionAsync(ct);

order.Status = OrderStatus.Created;
await db.SaveChangesAsync(ct);

payment.Status = PaymentStatus.Pending;
await db.SaveChangesAsync(ct);

await tx.CommitAsync(ct);

这类事务能解决的问题是：多次数据库操作之间不能只成功一半。

EF Core 写入链路实战：从 ChangeTracker 到 SQL Batch 的性能诊断与优化

Tue, 16 Jun 2026 17:04:23 +0800

这篇文章讨论一个问题：一次写入请求从实体变更到数据库落盘，中间到底发生了什么，哪里最容易慢，以及应该怎么定位。

问题背景

真实场景：订单系统在白天吞吐稳定，凌晨高峰出现周期性尖峰。接口平均耗时变化不大，但 P95 从 80ms 抬到 420ms，数据库 CPU 也出现波峰。

排查后发现：

应用层每次批量处理 2000 条数据
循环中频繁触发变更检测
每条数据都单独 SaveChanges
最终生成大量碎片化 SQL 往返

这类问题看起来像“数据库有点拉，扛不住了”，实际上很多成本来自应用侧写入链路组织不当。

原理解析

`ChangeTracker` 负责记录变更

EF Core 需要知道哪些实体是新增、修改、删除，这些状态都由 ChangeTracker 管理。默认情况下，EF Core 会在多个时机触发 DetectChanges，例如：

调用 SaveChanges / SaveChangesAsync
访问部分跟踪集合
某些 Add / Attach 组合场景

如果一个 DbContext 里挂了大量实体，频繁 DetectChanges 会带来明显 CPU 开销。

`SaveChanges` 并不是“一条语句”

一次 SaveChanges 大致会经历这些步骤：

执行变更检测，确定实体状态
生成修改命令（insert/update/delete）
按提供程序规则组装批次（batch）
开启事务并执行命令
成功后调用 AcceptAllChanges

性能问题通常出在 2-4 步：命令太碎、批次太小、往返太多、事务范围不合理。

SQL Batch 决定数据库往返次数

以 SQL Server 为例，EF Core 会尽可能把多条 DML 合并到一个批次中执行，但合并能力受多种因素影响：

EF Core 原生 SQL 实战：FromSql、SqlQuery 与对象映射边界

Tue, 16 Jun 2026 17:04:23 +0800

做 EF Core 一段时间后，很多人都会遇到同一个节点：常规 LINQ 能覆盖大多数查询，但一到复杂报表、视图或者历史 SQL 复用场景，就会开始考虑原生 SQL。问题不在于“能不能写 SQL”，而在于怎么写得可维护、可观测、还能和 EF Core 的映射体系配合好。这篇文章讲解 FromSql、SqlQuery 的使用边界和对象映射的一些坑。

1. 问题背景：为什么原生 SQL 常常能跑但难以长期维护

在系统演进到中后期后，下面这些场景非常常见：

报表查询需要 GROUP BY、聚合，LINQ 写出来可读性很差。
历史系统已经有稳定 SQL，需要在新服务里复用。
部分查询要精确控制执行计划，团队希望直接落 SQL。

这时候“能跑”的版本通常很快就能写出来，但过一段时间就会暴露问题：

SQL 拼接字符串，参数化做得不一致，埋下注入和计划污染风险。
映射类型定义不清晰，字段一改名就出现运行时映射异常。
查询读模型和实体模型混用，导致跟踪行为和更新语义变得混乱。
慢 SQL 能看到语句，但定位不到具体业务查询意图。

所以这篇不是教你“怎么在 EF Core 里执行 SQL”，而是讲“如何把原生 SQL 纳入 EF Core 的工程边界”。

2. 原理解析：先分清 FromSql 和 SqlQuery 的职责

FromSql 和 SqlQuery 都能执行原生 SQL，但它们解决的是不同问题。

2.1 FromSql：面向 DbSet 的查询入口

FromSql 适合挂在 DbSet 或 Set<T>() 上执行原生 SQL，典型用途有两类：

查询实体类型（可跟踪，也可 AsNoTracking）
查询 Keyless 读模型（只读投影）

关键点：

EF Core 并发冲突处理实战：乐观锁、RowVersion 与 DbUpdateConcurrencyException

Tue, 16 Jun 2026 17:04:23 +0800

并发冲突是 EF Core 里最容易被忽视、出了事又最难排查的问题之一。这篇文章聊聊它的机制、怎么配置乐观锁、冲突异常怎么处理，以及几个工程上容易踩的坑。

问题背景

真实场景：电商平台秒杀活动，同一件商品被多个请求并发扣减库存。业务日志里一切正常，但库存对不上——扣了 100 件，实际库存只减少了 60 件。

排查后发现：

多个请求几乎同时读取了库存为 200 的记录
各自在内存里把数量减掉后写回
数据库里最后一个写入覆盖了前面所有写入的结果
EF Core 没有报任何错误，因为没有配置并发控制

这就是典型的"丢失更新"（Lost Update）。

原理解析

EF Core 的并发控制模型

EF Core 支持乐观并发，不在读取时加锁，而是在写入时检测：

提交更新时，把当前数据库中读取到的"令牌值"放进 WHERE 条件，如果这行在读取之后被别人改动过，令牌不匹配，受影响行数为 0，EF Core 就会抛出 DbUpdateConcurrencyException。

生成的 SQL 大概长这样：

UPDATE Products
SET Stock = @newStock
WHERE Id = @id AND RowVersion = @originalRowVersion

如果 RowVersion 被别人改过，WHERE 匹配不到，更新语句影响 0 行，EF Core 检测到后抛异常。

两种并发令牌配置方式

方式一：[Timestamp] / IsRowVersion()（推荐）

数据库自动维护，每次行更新时自增，不需要应用层干预：

public sealed class Product
{
    public int Id { get; set; }
    public string Name { get; set; } = string.Empty;
    public int Stock { get; set; }

    [Timestamp]
    public byte[] RowVersion { get; set; } = [];
}

或者在 OnModelCreating 里配置：

EF Core 慢查询排查实战：TagWith、OpenTelemetry 与执行计划

Tue, 16 Jun 2026 17:04:23 +0800

EF Core 性能问题里，最折磨人的不是“慢”，而是“慢得没规律”，线上卡，测试又无法复现。

很多小D、小W同学都经历过这种现场：

压测数据很好看
数据库 CPU 没打满
业务代码看起来也没什么大问题

你改了几个 Include，可能短期有效，但过两周又抖回来。根因往往不是某一行 LINQ 写错，而是整条排查链路没打通。

这篇文章就做一件事：给你一套能线上落地的 EF Core 慢查询定位闭环，从应用日志一路追到数据库执行计划，不靠猜。

问题背景：为什么本地快、线上慢

真实场景：订单列表接口平时 80ms 左右，高峰时段 P95 抬到 1s。你的第一反应是“数据库是不是扛不住了”，但监控显示：

数据库 CPU 长期低于 50%
连接池没有打满
磁盘 IO 没明显异常

排查下来，又遇到两个组合问题：

列表查询没有打 SQL 标签，日志里几百条 SQL 根本分不出谁是谁
某些筛选条件线上本地索引匹配不同，SQL 文本相同但参数分布不同，执行计划差异很大

也就是说，问题不是“不会优化 SQL”，而是“看不见慢点在哪”。

原理解析：慢查询定位为什么总是卡在一半

EF Core 的查询链路大致是：

LINQ 表达式翻译成 SQL
命令发送到数据库执行
结果集回传并在应用层物化

很多排查第一步都把 SQL 抓出来看看，忽略了第 2、3 步的上下文信息，比如：

这条 SQL 是哪个接口触发的
这次慢是数据库执行慢，还是返回数据太大导致物化慢
慢的是固定 SQL，还是同模板下某些参数更慢

要拿到这些信息，最实用的组合就是：

TagWith：给 SQL 打业务标签
OpenTelemetry：采集耗时、TraceId、SQL 标签并统一上报
执行计划：确认索引命中、回表、扫描和 Key Lookup

三者合起来，才能形成可服用、可验证的排查闭环。

EF Core 拦截器实战：SaveChangesInterceptor、CommandInterceptor 与审计落地

Tue, 16 Jun 2026 17:04:23 +0800

审计不是“给表补几个 CreatedBy 字段”，也不是“在业务方法里顺手记日志”。它本质上是系统级可追溯能力，设计目标是让系统在任何写路径下都能稳定回答四个问题：谁发起、改了什么、何时发生、通过哪条链路触发。

真正的难点不在 API 用法，而在系统设计阶段是否把审计定义成基础设施能力。这里聚焦两层落地：SaveChangesInterceptor 负责实体变更审计，CommandInterceptor 负责 SQL 执行审计，两者一起组成可观测、可追溯、可审计的最小闭环。

1. 问题背景：为什么审计必须在系统设计期落地

如果你刚开始做系统设计，通常会先把功能跑通，再逐步补监控、日志和审计。这条路径很正常，但系统从单一写入口演进到多入口后，审计会出现一些典型断层：

HTTP 请求有 TraceId，但数据库变更记录无法关联到具体调用链路。
Web 接口有审计字段，批处理、后台任务、集成事件消费链路没有统一审计。
SQL 慢查询能看到语句本身，但看不到对应业务场景和调用来源。
合规追查时能找到结果，找不到完整过程和责任主体。

这些现象不是某个人“写错了”，而是系统设计阶段还没有建立统一审计模型：

还没先定义统一的审计契约（身份、时间、来源、关联链路）。
写入路径没有统一审计入口，不同调用通道口径自然会分化。
变更审计和 SQL 观测没有打通，排障时很难快速复原完整链路。
只有开发约定，没有系统级自动机制，随着迭代推进就容易出现漏记。

这篇文章要解决的核心问题不是“把审计代码写到哪一层”，而是“如何在系统层提供默认生效、可验证、可扩展的审计能力”，并且让这套能力能跟着系统规模一起演进。

2. 原理解析：先拆职责，再落地拦截器

如果你是第一次从系统设计角度做审计，最稳妥的方法是先做职责拆分，再做实现落地。这里按“三步法”来理解：先统一实体变更审计，再统一 SQL 观测入口，最后明确拦截器边界。

2.1 第一步：用 SaveChangesInterceptor 统一实体变更审计

SaveChangesInterceptor 适合处理实体状态相关规则，例如：

Added 时补 CreatedAt/CreatedBy
Modified 时补 UpdatedAt/UpdatedBy
软删除时把 Deleted 改写成 Modified + IsDeleted

这类逻辑和实体状态强相关，放在拦截器里能覆盖所有调用路径，避免每个 Service 重复写一遍。

2.2 第二步：用 CommandInterceptor 统一 SQL 观测入口

DbCommandInterceptor 适合做 SQL 级别的统一观测：

慢 SQL 记录
SQL 失败统一日志
参数快照和调用耗时

它不适合做业务决策，但非常适合做“排障入口统一化”。

EF Core 查询性能实战：Include、投影与跟踪策略边界

Tue, 16 Jun 2026 17:04:23 +0800

很多团队把 EF Core 的性能问题归因于“ORM 天生慢”，但线上真实情况通常是：

查询写法对 SQL 形态不敏感
默认跟踪被滥用
图省事一次 Include 到底

结果是接口能跑，但高峰时段 P95 持续抬高，数据库 CPU 和网络带宽一起被拖上去。

这篇文章聚焦一个目标：把 EF Core 查询从“能查到数据”升级到“可预测、可解释、可优化”。

1. 问题背景：列表页为什么越改越慢

一个典型场景：订单列表页需要展示订单、客户、明细、商品。

最直觉的写法是连续 Include：

var orders = await db.Orders
    .Include(o => o.Customer)
    .Include(o => o.Items)
        .ThenInclude(i => i.Product)
    .Where(o => o.CreatedAt >= from && o.CreatedAt < to)
    .OrderByDescending(o => o.CreatedAt)
    .Take(50)
    .ToListAsync();

这段代码看起来“很完整”，但常见后果是：

结果集行数被笛卡尔放大
应用端做了大量重复对象反序列化和跟踪
实际只显示 6 个字段，却把整个对象图都拉回来了

2. 原理解析：EF Core 查询成本主要花在哪里

2.1 翻译成本

LINQ 先被转换为表达式树，再翻译成 SQL。复杂投影、方法调用、局部函数容易导致翻译退化或直接失败。

2.2 执行与网络成本

Include 深度越深，JOIN 越复杂，网络回包越大。很多慢查询不是数据库“算得慢”，而是“传得多”。

2.3 跟踪成本

默认跟踪模式会创建实体快照，便于更新，但纯读场景这部分是额外开销。

2.4 物化成本

即使 SQL 很快，应用层物化大量实体和导航属性也会抬高 CPU 与内存分配。

3. 示例代码：从全量实体到精准投影

先给出推荐的读模型查询写法：

public sealed record OrderListItemDto(
    long Id,
    string OrderNo,
    string CustomerName,
    decimal TotalAmount,
    int ItemCount,
    DateTime CreatedAt);

var query = db.Orders
    .AsNoTracking()
    .Where(o => o.CreatedAt >= from && o.CreatedAt < to)
    .OrderByDescending(o => o.CreatedAt)
    .Select(o => new OrderListItemDto(
        o.Id,
        o.OrderNo,
        o.Customer.Name,
        o.Items.Sum(i => i.Quantity * i.UnitPrice),
        o.Items.Count,
        o.CreatedAt));

var page = await query.Take(50).ToListAsync();

对于高频、形态固定的查询，可以进一步使用编译查询：

Microsoft Agent Framework + Kimi API 实战：控制台应用跑通单次与多轮 Agent 对话

Tue, 16 Jun 2026 17:04:23 +0800

引言

如果你的技术栈主要是 .NET，想要快速上手 Agent 开发，那么 Microsoft Agent Framework 是一个非常不错的选择。它提供了对话管理、上下文保持、工具调用等一系列功能，让你能专注于业务逻辑实现。

这篇文章用一个最小控制台应用，通过 maf + kimi ai 合作，完成下面的目标：

使用 Microsoft Agent Framework（NuGet 包名为 Microsoft.Agents.AI 体系）
使用 Kimi 的 OpenAI 兼容接口
实现单次对话
实现多轮对话（基于 Session 保留上下文）

你把代码复制后，只要配置好 KIMI_API_KEY 就能跑起来。

环境准备

.NET SDK 9.0+
Kimi API Key
一个控制台项目

创建项目并安装依赖：

dotnet new console -n AgentConsoleApp
cd AgentConsoleApp

dotnet add package Microsoft.Agents.AI
dotnet add package Microsoft.Agents.AI.OpenAI
dotnet add package OpenAI

开发实战

一、配置 Kimi API 的访问参数

注意：在实际开发中，确保妥善保管 API 密钥，避免泄露。我这里把密钥放在了环境变量中，代码中通过读取环境变量来获取密钥。

Redis：延迟双删的适用边界与落地细节

Tue, 16 Jun 2026 17:04:23 +0800

延迟双删不是新概念，但线上一出缓存脏读，我曾经在项目中把它当成标准答案直接套进去。结果通常是代码写了两次删除，问题却没真正收住。

这篇就聚焦一个知识点：延迟双删到底解决什么问题，为什么它只能改善最终一致概率，以及在 .NET 服务里怎么把第二次删除做得更稳一点。

1. 问题背景：数据库已经更新，为什么缓存里还是旧值

聊一个高频场景：商品详情页读 Redis，后台商品编辑写数据库。读流量远大于写流量，最常见的缓存策略是 Cache Aside。

我的更新代码长这样：先更新数据库，再删除缓存。平时看起来没什么问题，但高并发下还是会偶发脏数据。业务侧看到的现象一般是：管理后台已经改价成功，前台用户短时间内还能查到旧价格。

关键不在“删没删缓存”，而在并发时序。

一个典型过程是这样的：

线程 A 更新数据库中的商品价格
线程 A 删除 Redis 中的商品缓存
线程 B 正好在这个空档读缓存未命中，开始查数据库
线程 B 读到的仍然是旧值，或者读到了事务提交前的旧快照
线程 B 把旧值重新写回 Redis

这时候数据库是新值，缓存却又变回旧值了。问题根因不是删除动作本身，而是删除之后，旧数据又被别的请求回填进缓存。

如果只看文字，这个并发窗口不算直观。把它画成时序图会更清楚：

sequenceDiagram
    autonumber
    participant A as 写线程A
    participant R as Redis
    participant D as Database
    participant B as 读线程B

    A->>D: 更新商品价格为新值
    A->>R: 删除商品缓存
    B->>R: 读取商品缓存
    R-->>B: 未命中
    B->>D: 查询商品数据
    D-->>B: 返回旧值或旧快照
    B->>R: 回填旧值到缓存
    B-->>B: 后续请求命中旧缓存

这张图里最关键的不是“删缓存”这一步，而是删完之后到下一次稳定回填新值之前，中间存在一个旧值重新进入 Redis 的窗口。延迟双删补的就是这个窗口。

Serilog + OpenTelemetry：从请求日志到链路追踪的关联落地

Tue, 16 Jun 2026 17:04:23 +0800

这篇直接给落地方案，不再讲结构化日志的背景概念。目标只有一个：在 ASP.NET Core 服务里，把 Serilog 日志和 OpenTelemetry 链路追踪打通，排障时可以从一条错误日志直接跳到完整 Trace。

1. 问题背景：这篇要交付什么

按下面步骤做完，你会得到一条可执行排障链路：

日志里稳定带上 TraceId、SpanId、RequestPath、RequestMethod
业务日志统一输出 OrderId、TenantId 这类主键字段
下游 HTTP 调用失败时，日志可直接回跳到同一 TraceId
现场排障固定为 3 步：查日志 -> 拿 TraceId -> 打开链路

这篇示例默认运行环境：

.NET 8
Serilog
OpenTelemetry + OTLP

2. 原理解析：实施前约定与字段契约

先把约定定下来，后面配置才不会反复返工。

2.1 平台层字段（必须统一）

TraceId：整条请求链路唯一键
SpanId：当前节点唯一键
RequestPath：请求路径
RequestMethod：请求方法
StatusCode：响应码

2.2 业务层字段（按场景补充）

订单域：OrderId、CustomerId
多租户：TenantId
外部依赖：DependencyName、DownstreamStatusCode

2.3 字段命名规则（一次定死）

统一使用 PascalCase
同义字段只保留一个名字，比如只用 TraceId
业务字段保持稳定，不随文案调整

3. 示例代码：按步骤落地

3.1 安装依赖

Serilog.AspNetCore
Serilog.Sinks.Console
Serilog.Enrichers.Environment
OpenTelemetry.Extensions.Hosting
OpenTelemetry.Instrumentation.AspNetCore
OpenTelemetry.Instrumentation.Http
OpenTelemetry.Exporter.OpenTelemetryProtocol

3.2 第一步：配置 Serilog 与 OpenTelemetry

把这段放进 Program.cs，先打通基础链路：

Serilog：从结构化日志认知到 .NET 工程落地

Tue, 16 Jun 2026 17:04:23 +0800

问题背景

很多项目不缺日志，缺的是有用的日志。

平时接口跑得顺，大家都觉得日志够用。真到线上出问题，日志的短板会一下子暴露出来。

比如订单接口偶发超时，日志里只剩这么一句：

Create order failed for customer 1024, cost 3800ms, trace abc123

这种日志平时看着还行，真到线上排障时基本帮不上太多忙：

你没法直接按 CustomerId、TraceId、ElapsedMs 做过滤和聚合，只能全文搜索
同一个字段今天写 customerId，明天写 userId，后天又换成 client_id，查询条件根本沉淀不下来
想统计某类错误的数量、平均耗时、失败占比，往往还得写额外脚本二次清洗
日志平台能做的分析能力很弱，因为它拿到的只是一段文本，不是一条可分析的数据

问题往往不在于日志打得不够多，而在于日志从一开始就没按可检索、可聚合、可关联的方式去设计。

传统文本日志更像写给人看的备注，结构化日志才像写给系统消费的数据。业务一旦进入多人协作、线上排障、统一观测这些阶段，日志就不再只是打出来看一眼，而是排障、审计、告警、指标补充、链路追踪的一部分。走到这一步，结构化日志就不是锦上添花，而是该补的基础课。

原理解析

什么是结构化日志

很多人第一次接触结构化日志，会下意识把重点放在 JSON 输出上。其实 JSON 只是表现形式，核心不在日志长什么样，而在日志里的字段有没有明确语义，后续能不能被系统稳定识别。

先看两种写法的差异。

普通文本日志：

logger.LogInformation(
    $"Order {order.Id} created for customer {order.CustomerId}, amount {order.Amount}, cost {elapsedMs}ms"
);

这行代码最终只会产出一段字符串。人类看没问题，但日志平台拿到以后，并不知道哪一段是订单号，哪一段是金额，哪一段是耗时。

结构化日志：

logger.LogInformation(
    "Order {OrderId} created for customer {CustomerId}, amount {Amount}, cost {ElapsedMs}ms",
    order.Id,
    order.CustomerId,
    order.Amount,
    elapsedMs
);

换成这种写法以后，日志框架记录的就不再是一整段普通字符串，而是一个日志事件：

模板是 Order {OrderId} created for customer {CustomerId}, amount {Amount}, cost {ElapsedMs}ms
属性是 OrderId、CustomerId、Amount、ElapsedMs
元数据还包括时间、级别、异常、来源、线程、TraceId 这些上下文

输出到控制台时，它可以渲染成人能直接看的句子；送到 Elasticsearch、Seq、Loki 或 OpenTelemetry 后端时，它又能以字段化数据的形式被检索和聚合。

从 IApplicationBuilder 到 RequestDelegate：ASP.NET Core 请求管线性能与可观测性

Tue, 16 Jun 2026 17:04:23 +0800

很多团队做性能优化时，第一反应是改 SQL、加缓存、扩机器。结果接口还是慢，而且慢得不稳定。

这类问题里，有一部分根因并不在业务代码，而在请求进入业务之前就已经产生了: 中间件顺序、重复序列化、过重日志、异常处理位置不当，都会把每个请求的固定成本悄悄抬高。

这篇文章我们不讲抽象概念，直接从一个真实工程场景出发，拆开 ASP.NET Core 请求管线，回答三个问题:

请求管线到底是怎么执行的
哪些中间件写法会稳定拉低吞吐
如何在不牺牲可观测性的前提下，把链路成本控制住

1. 问题背景: 为什么明明 CPU 不高，RT 却在抖

先看一个常见现象:

峰值时段 P95 从 35ms 涨到 90ms
CPU 只到 45%
数据库监控正常
线程池没有明显爆满

像商场收银台排队: 收银员速度没变，库存系统也没卡，但每位顾客在真正结账前都要先填两张表、复印一次小票、走一段绕路。单人多花 10 秒，队伍就会在高峰时段整体失控。

在 Web 服务里，这段“真正结账前的绕路”就是请求管线上的固定开销。

典型问题包括:

将高成本日志中间件放在链路最前面，且对所有请求都做完整 Body 记录
鉴权、异常处理、路由等中间件顺序错误，导致重复执行或额外分支判断
在中间件中做同步阻塞 I/O
将一些本该按采样写出的指标，变成了每请求都完整打点

2. 原理解析: IApplicationBuilder 如何变成 RequestDelegate

ASP.NET Core 启动时，IApplicationBuilder 会把你注册的中间件构造成一个 RequestDelegate 链。

关键点只有两个，但经常被忽略:

中间件按“注册顺序”进入，按“逆序”包裹执行。每个中间件把后续链路作为自己的 next，形成嵌套闭包。
任意中间件都可以不调用 next()，从而短路后续链路。

一个简化模型如下:

RequestDelegate app = context => Task.CompletedTask;

app = MiddlewareC(app);
app = MiddlewareB(app);
app = MiddlewareA(app);

// 实际执行顺序: A -> B -> C -> Endpoint -> C -> B -> A

这意味着:

从其他语言到 Pythonic 思维的完整迁移手册

Tue, 16 Jun 2026 17:04:23 +0800

想学学python搞ai应用开发，但是好多教程都是从“hello world" 开始，太痛苦了。因此，整理了这份文档。面向有编程基础的开发者，快速掌握 Python 开发全貌

一、环境管理

Python 版本管理

macOS / Linux（pyenv）

curl https://pyenv.run | bash

pyenv install 3.12.0        # 安装指定版本
pyenv global 3.12.0         # 设置全局版本
pyenv local 3.11.0          # 设置当前目录版本（生成 .python-version）
pyenv versions              # 列出所有已安装版本
pyenv which python          # 查看当前 python 路径

Windows（PowerShell）

winget search Python.Python        # 搜索可用版本
winget install Python.Python.3.12  # 安装
winget upgrade Python.Python.3.12  # 升级

python --version
pip --version

⚠️ 使用官网 .exe 安装包时，务必勾选 Add Python to PATH，否则终端找不到 python 命令。

Invoke-WebRequest -UseBasicParsing `
  -Uri "https://raw.githubusercontent.com/pyenv-win/pyenv-win/master/pyenv-win/install-pyenv-win.ps1" `
  -OutFile "$HOME\install-pyenv-win.ps1"
& "$HOME\install-pyenv-win.ps1"

pyenv install 3.12.0
pyenv global 3.12.0
pyenv local 3.11.0
pyenv versions
pyenv rehash              # 安装新版本后刷新 shims

where.exe python
$env:PATH -split ";"

虚拟环境

macOS / Linux

python -m venv .venv              # 创建
source .venv/bin/activate         # 激活
deactivate                        # 退出

Windows（PowerShell）

python -m venv .venv

.\.venv\Scripts\Activate.ps1


deactivate

Remove-Item -Recurse -Force .venv

⚠️ 首次激活若报"无法加载文件"执行策略错误，运行一次即可解决：

开发实战：ASP.NET Core + EF Core 实现动态可扩展的分页方案

Tue, 16 Jun 2026 17:04:23 +0800

引言

欢迎阅读，这篇文章主要面向初级开发者。

在开始之前，先问你一个问题：你做的系统，是不是每次增加一个查询条件或者排序字段，都要去请求参数对象里加一个属性，然后再跑去改 EF Core 的查询逻辑？

如果是，那这篇文章应该对你有用。我会带你做一个统一的、扩展起来不那么麻烦的分页查询方案。整体思路是四件事：统一入参、统一出参、动态排序、动态过滤。

统一请求参数

先定义一个公共的 QueryParameters 解决这个问题：

public class QueryParameters
{
    private const int MaxPageSize = 100;
    private int _pageSize = 10;

    public int PageNumber { get; set; } = 1;

    // 限制最大值，防止前端传一个很大数值把数据库搞崩了
    public int PageSize
    {
        get => _pageSize;
        set => _pageSize = value > MaxPageSize ? MaxPageSize : value;
    }

    // 支持多字段排序，格式："name desc,price asc"
    public string? SortBy { get; set; }

    // 通用关键词搜索
    public string? Search { get; set; }

    // 动态过滤条件
    public List<FilterItem> Filters { get; set; } = [];

    // 要返回的字段，逗号分隔："id,name,price"，不传则返回全部
    public string? Fields { get; set; }
}

ASP.NET Core 的模型绑定会自动把 query string 映射到这个对象，不需要手动解析。后续如果某个接口有额外参数，继承它加字段就行，不用每次从头定义。

统一响应包装器

返回值也统一一下，把分页信息和数据放在一起，调用方就不用自己拼了：

public class PagedResponse<T>
{
    // IReadOnlyList 防止外部随意修改集合
    public IReadOnlyList<T> Data { get; init; } = [];

    public int PageNumber { get; init; }
    public int PageSize { get; init; }
    public int TotalRecords { get; init; }

    public int TotalPages => (int)Math.Ceiling(TotalRecords / (double)PageSize);
    public bool HasNextPage => PageNumber < TotalPages;
    public bool HasPreviousPage => PageNumber > 1;
}

Data 是任意类型的集合，用 IReadOnlyList 防止被意外修改。TotalPages、HasNextPage 和 HasPreviousPage 三个是计算属性，不需要单独赋值。

开发实战：在 ASP.NET Core 与 EF Core 中，实现多租户数据隔离

Tue, 16 Jun 2026 17:04:23 +0800

在一个项目中，方便为多个客户提供服务，我们需要实现多租户系统。多租户系统，就是多个客户共享一个运行的项目实例，同时确保每个客户的数据安全隔离（你看不见我，我看不见你）。

这篇文章，我们将落地在 ASP.NET Core 和 Entity Framework Core 中，基于 TenantId 的全局过滤机制，实现多租户数据隔离。

原理解析

先确定隔离模型

多租户常见有三种模型：

每个租户一套数据库
共享数据库，不同 Schema
共享数据库、共享表，用 TenantId 做逻辑隔离

对大多数中小体量业务，第三种最常见，迁移成本最低，适合快速上线。

请求进入时解析租户身份
DbContext 自动带上当前租户
查询默认加 TenantId 过滤
写入自动补 TenantId

这样做以后，业务代码只关注“查什么”，不用每次都关心“记没记得加租户条件”。

ASP.NET Core + EF Core 的最小 MVP 实现

在 ASP.NET Core 里，租户信息通常来自域名、Header、Token Claim。为了演示清晰，这里我们用 Header X-Tenant-Id。

在 EF Core 里，用全局查询过滤器筛选：

modelBuilder.Entity<Order>()
    .HasQueryFilter(o => o.TenantId == _tenantProvider.TenantId);

然后在 SaveChanges 阶段，给新增实体自动写入 TenantId，避免脏数据。

示例代码

反例：手动传 tenantId

[HttpGet("orders")]
public async Task<IReadOnlyList<Order>> GetOrders([FromQuery] Guid tenantId)
{
    return await _db.Orders
        .Where(o => o.TenantId == tenantId)
        .ToListAsync();
}

这个写法的问题是隔离规则散在每个接口里，漏一次客户数据就串了。

正例：把租户隔离下沉到底层

1) 定义租户上下文

public interface ITenantProvider
{
    Guid TenantId { get; }
}

public sealed class HttpTenantProvider : ITenantProvider
{
    private readonly IHttpContextAccessor _httpContextAccessor;

    public HttpTenantProvider(IHttpContextAccessor httpContextAccessor)
    {
        _httpContextAccessor = httpContextAccessor;
    }

    public Guid TenantId
    {
        get
        {
            var headerValue = _httpContextAccessor.HttpContext?
                .Request.Headers["X-Tenant-Id"]
                .FirstOrDefault();

            if (!Guid.TryParse(headerValue, out var tenantId))
            {
                throw new InvalidOperationException("Missing or invalid X-Tenant-Id header.");
            }

            return tenantId;
        }
    }
}

2) 实体约束：需要租户字段

public interface ITenantEntity
{
    Guid TenantId { get; set; }
}

public sealed class Order : ITenantEntity
{
    public long Id { get; set; }
    public Guid TenantId { get; set; }
    public string OrderNo { get; set; } = string.Empty;
    public decimal Amount { get; set; }
    public DateTime CreatedAt { get; set; }
}

3) DbContext 全局过滤 + 自动写入 TenantId

public sealed class AppDbContext : DbContext
{
    private readonly ITenantProvider _tenantProvider;

    public AppDbContext(
        DbContextOptions<AppDbContext> options,
        ITenantProvider tenantProvider) : base(options)
    {
        _tenantProvider = tenantProvider;
    }

    public DbSet<Order> Orders => Set<Order>();

    protected override void OnModelCreating(ModelBuilder modelBuilder)
    {
        modelBuilder.Entity<Order>()
            .HasQueryFilter(o => o.TenantId == _tenantProvider.TenantId);

        base.OnModelCreating(modelBuilder);
    }

    public override Task<int> SaveChangesAsync(CancellationToken cancellationToken = default)
    {
        var tenantId = _tenantProvider.TenantId;

        foreach (var entry in ChangeTracker.Entries<ITenantEntity>()
                     .Where(e => e.State == EntityState.Added))
        {
            entry.Entity.TenantId = tenantId;
        }

        return base.SaveChangesAsync(cancellationToken);
    }
}

4) Program 注册

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddHttpContextAccessor();
builder.Services.AddScoped<ITenantProvider, HttpTenantProvider>();

builder.Services.AddDbContext<AppDbContext>(options =>
{
    options.UseSqlServer(builder.Configuration.GetConnectionString("Default"));
});

var app = builder.Build();
app.MapControllers();
app.Run();

总结

ASP.NET Core 负责拿到租户身份，EF Core 负责做过滤和写入约束，这两层配合起来就能把多租户落地。

聊聊 ASP.NET Core 中间件和过滤器的区别

Tue, 16 Jun 2026 17:04:23 +0800

引言

不知道你有没有在面试中遇到过这样的问题：“中间件和过滤器的区别是什么？"，或者在平时开发中思考过：“一个请求进来，ASP.NET Core 到底是怎么一步步处理它的？”

这篇文章就来聊聊，不会涉及太深的源码，主要面向初级开发者，帮你建立一个清晰的认知。

先说中间件

中间件是 ASP.NET Core 处理 HTTP 请求的基本部件，是框架本身的组成部分。

每一个请求进来后，按照 Use 的注册顺序，依次经过每一个中间件，到达终端后，再按照相反的方向依次返回。一系列中间件串联起来，就组成了 ASP.NET Core 的请求管道。这个模型有人叫"洋葱模型”，也有人叫"俄罗斯套娃模型"，都是一个意思。

请求 →  中间件A → 中间件B → 中间件C（终端）
响应 ←  中间件A ← 中间件B ←

中间件可以做什么呢？它收到请求后，可以在请求/响应对象上加点佐料（自己的逻辑），然后调用 next() 把请求传递给下一个中间件。如果不调用 next()，请求就在这里短路了，后面的中间件不会执行，这个中间件就成了终端中间件。

下面是一个简单示例，演示如何自定义一个记录请求耗时的中间件：

// 定义中间件类
public class TimingMiddleware
{
    private readonly RequestDelegate _next;

    public TimingMiddleware(RequestDelegate next)
    {
        _next = next;
    }

    public async Task InvokeAsync(HttpContext context)
    {
        var sw = Stopwatch.StartNew();

        // 调用 next()，请求继续往下走
        await _next(context);

        // next() 返回后，响应正在往回走
        sw.Stop();
        Console.WriteLine($"[{context.Request.Path}] 耗时：{sw.ElapsedMilliseconds}ms");
    }
}

// 在 Program.cs 中注册
var app = builder.Build();

app.UseMiddleware<TimingMiddleware>();  // 注册自定义中间件

app.UseRouting();
app.UseAuthorization();
app.MapControllers();

app.Run();

如果你不想单独定义一个类，也可以用 app.Use 直接写一个内联中间件：

Posts on Coding with Denglei

.NET 10 使用 Microsoft.AspNetCore.OpenApi 实现 API 版本管理

为什么 API 版本管理如此重要？

上手 Microsoft.AspNetCore.OpenApi 和 Asp.Versioning

.NET 中 .Result 避坑指南：不同框架下的死锁与线程池饥饿

问题背景

原理：同一个坑，两种后果

场景 1：ASP.NET Classic / WinForms / WPF（有 SynchronizationContext）

场景 2：ASP.NET Core（默认无 SynchronizationContext）

最小对照示例

如何避坑（只保留最关键三条）

一句结论

.NET 内存性能优化实战：Span、ArrayPool、GC 与 LOH 控制

问题背景

原理解析

代际 GC

LOH（大对象堆）

Span<T> 与 ArrayPool<T>

示例代码

ASP.NET Core 内存缓存实战：一篇搞懂该怎么配、怎么避坑

引言

什么是缓存

asp.net core 中的缓存类型

asp.net core 的内存缓存 IMemoryCache

在 asp.net core 中使用 IMemoryCache

ASP.NET Core 外部依赖调用治理实战：HttpClientFactory、Polly 与幂等边界

1. 问题背景：服务没挂，为什么成功率先掉

2. 原理解析：连接、超时、重试和幂等为什么必须一起设计

2.1 连接管理决定了你能扛多久

2.2 超时预算必须先于重试策略

2.3 遵循行业共识，重试只能处理瞬时故障，不能处理业务冲突

2.4 写操作重试前必须定义幂等边界

ASP.NET Core 认证与授权实战：JWT、Policy 与权限边界落地

问题背景

原理解析

认证解决身份确认

授权解决操作范围

角色不等于权限模型

资源级授权才是真正的边界

示例代码

C# 异步编程实战：Task、ValueTask、线程池饥饿与背压设计

1. 问题背景：为什么会出现线程池饥饿

2. 原理解析

2.1 Task 与调度

2.2 ValueTask 的边界

2.3 线程池饥饿

2.4 背压

3. 示例代码：有边界的后台处理模型

EF Core 事务实战：SaveChanges、ExecutionStrategy、Outbox 与一致性边界

问题背景：为什么“写成功了”不等于业务真的成功

原理解析：EF Core 里的事务到底管到哪一步

SaveChanges 默认就带事务，但范围很有限

显式事务解决的是“多步数据库写入”

EF Core 写入链路实战：从 ChangeTracker 到 SQL Batch 的性能诊断与优化

问题背景

原理解析

ChangeTracker 负责记录变更

SaveChanges 并不是“一条语句”

SQL Batch 决定数据库往返次数

EF Core 原生 SQL 实战：FromSql、SqlQuery 与对象映射边界

1. 问题背景：为什么原生 SQL 常常能跑但难以长期维护

2. 原理解析：先分清 FromSql 和 SqlQuery 的职责

2.1 FromSql：面向 DbSet 的查询入口

EF Core 并发冲突处理实战：乐观锁、RowVersion 与 DbUpdateConcurrencyException

问题背景

原理解析

EF Core 的并发控制模型

两种并发令牌配置方式

EF Core 慢查询排查实战：TagWith、OpenTelemetry 与执行计划

问题背景：为什么本地快、线上慢

原理解析：慢查询定位为什么总是卡在一半

EF Core 拦截器实战：SaveChangesInterceptor、CommandInterceptor 与审计落地

1. 问题背景：为什么审计必须在系统设计期落地

2. 原理解析：先拆职责，再落地拦截器

2.1 第一步：用 SaveChangesInterceptor 统一实体变更审计

2.2 第二步：用 CommandInterceptor 统一 SQL 观测入口

EF Core 查询性能实战：Include、投影与跟踪策略边界

1. 问题背景：列表页为什么越改越慢

2. 原理解析：EF Core 查询成本主要花在哪里

2.1 翻译成本

`Span<T>` 与 `ArrayPool<T>`

2.1 `Task` 与调度

2.2 `ValueTask` 的边界

`SaveChanges` 默认就带事务，但范围很有限

`ChangeTracker` 负责记录变更

`SaveChanges` 并不是“一条语句”