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

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

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 密钥，避免泄露。我这里把密钥放在了环境变量中，代码中通过读取环境变量来获取密钥。

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 后端时，它又能以字段化数据的形式被检索和聚合。

Dotnet 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>

示例代码

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

引言

环境准备

开发实战

一、配置 Kimi API 的访问参数

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

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

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

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

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

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

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

3.1 安装依赖

3.2 第一步：配置 Serilog 与 OpenTelemetry

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

问题背景

原理解析

什么是结构化日志

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