一个函数是否应该设计成在协程中运行的判断标准是什么？

函数执行期间，CPU 是否在做有用的工作？

  是 → 不需要协程（CPU 密集型，用线程并行）
  否 → CPU 在空转等待外部响应 → 这就是协程的适用场合

这个函数要做什么？
│
├── 纯计算（排序、加密、图像处理、物理模拟）
│       └── ❌ 不要 async
│           原因：协程不能让 CPU 跑得更快，
│                 async 开销反而是净损耗
│           如果耗时 > 几十毫秒：
│               └── 用线程池执行，然后 await 那个线程
│
├── I/O 操作（网络、磁盘、数据库）
│       └── ✅ 必须 async
│           原因：等待期间线程什么都不做，
│                 释放线程让别人用是纯收益
│
├── 等待时间/信号（sleep、timer、条件变量）
│       └── ✅ 必须 async
│           原因：同上，等待期间 CPU 完全空闲
│
├── 调用了其他 async 函数
│       └── ✅ 必须 async（传染性决定的）
│           唯一例外：用 .GetAwaiter().GetResult() 同步等待，
│                     但这会阻塞线程，几乎总是错的
│
└── 纯内存操作（读写缓存、数据转换、状态查询）
        └── ❌ 不要 async
            原因：纳秒级操作，async 状态机开销比操作本身还大

进程内部（内存速度）：
  读写变量、操作集合、调用本地函数
  → 不需要 async，几纳秒到几微秒，协程开销不值得

跨进程边界（I/O 速度）：
  数据库查询、HTTP 请求、读文件、消息队列
  → 必须 async，毫秒级等待，线程释放价值极高

// 错误用法：CPU 密集型任务包上 async 没有意义
async Task<int> WrongAsync(int[] data) {
    // 这里根本没有 await，async 是假的
    // 编译器会警告，而且完全没有性能收益
    return data.Sum();
}

// CPU 密集型的正确做法：扔到线程池，然后 await
async Task<int> CpuBoundCorrect(int[] data) {
    return await Task.Run(() => HeavyComputation(data));
    // 这里 await 等的是"线程池里的一个线程完成计算"
    // 当前线程在这期间可以做别的事
}

// I/O 的正确做法：直接 async
async Task<string> IoCorrect(string url) {
    return await httpClient.GetStringAsync(url);
    // 等待期间不占用任何线程
}

函数实际执行时间    async 是否值得？
< 1 μs            ❌ 绝对不要，开销比工作本身大
1 μs ~ 1 ms       ⚠️  取决于并发量，通常不值得
> 1 ms（含 I/O）  ✅ 必须，线程释放价值远超开销

// Redis 本机查询耗时约 0.1ms，要 async 吗？
async Task<string> GetFromLocalRedis(string key) {
    return await redis.GetAsync(key);
}

// 先查内存缓存（纳秒），没有再查数据库（毫秒）
async Task<User> GetUser(int id) {
    if (cache.TryGet(id, out var user))
        return user;  // 同步路径，async 开销白付了

    return await db.QueryAsync<User>(id);  // 异步路径
}

ValueTask<User> GetUser(int id) {
    if (cache.TryGet(id, out var user))
        return new ValueTask<User>(user);  // 零分配
    
    return new ValueTask<User>(db.QueryAsync<User>(id));
}

// 处理一个 10GB 的文件，纯 CPU 解析，耗时 30 秒
// 直接 async 没意义，但也不能阻塞调用者 30 秒

Task<Result> ProcessHugeFile(string path) {
    return Task.Run(() => {
        // 在线程池线程上做 CPU 密集型工作
        return SynchronousHeavyParsing(path);
    });
}

// 调用者：
var result = await ProcessHugeFile(path);  // 不阻塞 UI/请求线程

用户主要是 UI 应用（WPF、MAUI）：
  → 必须提供 async，同步版本会冻结 UI

用户主要是命令行工具或脚本：
  → async 收益有限，同步版本更简单

用户是高并发服务器：
  → 必须 async，这是生死线

用户不确定：
  → 提供 async 版本，同步版本通过封装提供
    （但不要 sync-over-async，会死锁）

┌─────────────────────────────────────────────────────┐
│              这个函数要不要 async？                   │
├─────────────────────────────────────────────────────┤
│                                                     │
│  会等待进程外部（网络/磁盘/DB/Timer）？               │
│  → 是  → ✅ async                                   │
│                                                     │
│  只做内存计算，耗时 < 1ms？                          │
│  → 是  → ❌ 不要 async                              │
│                                                     │
│  CPU 密集，耗时 > 几十 ms？                          │
│  → 是  → Task.Run() 包裹，返回 Task（可被 await）    │
│                                                     │
│  调用了 async 函数？                                 │
│  → 是  → ✅ 必须 async（传染性）                     │
│                                                     │
│  同一个操作有时快（命中缓存）有时慢（穿透 I/O）？      │
│  → 是  → ValueTask / 条件性 async                   │
│                                                     │
└─────────────────────────────────────────────────────┘