Aspnet-Core 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 的路由。

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)
        };
    });

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

从 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

这意味着:

开发实战：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 直接写一个内联中间件：