6.3 异步编程与API版本管理

6.3 异步编程与 API 版本管理

异步是接口的吞吐量生死线：同步阻塞的等待（数据库、外部调用）会占住线程池线程，请求一高峰线程池补线不及，整站排队雪崩；版本管理则是接口的时间线生死线——契约一旦有人依赖，变更必须以版本演进的方式落地。一个管空间（并发），一个管时间（演进）。

接口通道的最后两课放在一起讲，因为它们都属于"上线之后才见真章"的知识：开发机上一切正常的代码，压测与迭代时暴露本性。观察哨本节分别蹲在线程池与版本时间线上，各看一个真实案例。

异步到底省了什么：线程池记账

先纠正一个普遍误解：异步不是为了"更快"。单个请求的耗时基本不变，异步救的是并发容量。原理用记账方式讲：线程池是固定规模的柜员队伍；同步等待数据库时，柜员陪客户一起干等（线程阻塞）；异步等待时柜员去服务下一位，等数据库回话再回来（await 让出线程）。

// 同步版：柜员被数据库响应时间锁死
public List<ProductView> ListSync()
{
    return _db.Products.ToList();          // 阻塞：当前线程干等到 SQL 返回
}

// 异步版：柜员在等待期间去服务别人
public async Task<List<ProductView>> ListAsync()
{
    return await _db.Products.ToListAsync();   // await 处让出，SQL 完成后回来续跑
}
​

两个数字感受差别：线程池默认柜员数约等于 CPU 核数（比如 8 个），同步接口下每个在途请求占住一名柜员——数据库一抖，几十毫秒的查询变两秒，8 名柜员瞬间全在干等，后续请求排队等新柜员上线（线程池每秒只补一两名）；异步接口下等待期柜员全部在外勤服务，同样 8 名柜员能扛住成百上千在途请求。吞吐量的差距不在单次快慢，在柜员周转率。

案例：一次线程池饥饿事故复盘

背景：某订单接口上线三个月平稳，大促晚八点整站突然极慢：CPU 不满、数据库不忙，但所有接口排队数秒。扩容虚拟机也无缓解，现场如陷泥潭。

操作：观察哨三步定位。第一步看日志时间戳：每个请求的"进站"到"出站"间隔数秒，但动作本身只执行了几十毫秒——时间丢在排队。第二步拉线程池指标：线程数飙到几百还在涨、队列长度数千——典型的线程池饥饿特征。第三步扫代码找阻塞源，抓到两处：一个同步的第三方短信调用，一个被 .Result 触发的异步方法。

// 事故源一：接口里同步调外部服务，外部一抖全站陪等
var ok = _smsClient.SendSync(phone, text);      // 阻塞数百毫秒到数秒

// 事故源二：伪异步——异步方法被同步等待，比纯同步更糟
var data = FetchAsync().Result;                 // 占住线程还占住调度槽
​

结果：短信调用换异步版本（SendAsync 加 await），FetchAsync 调用链全链路改 async，发布后同样流量下线程数稳定在几十，排队消失。解读：饥饿的本质是"等待占用了柜员"。修复方向只有两条：等待变异步（柜员不陪等）、等待变短（加超时与缓存）。变式：无法改异步的老库，用独立线程池隔离（把阻塞调用圈进小池子，不污染主池）；外部调用必须配超时与降级——异步解决了占住柜员，没解决"等太久"本身。

一条配套纪律：异步链路要纯。方法链上出现一个 Result、Wait、GetAwaiter 就把整条链打回同步，而且这种"伪异步"在代码评审里最难发现——命名全带 Async，行为全阻塞。

版本管理：接口的时间线问题

接口一旦有外部消费者，就进入"契约不能随便改"的阶段：字段改名是删除加新增、枚举加值对旧客户端可能是崩溃、行为微调可能击穿对方的容错假设。版本策略先选再改——三策略对比：

路径版本的实现朴素而有效——控制器路由带版本段，新旧两版并存：

[ApiController]
[Route("api/v1/products")]
public class ProductsV1Controller : ControllerBase
{
    [HttpGet("{id:int}")]
    public IActionResult Get(int id) => Ok(new { id, name = "键盘", price = 199 });
    // v1 契约：price 是数字，单位元
}

[ApiController]
[Route("api/v2/products")]
public class ProductsV2Controller : ControllerBase
{
    [HttpGet("{id:int}")]
    public IActionResult Get(int id) => Ok(new { id, name = "键盘", priceFen = 19900 });
    // v2 变更：金额改用分存储，字段更名并换语义——破坏性变更必须换版本
}
// GET api/v1/products/1 → price:199
// GET api/v2/products/1 → priceFen:19900   两代契约并存，互不打扰
​

两套控制器难免重复，共用逻辑抽进服务层（第 5 章的仓储），控制器只留"契约翻译"职责——版本层本质上是给每代契约配一个翻译官。

演进纪律：变更分级与弃用流程

不是所有变更都要升版本。我的分级标准三级：兼容变更直接改——加可选字段、加新端点、放宽校验，旧客户端无感；灰色变更先观察——枚举加值、错误体加字段，对"穷举解析"的客户端可能不兼容，灰度期间盯着错误率；破坏性变更必须换版本——删字段、改语义、改类型、收紧校验。拿不准时按破坏性处理，多花一个版本的代价远小于击穿一批客户端。

弃用要走完时间线：宣布（响应头或文档标注弃用日期）→ 迁移窗口（保留双版本至少一个迭代周期，期间监控旧版调用量）→ 降级提醒（旧版响应加显著警告字段）→ 下线（旧版路由返回 410 Gone，附迁移说明）。观察哨见过跳过流程直接下线的团队——三个客户的系统集成当晚断掉，救火到凌晨。契约是信任，弃用流程就是履约。

问题：异步方法是不是越多越好？

不是。纯计算（内存里排序、序列化）不会释放等待，包一层异步只增加状态机开销。判定标准：有没有真正的等待点（网络、磁盘、数据库）——有就异步，没有就同步。CPU 密集工作反而该用独立任务队列，别占请求线程。

⚠️ 常见坑：异步链路里混进一个同步调用（.Result）而压测不暴露——低流量下它无害，线程饥饿只在高峰现身。代码评审用工具扫 Result 与 Wait 的出现点，比人眼可靠。

💡 关键直觉：异步管的是"柜员周转率"，版本管的是"契约信用期"。一个是空间上的并发容量，一个是时间上的变更秩序——接口要同时活在这两个维度里。

本节要点回顾

• 异步救并发不救单次：await 让线程在等待期外勤，吞吐量来自柜员周转率；
• 饥饿特征：CPU 不满但排队暴涨、线程数持续攀升，阻塞源多在同步外部调用与伪异步；
• 修复两方向：等待异步化、等待变短（超时加降级），异步链路要纯；
• 版本三策略：路径版本质是双翻译官并存，逻辑下沉服务层；
• 变更分级：兼容直改、灰色观察、破坏必升版，弃用走完四步时间线。