// ? 標準命名：方法名 + Async 后綴
public Task<int> ReadAsync(byte[] buffer, int offset, int count);
// ? 已有同名 EAP 方法時，用 TaskAsync 后綴
public Task<string> GetTaskAsync(string url);
// ? 返回 void 的同步對應版本 → 返回 Task
public Task SaveAsync(string path);
// ? 返回 T 的同步對應版本 → 返回 Task<T>
public Task<UserDto> GetUserAsync(int userId);
// ? 避免：out/ref 參數(shù)在 TAP 中禁止使用
// 應將多返回值包裝為 tuple 或自定義類型
public Task<(bool Success, string Error)> TryParseAsync(string input);

// ? 推薦：參數(shù)驗證在外層同步完成
public Task<int> ProcessAsync(string input)
{
    if (input == null)
        throw new ArgumentNullException(nameof(input)); // 同步拋出
    return ProcessCoreAsync(input); // 委托給真正的 async 方法
}
private async Task<int> ProcessCoreAsync(string input)
{
    // 真正的異步工作
    var result = await DoWorkAsync(input);
    return result;
}

// 定義時接受 IProgress<T> 參數(shù)
public async Task<string[]> FindFilesAsync(
    string pattern,
    CancellationToken ct = default,
    IProgress<int> progress = null) // 允許為 null
{
    var results = new List<string>();
    int count = 0;
    await foreach (var file in EnumerateFilesAsync(pattern, ct))
    {
        results.Add(file);
        progress?.Report(++count); // null 安全調(diào)用
    }
    return results.ToArray();
}
// 調(diào)用端：Progress<T> 捕獲 UI 線程的同步上下文
var reporter = new Progress<int>(count =>
    progressBar.Value = count); // 這里可以安全更新 UI
await FindFilesAsync("*.cs", ct, reporter);

// ? 默認行為：第三方 Widget 內(nèi)部創(chuàng)建的子任務會延遲父任務完成
Task<Task> runWidget = Task.Factory.StartNew(
    () => thirdPartyWidget.Run());  // 子任務 sleep 5s，父任務也等 5s
// ? 正確做法：DenyChildAttach 隔離第三方任務
Task<Task> runWidget = Task.Factory.StartNew(
    () => thirdPartyWidget.Run(),
    TaskCreationOptions.DenyChildAttach);  // 父任務立即完成

// WhenAll：等待所有任務完成（并行 I/O 的核心武器）
var tasks = urls.Select(url => httpClient.GetStringAsync(url));
string[] results = await Task.WhenAll(tasks);
// WhenAny：哪個先完成用哪個（超時控制的經(jīng)典寫法）
var dataTask = FetchDataAsync();
var timeout = Task.Delay(TimeSpan.FromSeconds(5));
var winner = await Task.WhenAny(dataTask, timeout);
if (winner == timeout)
    throw new TimeoutException("請求超時");
return await dataTask; // 再次 await 以解包異常

private static readonly ConcurrentDictionary<string, string>
    _cache = new();
public static Task<string> DownloadStringAsync(string url)
{
    // 緩存命中：返回已完成的 Task，無線程切換開銷
    if (_cache.TryGetValue(url, out string? cached))
        return Task.FromResult(cached);
    // 緩存未命中：真正的異步下載
    return Task.Run(async () =>
    {
        var content = await _httpClient.GetStringAsync(url);
        _cache.TryAdd(url, content);
        return content;
    });
}

// ?? 注意：valueFactory 可能被多個線程調(diào)用
// 但只有一個線程的結果會被保留
var value = dict.GetOrAdd(key, k =>
{
    // 這里的代碼可能被并發(fā)執(zhí)行多次！
    // 如果 factory 有副作用（如 DB 寫入），需要額外處理
    return new ExpensiveObject(k);
});
// ? 如果 factory 有副作用，使用 Lazy<T> 確保只執(zhí)行一次
var lazy = dict.GetOrAdd(key, k =>
    new Lazy<ExpensiveObject>(() => new ExpensiveObject(k)));
var obj = lazy.Value; // 真正的構造只發(fā)生一次

var queue = new BlockingCollection<WorkItem>(boundedCapacity: 100);
// 生產(chǎn)者
Task producer = Task.Run(() =>
{
    foreach (var item in GetWorkItems())
        queue.Add(item);
    queue.CompleteAdding(); // ?? 必須調(diào)用！否則消費者永遠阻塞
});
// 消費者：GetConsumingEnumerable 會在 CompleteAdding 后自動退出
Task consumer = Task.Run(() =>
{
    foreach (var item in queue.GetConsumingEnumerable())
        ProcessItem(item);
});
await Task.WhenAll(producer, consumer);

using System.Runtime.InteropServices;
public static class NativeMethods
{
    // DllImport 聲明：映射到 kernel32.dll 中的函數(shù)
    [DllImport("kernel32.dll", SetLastError = true, CharSet = CharSet.Unicode)]
    public static extern bool CreateDirectory( 
        string lpPathName,
        IntPtr lpSecurityAttributes);
    // 現(xiàn)代寫法（.NET 7+）：LibraryImport + Source Generator（更快，AOT 友好）
    [LibraryImport("kernel32.dll", SetLastError = true,
        StringMarshalling = StringMarshalling.Utf16)]
    [return: MarshalAs(UnmanagedType.Bool)]
    public static partial bool CreateDirectoryModern( 
        string lpPathName,
        IntPtr lpSecurityAttributes);
}

// ? 危險：委托可能在 Native 調(diào)用期間被回收
NativeMethods.RegisterCallback(
    Marshal.GetFunctionPointerForDelegate(
        new MyCallback(OnEvent))); // 匿名委托，無引用！
// ? 正確：持有委托的引用直到 Native 不再使用
private readonly MyCallback _callback = OnEvent; // 類級別字段
void Init()
{
    var fnPtr = Marshal.GetFunctionPointerForDelegate(_callback);
    NativeMethods.RegisterCallback(fnPtr);
    GC.KeepAlive(_callback); // 明確告知 GC 此對象不可回收
}

public class ResourceHolder : IDisposable
{
    private IntPtr _nativeHandle;     // 非托管資源
    private Stream _managedStream;    // 托管的 IDisposable
    private bool _disposed = false;
    // 公共方法：供調(diào)用方手動釋放
    public void Dispose()
    {
        Dispose(disposing: true);
        GC.SuppressFinalize(this); // 告知 GC 不必再調(diào)用析構函數(shù)
    }
    // 核心釋放邏輯
    protected virtual void Dispose(bool disposing)
    {
        if (_disposed) return;
        if (disposing)
        {
            // 釋放托管資源（只在主動 Dispose 時）
            _managedStream?.Dispose();
        }
        // 釋放非托管資源（無論哪種路徑都要釋放）
        if (_nativeHandle != IntPtr.Zero)
        {
            NativeFree(_nativeHandle);
            _nativeHandle = IntPtr.Zero;
        }
        _disposed = true;
    }
    // 析構函數(shù)：GC 兜底（不能保證調(diào)用時機）
    ~ResourceHolder() => Dispose(disposing: false);
}

public class AsyncConnection : IAsyncDisposable
{
    private readonly NetworkStream _stream;
    public async ValueTask DisposeAsync()
    {
        await _stream.FlushAsync();  // 異步刷新緩沖區(qū)
        await _stream.DisposeAsync(); // 異步關閉連接
    }
}
// await using 確保無論是否異常都會調(diào)用 DisposeAsync
await using var conn = new AsyncConnection(endpoint);
await conn.SendAsync(data);