Asyncio on Tarragon

案例：非同步 subprocess

Wed, 21 Jan 2026 00:00:00 +0000

本案例基於 .claude/lib/git_utils.py 的實際程式碼，展示如何用 asyncio 實現非同步的外部命令執行。

先備知識

問題背景

現有設計

git_utils.py 使用同步的 subprocess.run：

 1import subprocess
 2from typing import Optional
 3
 4def run_git_command(
 5 args: list[str],
 6 cwd: Optional[str] = None,
 7 timeout: int = 10
 8) -> tuple[bool, str]:
 9 """
10 執行 git 命令並返回結果
11
12 Args:
13 args: git 命令參數列表（不含 'git'）
14 cwd: 執行目錄
15 timeout: 命令超時時間（秒）
16
17 Returns:
18 tuple[bool, str]: (是否成功, 輸出內容或錯誤訊息)
19 """
20 try:
21 result = subprocess.run(
22 ["git"] + args,
23 cwd=cwd,
24 capture_output=True,
25 text=True,
26 timeout=timeout
27 )
28 if result.returncode == 0:
29 return True, result.stdout.strip()
30 else:
31 return False, result.stderr.strip()
32 except subprocess.TimeoutExpired:
33 return False, f"Command timed out after {timeout}s"
34 except FileNotFoundError:
35 return False, "git command not found"
36 except Exception as e:
37 return False, str(e)
38
39def get_current_branch() -> Optional[str]:
40 """獲取當前分支名稱"""
41 success, output = run_git_command(["branch", "--show-current"])
42 return output if success and output else None
43
44def get_worktree_list() -> list[dict]:
45 """獲取所有 worktree 列表"""
46 success, output = run_git_command(["worktree", "list", "--porcelain"])
47 if not success:
48 return []
49 # ... 解析邏輯

這個設計的優點

簡單直覺：同步呼叫，容易理解
錯誤處理完善：處理超時、檔案不存在等情況
API 清晰：返回 (bool, str) 元組

這個設計的限制

問題：無法並行執行多個 Git 命令

 1def check_all_worktrees(worktrees: list[str]) -> dict[str, str]:
 2 """檢查所有 worktree 的狀態"""
 3 results = {}
 4 for worktree in worktrees:
 5 # 每次呼叫都會阻塞等待
 6 success, status = run_git_command(["status", "-s"], cwd=worktree)
 7 results[worktree] = status if success else "error"
 8 return results
 9
10# 如果有 10 個 worktree，每個花 0.5 秒
11# 總共需要 5 秒！

問題：阻塞事件迴圈

1async def handle_request():
2 # 這會阻塞事件迴圈！
3 branch = get_current_branch()
4 # 其他協程無法執行
5 return {"branch": branch}

進階解決方案：非同步 subprocess

設計目標

非阻塞執行：不阻塞事件迴圈
並行能力：可以同時執行多個命令
相容性：保持與同步版本相似的 API

實作步驟

步驟 1：建立非同步命令執行器

 1import asyncio
 2from typing import Optional
 3
 4async def async_run_git_command(
 5 args: list[str],
 6 cwd: Optional[str] = None,
 7 timeout: float = 10.0
 8) -> tuple[bool, str]:
 9 """
10 非同步執行 git 命令
11
12 Args:
13 args: git 命令參數列表（不含 'git'）
14 cwd: 執行目錄
15 timeout: 命令超時時間（秒）
16
17 Returns:
18 tuple[bool, str]: (是否成功, 輸出內容或錯誤訊息)
19
20 Example:
21 success, output = await async_run_git_command(["status"])
22 """
23 try:
24 # 建立非同步子進程
25 process = await asyncio.create_subprocess_exec(
26 "git", *args,
27 cwd=cwd,
28 stdout=asyncio.subprocess.PIPE,
29 stderr=asyncio.subprocess.PIPE
30 )
31
32 # 等待完成（帶超時）
33 try:
34 stdout, stderr = await asyncio.wait_for(
35 process.communicate(),
36 timeout=timeout
37 )
38 except asyncio.TimeoutError:
39 process.kill()
40 await process.wait()
41 return False, f"Command timed out after {timeout}s"
42
43 # 處理結果
44 if process.returncode == 0:
45 return True, stdout.decode().strip()
46 else:
47 return False, stderr.decode().strip()
48
49 except FileNotFoundError:
50 return False, "git command not found"
51 except Exception as e:
52 return False, str(e)

步驟 2：建立便利函式

 1async def async_get_current_branch() -> Optional[str]:
 2 """非同步獲取當前分支名稱"""
 3 success, output = await async_run_git_command(["branch", "--show-current"])
 4 return output if success and output else None
 5
 6async def async_get_project_root() -> str:
 7 """非同步獲取專案根目錄"""
 8 import os
 9 success, output = await async_run_git_command(["rev-parse", "--show-toplevel"])
10 return output if success else os.getcwd()
11
12async def async_get_worktree_list() -> list[dict]:
13 """非同步獲取 worktree 列表"""
14 success, output = await async_run_git_command(
15 ["worktree", "list", "--porcelain"]
16 )
17 if not success:
18 return []
19
20 worktrees = []
21 current_worktree: dict = {}
22
23 for line in output.split("\n"):
24 if line.startswith("worktree "):
25 if current_worktree:
26 worktrees.append(current_worktree)
27 current_worktree = {"path": line[9:]} # len("worktree ") = 9
28 elif line.startswith("branch "):
29 branch_ref = line[7:] # len("branch ") = 7
30 if branch_ref.startswith("refs/heads/"):
31 branch_ref = branch_ref[11:] # len("refs/heads/") = 11
32 current_worktree["branch"] = branch_ref
33 elif line == "detached":
34 current_worktree["detached"] = True
35
36 if current_worktree:
37 worktrees.append(current_worktree)
38
39 return worktrees

步驟 3：實現並行執行

 1async def check_all_worktrees(worktrees: list[str]) -> dict[str, str]:
 2 """
 3 並行檢查所有 worktree 的狀態
 4
 5 Args:
 6 worktrees: worktree 路徑列表
 7
 8 Returns:
 9 dict[str, str]: {路徑: 狀態} 映射
10 """
11 async def check_one(worktree: str) -> tuple[str, str]:
12 """檢查單個 worktree"""
13 success, status = await async_run_git_command(
14 ["status", "-s"],
15 cwd=worktree
16 )
17 return worktree, status if success else "error"
18
19 # 並行執行所有檢查
20 tasks = [check_one(wt) for wt in worktrees]
21 results = await asyncio.gather(*tasks)
22
23 return dict(results)
24
25async def get_all_branches(worktrees: list[str]) -> dict[str, str]:
26 """
27 並行獲取所有 worktree 的當前分支
28
29 Args:
30 worktrees: worktree 路徑列表
31
32 Returns:
33 dict[str, str]: {路徑: 分支名} 映射
34 """
35 async def get_branch(worktree: str) -> tuple[str, str]:
36 success, branch = await async_run_git_command(
37 ["branch", "--show-current"],
38 cwd=worktree
39 )
40 return worktree, branch if success else "unknown"
41
42 tasks = [get_branch(wt) for wt in worktrees]
43 results = await asyncio.gather(*tasks)
44
45 return dict(results)

完整程式碼

 1#!/usr/bin/env python3
 2"""
 3非同步 Git 操作工具 - 完整範例
 4
 5展示如何用 asyncio 實現非阻塞的 Git 命令執行。
 6"""
 7
 8import asyncio
 9import os
 10from typing import Optional
 11
 12# ===== 核心功能 =====
 13
 14async def async_run_git_command(
 15 args: list[str],
 16 cwd: Optional[str] = None,
 17 timeout: float = 10.0
 18) -> tuple[bool, str]:
 19 """
 20 非同步執行 git 命令
 21
 22 Args:
 23 args: git 命令參數列表
 24 cwd: 執行目錄
 25 timeout: 超時時間（秒）
 26
 27 Returns:
 28 (是否成功, 輸出或錯誤訊息)
 29 """
 30 try:
 31 process = await asyncio.create_subprocess_exec(
 32 "git", *args,
 33 cwd=cwd,
 34 stdout=asyncio.subprocess.PIPE,
 35 stderr=asyncio.subprocess.PIPE
 36 )
 37
 38 try:
 39 stdout, stderr = await asyncio.wait_for(
 40 process.communicate(),
 41 timeout=timeout
 42 )
 43 except asyncio.TimeoutError:
 44 process.kill()
 45 await process.wait()
 46 return False, f"Command timed out after {timeout}s"
 47
 48 if process.returncode == 0:
 49 return True, stdout.decode().strip()
 50 else:
 51 return False, stderr.decode().strip()
 52
 53 except FileNotFoundError:
 54 return False, "git command not found"
 55 except Exception as e:
 56 return False, str(e)
 57
 58# ===== 便利函式 =====
 59
 60async def async_get_current_branch() -> Optional[str]:
 61 """獲取當前分支"""
 62 success, output = await async_run_git_command(["branch", "--show-current"])
 63 return output if success and output else None
 64
 65async def async_get_project_root() -> str:
 66 """獲取專案根目錄"""
 67 success, output = await async_run_git_command(["rev-parse", "--show-toplevel"])
 68 return output if success else os.getcwd()
 69
 70async def async_get_worktree_list() -> list[dict]:
 71 """獲取 worktree 列表"""
 72 success, output = await async_run_git_command(
 73 ["worktree", "list", "--porcelain"]
 74 )
 75 if not success:
 76 return []
 77
 78 worktrees = []
 79 current_worktree: dict = {}
 80
 81 for line in output.split("\n"):
 82 if line.startswith("worktree "):
 83 if current_worktree:
 84 worktrees.append(current_worktree)
 85 current_worktree = {"path": line[9:]}
 86 elif line.startswith("branch "):
 87 branch_ref = line[7:]
 88 if branch_ref.startswith("refs/heads/"):
 89 branch_ref = branch_ref[11:]
 90 current_worktree["branch"] = branch_ref
 91 elif line == "detached":
 92 current_worktree["detached"] = True
 93
 94 if current_worktree:
 95 worktrees.append(current_worktree)
 96
 97 return worktrees
 98
 99# ===== 並行操作 =====
100
101async def check_all_worktrees(worktrees: list[str]) -> dict[str, str]:
102 """並行檢查所有 worktree 狀態"""
103 async def check_one(path: str) -> tuple[str, str]:
104 success, status = await async_run_git_command(["status", "-s"], cwd=path)
105 return path, status if success else "error"
106
107 tasks = [check_one(wt) for wt in worktrees]
108 results = await asyncio.gather(*tasks)
109 return dict(results)
110
111async def get_all_branches(worktrees: list[str]) -> dict[str, str]:
112 """並行獲取所有 worktree 的分支"""
113 async def get_branch(path: str) -> tuple[str, str]:
114 success, branch = await async_run_git_command(
115 ["branch", "--show-current"],
116 cwd=path
117 )
118 return path, branch if success else "unknown"
119
120 tasks = [get_branch(wt) for wt in worktrees]
121 results = await asyncio.gather(*tasks)
122 return dict(results)
123
124async def batch_git_commands(
125 commands: list[tuple[list[str], Optional[str]]]
126) -> list[tuple[bool, str]]:
127 """
128 批次執行多個 Git 命令
129
130 Args:
131 commands: [(args, cwd), ...] 命令列表
132
133 Returns:
134 [(success, output), ...] 結果列表
135 """
136 tasks = [
137 async_run_git_command(args, cwd=cwd)
138 for args, cwd in commands
139 ]
140 return await asyncio.gather(*tasks)
141
142# ===== 同步/非同步橋接 =====
143
144def run_git_command(
145 args: list[str],
146 cwd: Optional[str] = None,
147 timeout: float = 10.0
148) -> tuple[bool, str]:
149 """
150 同步版本（相容舊 API）
151
152 在已有事件迴圈的環境中，這會建立新的迴圈執行。
153 """
154 return asyncio.run(async_run_git_command(args, cwd, timeout))
155
156def get_current_branch() -> Optional[str]:
157 """同步版本：獲取當前分支"""
158 return asyncio.run(async_get_current_branch())
159
160# ===== 測試 =====
161
162async def demo():
163 """示範非同步 Git 操作"""
164 print("=== 非同步 Git 操作示範 ===\n")
165
166 # 單一命令
167 print("1. 獲取當前分支:")
168 branch = await async_get_current_branch()
169 print(f" 分支: {branch}\n")
170
171 # 獲取專案根目錄
172 print("2. 獲取專案根目錄:")
173 root = await async_get_project_root()
174 print(f" 根目錄: {root}\n")
175
176 # 獲取 worktree 列表
177 print("3. 獲取 worktree 列表:")
178 worktrees = await async_get_worktree_list()
179 for wt in worktrees:
180 branch = wt.get("branch", "detached")
181 print(f" - {branch}: {wt['path']}")
182 print()
183
184 # 如果有多個 worktree，示範並行操作
185 if len(worktrees) > 1:
186 print("4. 並行檢查所有 worktree 狀態:")
187 paths = [wt["path"] for wt in worktrees]
188 statuses = await check_all_worktrees(paths)
189 for path, status in statuses.items():
190 print(f" - {path}:")
191 if status:
192 for line in status.split("\n"):
193 print(f" {line}")
194 else:
195 print(" (clean)")
196 print()
197
198 # 批次命令示範
199 print("5. 批次執行多個命令:")
200 commands = [
201 (["config", "user.name"], None),
202 (["config", "user.email"], None),
203 (["rev-parse", "--short", "HEAD"], None),
204 ]
205 results = await batch_git_commands(commands)
206 labels = ["使用者名稱", "使用者信箱", "當前 commit"]
207 for label, (success, output) in zip(labels, results):
208 print(f" {label}: {output if success else '(未設定)'}")
209
210if __name__ == "__main__":
211 asyncio.run(demo())

使用範例

基本使用

 1import asyncio
 2
 3async def main():
 4 # 非同步獲取分支
 5 branch = await async_get_current_branch()
 6 print(f"當前分支: {branch}")
 7
 8 # 非同步獲取 worktree
 9 worktrees = await async_get_worktree_list()
10 print(f"Worktree 數量: {len(worktrees)}")
11
12asyncio.run(main())

並行操作

 1async def check_multiple_repos(repos: list[str]):
 2 """同時檢查多個 repo 的狀態"""
 3 tasks = [
 4 async_run_git_command(["status", "-s"], cwd=repo)
 5 for repo in repos
 6 ]
 7
 8 # 並行執行，等待全部完成
 9 results = await asyncio.gather(*tasks)
10
11 for repo, (success, output) in zip(repos, results):
12 status = "clean" if not output else "dirty"
13 print(f"{repo}: {status}")
14
15# 10 個 repo，如果每個花 0.5 秒
16# 並行執行只需要約 0.5 秒！

與 FastAPI 整合

 1from fastapi import FastAPI
 2
 3app = FastAPI()
 4
 5@app.get("/git/branch")
 6async def get_branch():
 7 """非同步端點：獲取當前分支"""
 8 branch = await async_get_current_branch()
 9 return {"branch": branch}
10
11@app.get("/git/worktrees")
12async def get_worktrees():
13 """非同步端點：獲取 worktree 列表"""
14 worktrees = await async_get_worktree_list()
15 return {"worktrees": worktrees}

效能比較

 1import time
 2import asyncio
 3
 4def sync_check_repos(repos: list[str]) -> float:
 5 """同步版本：依序檢查"""
 6 start = time.perf_counter()
 7 for repo in repos:
 8 run_git_command(["status", "-s"], cwd=repo)
 9 return time.perf_counter() - start
10
11async def async_check_repos(repos: list[str]) -> float:
12 """非同步版本：並行檢查"""
13 start = time.perf_counter()
14 tasks = [
15 async_run_git_command(["status", "-s"], cwd=repo)
16 for repo in repos
17 ]
18 await asyncio.gather(*tasks)
19 return time.perf_counter() - start
20
21# 假設每個 git status 花 0.2 秒
22repos = [f"/path/to/repo{i}" for i in range(10)]
23
24sync_time = sync_check_repos(repos) # ~2.0 秒
25async_time = asyncio.run(async_check_repos(repos)) # ~0.2 秒
26
27print(f"同步: {sync_time:.2f}s")
28print(f"非同步: {async_time:.2f}s")
29print(f"加速: {sync_time / async_time:.1f}x")

設計權衡

面向	同步 subprocess	非同步 subprocess
簡單性	簡單直覺	需要理解 async/await
效能	依序執行	可並行執行
相容性	到處可用	需要事件迴圈
錯誤處理	直覺	需要處理非同步異常
測試	簡單	需要 pytest-asyncio
記憶體	低	略高（維護多個進程）

什麼時候該用非同步 subprocess？

適合使用：

1.1 基礎概念與事件迴圈

Tue, 20 Jan 2026 00:00:00 +0000

本章介紹 asyncio 的核心概念。理解這些概念是掌握異步程式設計的基礎。

先備知識

入門系列 3.7 並行處理
了解 I/O 密集任務的特性

本章目標

學完本章後，你將能夠：

理解並發、並行、異步的區別
解釋事件迴圈的工作原理
寫出第一個異步程式
判斷何時使用 asyncio

【原理層】並發、並行與異步

三個容易混淆的概念

在開始之前，我們需要釐清三個經常被混用的概念：

 1並發（Concurrency）：
 2  同時「處理」多件事情（不一定同時執行）
 3  重點是結構和設計
 4
 5並行（Parallelism）：
 6  同時「執行」多件事情
 7  需要多核 CPU 或多台機器
 8
 9異步（Asynchronous）：
10  不等待結果就繼續執行
11  一種實現並發的方式

用一個生活化的例子：

 1同步做早餐：
 2  1. 煮咖啡（等 5 分鐘）
 3  2. 烤土司（等 3 分鐘）
 4  3. 煎蛋（等 4 分鐘）
 5  總共：12 分鐘
 6
 7異步做早餐（一個人）：
 8  1. 啟動咖啡機
 9  2. 放土司進烤箱
10  3. 開始煎蛋
11  4. 等待全部完成
12  總共：約 5 分鐘（最長任務的時間）
13
14並行做早餐（三個人）：
15  三人同時分別處理
16  總共：約 5 分鐘

asyncio 是並發，不是並行

這是最重要的概念：asyncio 在單執行緒中實現並發。

 1import asyncio
 2import time
 3
 4async def task(name, delay):
 5    print(f"{name} 開始")
 6    await asyncio.sleep(delay)  # 非阻塞等待
 7    print(f"{name} 完成")
 8    return name
 9
10async def main():
11    start = time.perf_counter()
12
13    # 同時啟動三個任務
14    results = await asyncio.gather(
15        task("A", 2),
16        task("B", 1),
17        task("C", 1.5)
18    )
19
20    elapsed = time.perf_counter() - start
21    print(f"總耗時：{elapsed:.2f}s")  # 約 2 秒，不是 4.5 秒
22
23asyncio.run(main())

輸出：

1A 開始
2B 開始
3C 開始
4B 完成
5C 完成
6A 完成
7總耗時：2.00s

三個任務「並發」執行，但都在同一個執行緒中。

為什麼不用多執行緒？

你可能會問：用 threading 也能達到類似效果，為什麼要用 asyncio？

面向	threading	asyncio
記憶體開銷	每執行緒約 8MB stack	每協程約幾 KB
切換成本	OS 排程，較高	用戶空間切換，極低
並發數量	數百到數千	數萬到數十萬
執行緒安全	需要鎖保護	單執行緒，天生安全
除錯難度	競爭條件難以重現	確定性較高

當你需要處理大量 I/O 並發（如 Web 伺服器、爬蟲）時，asyncio 通常是更好的選擇。

【設計層】事件迴圈

什麼是事件迴圈？

事件迴圈（Event Loop）是 asyncio 的核心，它負責：

排程和執行協程
處理 I/O 事件
管理回呼函式

 1事件迴圈的運作：
 2
 3┌─────────────────────────────────────┐
 4│           事件迴圈                    │
 5│  ┌─────────────────────────────┐    │
 6│  │    就緒佇列（Ready Queue）    │    │
 7│  │  [協程A] [協程B] [協程C]      │    │
 8│  └─────────────────────────────┘    │
 9│              ↓                       │
10│         執行就緒任務                  │
11│              ↓                       │
12│         遇到 await                   │
13│              ↓                       │
14│  ┌─────────────────────────────┐    │
15│  │   等待佇列（Waiting Queue）   │    │
16│  │  [等待 I/O] [等待計時器]      │    │
17│  └─────────────────────────────┘    │
18│              ↓                       │
19│         I/O 完成                     │
20│              ↓                       │
21│         放回就緒佇列                  │
22└─────────────────────────────────────┘

協作式多任務

asyncio 使用「協作式多任務」（Cooperative Multitasking）：

任務主動讓出控制權（透過 await）
事件迴圈選擇下一個就緒任務執行
沒有強制搶佔

 1async def cooperative_task(name):
 2    for i in range(3):
 3        print(f"{name}: 步驟 {i}")
 4        await asyncio.sleep(0)  # 主動讓出控制權
 5    print(f"{name}: 完成")
 6
 7async def main():
 8    await asyncio.gather(
 9        cooperative_task("A"),
10        cooperative_task("B")
11    )
12
13asyncio.run(main())

輸出：

1A: 步驟 0
2B: 步驟 0
3A: 步驟 1
4B: 步驟 1
5A: 步驟 2
6B: 步驟 2
7A: 完成
8B: 完成

注意任務是交替執行的，每次 await 都是一個切換點。

asyncio.run() 的背後

asyncio.run() 是 Python 3.7+ 推薦的入口點：

1# 這是簡化的偽代碼
2def run(coro):
3    loop = asyncio.new_event_loop()
4    try:
5        asyncio.set_event_loop(loop)
6        return loop.run_until_complete(coro)
7    finally:
8        loop.close()

它做了三件事：

建立新的事件迴圈
執行協程直到完成
關閉事件迴圈

【實作層】第一個異步程式

async 和 await

 1import asyncio
 2
 3# async def 定義協程函式
 4async def greet(name, delay):
 5    print(f"開始問候 {name}")
 6    await asyncio.sleep(delay)  # await 等待可等待物件
 7    print(f"你好，{name}！")
 8    return f"問候 {name} 完成"
 9
10async def main():
11    # 方法 1：依序執行
12    result1 = await greet("Alice", 1)
13    result2 = await greet("Bob", 1)
14    # 總共約 2 秒
15
16    # 方法 2：並發執行
17    results = await asyncio.gather(
18        greet("Charlie", 1),
19        greet("David", 1)
20    )
21    # 總共約 1 秒
22
23asyncio.run(main())

協程 vs 協程函式

這是一個常見的混淆點：

 1async def my_coro():
 2    return 42
 3
 4# my_coro 是協程函式（coroutine function）
 5print(type(my_coro))  # 
 6
 7# my_coro() 是協程物件（coroutine object）
 8coro = my_coro()
 9print(type(coro))  # 
10
11# 協程物件需要被執行
12result = asyncio.run(coro)
13print(result)  # 42

常見錯誤：忘記 await

 1async def fetch_data():
 2    await asyncio.sleep(1)
 3    return {"data": "value"}
 4
 5async def main():
 6    # 錯誤：沒有 await
 7    result = fetch_data()  # 這只是建立協程物件，沒有執行
 8    print(result)  # 
 9
10    # 正確：使用 await
11    result = await fetch_data()
12    print(result)  # {'data': 'value'}
13
14asyncio.run(main())

Python 會發出警告：

1RuntimeWarning: coroutine 'fetch_data' was never awaited

偵錯技巧

 1import asyncio
 2
 3async def main():
 4    # 取得當前事件迴圈
 5    loop = asyncio.get_running_loop()
 6    print(f"事件迴圈：{loop}")
 7
 8    # 檢查是否在事件迴圈中
 9    print(f"正在執行：{loop.is_running()}")
10
11asyncio.run(main())

【選擇指南】何時使用 asyncio

適合 asyncio 的場景

Web 伺服器：處理大量並發請求
API 客戶端：批次呼叫多個 API
網路爬蟲：同時抓取多個網頁
即時應用：WebSocket、聊天室
資料庫操作：批次查詢

 1# 範例：並發下載多個網頁
 2import asyncio
 3import aiohttp
 4
 5async def fetch(session, url):
 6    async with session.get(url) as response:
 7        return await response.text()
 8
 9async def main():
10    urls = [
11        "https://python.org",
12        "https://docs.python.org",
13        "https://pypi.org"
14    ]
15
16    async with aiohttp.ClientSession() as session:
17        tasks = [fetch(session, url) for url in urls]
18        results = await asyncio.gather(*tasks)
19
20    for url, html in zip(urls, results):
21        print(f"{url}: {len(html)} bytes")
22
23asyncio.run(main())

不適合 asyncio 的場景

CPU 密集任務：asyncio 無法繞過 GIL
簡單腳本：增加複雜度沒有好處
依賴同步函式庫：需要額外處理

決策流程

 1任務類型？
 2    │
 3    ├─→ CPU 密集
 4    │       └─→ multiprocessing 或 Free-threading
 5    │
 6    └─→ I/O 密集
 7            │
 8            ├─→ 並發量 < 100
 9            │       └─→ threading 可能夠用
10            │
11            └─→ 並發量 > 100
12                    │
13                    ├─→ 需要共享複雜狀態
14                    │       └─→ threading + Lock
15                    │
16                    └─→ 任務相對獨立
17                            └─→ asyncio（推薦）

思考題

為什麼說 asyncio 是「協作式」而不是「搶佔式」？這對程式設計有什麼影響？
如果一個協程中有 CPU 密集的計算而沒有 await，會發生什麼事？
asyncio.sleep(0) 的作用是什麼？

實作練習

寫一個程式，同時「下載」5 個檔案（用 asyncio.sleep() 模擬下載時間），並顯示總耗時
修改上面的程式，讓它顯示每個檔案完成的順序
實作一個簡單的計時器，每秒印出一次時間，持續 5 秒

延伸閱讀

下一章：協程與 Task 管理

模組一：非同步程式設計（asyncio）

Tue, 20 Jan 2026 00:00:00 +0000

Python 的 asyncio 模組提供了異步程式設計的基礎設施。本模組將帶你從基礎概念到實戰應用，全面掌握 Python 的異步程式設計。

為什麼學習 asyncio？

在現代 Python 開發中，asyncio 已經成為處理 I/O 密集任務的標準方案：

Web 框架：FastAPI、Starlette 都以 asyncio 為基礎
網路客戶端：aiohttp、httpx 的異步 API
資料庫：SQLAlchemy 2.0、asyncpg 的異步支援
效能：單執行緒處理數千個並發連線

與入門系列的關係

入門系列介紹了 threading 和 multiprocessing，它們解決的是不同問題：

方案	適用場景	並發模型
threading	I/O 密集，需要共享記憶體	多執行緒並行
multiprocessing	CPU 密集	多進程並行
asyncio	I/O 密集，大量並發	單執行緒協作式並發

asyncio 提供在單執行緒中高效處理大量 I/O 並發任務的模型，跟 threading 是互補而非替代關係。

章節列表

章節	主題	關鍵收穫
1.0	從 threading 到 asyncio	理解為什麼需要 asyncio
1.1	基礎概念與事件迴圈	理解 asyncio 的核心概念
1.2	協程與 Task 管理	掌握 async/await 語法
1.3	設計模式與最佳實踐	學會常見的異步模式
1.4	實戰：與同步程式碼整合	在現有專案中應用 asyncio

案例研究

基於 .claude/lib 實際程式碼的進階案例：

案例	素材	學習重點
非同步 Subprocess	git_utils.py	asyncio.create_subprocess_exec
並行 I/O 操作	git_utils.py	asyncio.gather、TaskGroup
同步/非同步橋接	整個 lib	run_in_executor

先備知識

入門系列 3.7 並行處理
了解 I/O 密集 vs CPU 密集的區別
基本的 Python 函式與類別

學習建議

循序漸進：按章節順序學習，每章都建立在前一章的基礎上
動手實作：每章都有實作練習，請實際執行程式碼
對比思考：與 threading 做對比，理解各自的優缺點

常見誤解

在開始之前，先澄清一些常見誤解：

誤解：asyncio 可以讓程式碼變快

事實：asyncio 不會讓單一任務變快，它讓你能在等待 I/O 時做其他事情。

誤解：asyncio 是多執行緒

事實：asyncio 是單執行緒的協作式多任務，不會繞過 GIL。

誤解：async/await 只是語法糖

事實：async/await 定義了一種全新的程式設計模型，需要理解其背後的概念。

學習時間

每章節約 30-45 分鐘，全模組約 2-3 小時

上一模組：入門系列 下一模組：模組二：元編程

案例：並行 I/O 操作

Wed, 21 Jan 2026 00:00:00 +0000

本案例基於 .claude/lib/git_utils.py 的實際程式碼，展示如何用 asyncio.gather 和 TaskGroup 實現高效的並行 I/O 操作。

先備知識

問題背景

現有設計

git_utils.py 的 get_worktree_list() 取得 worktree 列表後，如果要檢查每個 worktree 的狀態，需要逐一呼叫：

 1from git_utils import run_git_command, get_worktree_list
 2
 3def check_all_worktrees_sync() -> dict[str, str]:
 4    """
 5    同步版本：依序檢查每個 worktree 的狀態
 6
 7    Returns:
 8        dict[str, str]: {路徑: 狀態} 映射
 9    """
10    worktrees = get_worktree_list()
11    results = {}
12
13    for wt in worktrees:
14        path = wt["path"]
15        # Every call blocks until completion
16        success, output = run_git_command(["status", "-s"], cwd=path)
17        results[path] = output if success else "error"
18
19    return results
20
21def get_all_branches_sync() -> dict[str, str]:
22    """
23    同步版本：依序取得每個 worktree 的分支名稱
24
25    Returns:
26        dict[str, str]: {路徑: 分支名} 映射
27    """
28    worktrees = get_worktree_list()
29    results = {}
30
31    for wt in worktrees:
32        path = wt["path"]
33        # Each command waits for the previous one
34        success, output = run_git_command(["branch", "--show-current"], cwd=path)
35        results[path] = output if success else "unknown"
36
37    return results

這個設計的優點

簡單直覺：循序執行，容易理解和除錯
錯誤處理明確：每個操作的結果立即可用
資源友善：一次只執行一個進程

這個設計的限制

當 worktree 數量增加時：

執行時間線性增長：10 個 worktree，每個 0.2 秒 = 2 秒
無法利用 I/O 等待時間：等待一個命令完成時，CPU 閒置
使用者體驗差：大量 worktree 時響應緩慢

 1import time
 2
 3def benchmark_sync(worktrees: list[str]) -> float:
 4    """測量同步版本的執行時間"""
 5    start = time.perf_counter()
 6
 7    for path in worktrees:
 8        # Simulate I/O wait (actual git command)
 9        run_git_command(["status", "-s"], cwd=path)
10
11    return time.perf_counter() - start
12
13# 10 worktrees, each taking 0.2s
14# Total: 10 * 0.2 = 2.0 seconds

進階解決方案

設計目標

並行執行多個獨立的 I/O 操作
正確處理部分失敗的情況
支援取消和超時機制

實作步驟

步驟 1：使用 asyncio.gather

asyncio.gather 是並行執行多個協程最直接的方式：

 1import asyncio
 2from typing import Optional
 3
 4async def async_run_git_command(
 5    args: list[str],
 6    cwd: Optional[str] = None,
 7    timeout: float = 10.0
 8) -> tuple[bool, str]:
 9    """
10    非同步執行 git 命令（詳見上一章）
11    """
12    try:
13        process = await asyncio.create_subprocess_exec(
14            "git", *args,
15            cwd=cwd,
16            stdout=asyncio.subprocess.PIPE,
17            stderr=asyncio.subprocess.PIPE
18        )
19
20        try:
21            stdout, stderr = await asyncio.wait_for(
22                process.communicate(),
23                timeout=timeout
24            )
25        except asyncio.TimeoutError:
26            process.kill()
27            await process.wait()
28            return False, f"Command timed out after {timeout}s"
29
30        if process.returncode == 0:
31            return True, stdout.decode().strip()
32        else:
33            return False, stderr.decode().strip()
34
35    except FileNotFoundError:
36        return False, "git command not found"
37    except Exception as e:
38        return False, str(e)
39
40async def check_all_worktrees_basic(worktrees: list[str]) -> dict[str, str]:
41    """
42    使用 asyncio.gather 並行檢查所有 worktree
43
44    Args:
45        worktrees: worktree 路徑列表
46
47    Returns:
48        dict[str, str]: {路徑: 狀態} 映射
49    """
50    async def check_one(path: str) -> tuple[str, str]:
51        """Check a single worktree and return (path, status)"""
52        success, output = await async_run_git_command(
53            ["status", "-s"],
54            cwd=path
55        )
56        return path, output if success else "error"
57
58    # Create tasks for all worktrees
59    tasks = [check_one(path) for path in worktrees]
60
61    # Execute all tasks in parallel
62    results = await asyncio.gather(*tasks)
63
64    # Convert list of tuples to dict
65    return dict(results)
66
67# Usage example
68async def demo_basic():
69    worktrees = ["/path/to/repo1", "/path/to/repo2", "/path/to/repo3"]
70
71    # All three checks run in parallel
72    # If each takes 0.2s, total time is ~0.2s, not 0.6s
73    statuses = await check_all_worktrees_basic(worktrees)
74
75    for path, status in statuses.items():
76        print(f"{path}: {'clean' if not status else status}")

重點說明：

asyncio.gather(*tasks) 同時啟動所有協程
等待所有協程完成後，返回結果列表
結果順序與輸入任務順序一致

步驟 2：處理錯誤（return_exceptions）

預設情況下，gather 在遇到第一個異常時會傳播該異常。使用 return_exceptions=True 可以收集所有結果，包括異常：

 1async def check_all_worktrees_safe(
 2    worktrees: list[str]
 3) -> dict[str, str | Exception]:
 4    """
 5    安全版本：使用 return_exceptions 處理部分失敗
 6
 7    即使某些 worktree 檢查失敗，仍然返回其他的結果。
 8
 9    Args:
10        worktrees: worktree 路徑列表
11
12    Returns:
13        dict: {路徑: 狀態或例外} 映射
14    """
15    async def check_one(path: str) -> tuple[str, str]:
16        """Check with potential exception"""
17        success, output = await async_run_git_command(
18            ["status", "-s"],
19            cwd=path,
20            timeout=5.0  # Shorter timeout
21        )
22
23        if not success:
24            # Raise exception for failed commands
25            raise RuntimeError(f"Git command failed: {output}")
26
27        return path, output
28
29    tasks = [check_one(path) for path in worktrees]
30
31    # return_exceptions=True: exceptions become results, not propagated
32    results = await asyncio.gather(*tasks, return_exceptions=True)
33
34    # Process results, handling both successes and exceptions
35    output = {}
36    for path, result in zip(worktrees, results):
37        if isinstance(result, Exception):
38            output[path] = f"error: {result}"
39        else:
40            # result is (path, status) tuple
41            _, status = result
42            output[path] = status if status else "clean"
43
44    return output
45
46async def demo_error_handling():
47    """示範錯誤處理"""
48    worktrees = [
49        "/valid/repo1",      # Works
50        "/invalid/path",     # Fails
51        "/valid/repo2",      # Works
52    ]
53
54    results = await check_all_worktrees_safe(worktrees)
55
56    for path, status in results.items():
57        if status.startswith("error:"):
58            print(f"[FAILED] {path}: {status}")
59        else:
60            print(f"[OK] {path}: {status}")
61
62# Output:
63# [OK] /valid/repo1: clean
64# [FAILED] /invalid/path: error: Git command failed: ...
65# [OK] /valid/repo2: M file.txt

return_exceptions 行為對比：

 1async def compare_exception_handling():
 2    async def might_fail(n: int) -> int:
 3        if n == 2:
 4            raise ValueError(f"Task {n} failed")
 5        return n * 10
 6
 7    tasks = [might_fail(i) for i in range(5)]
 8
 9    # Without return_exceptions (default)
10    try:
11        results = await asyncio.gather(*tasks)  # Raises ValueError
12    except ValueError as e:
13        print(f"Caught: {e}")  # Only see first error, others lost
14
15    # With return_exceptions=True
16    results = await asyncio.gather(*tasks, return_exceptions=True)
17    # results: [0, 10, ValueError('Task 2 failed'), 30, 40]
18
19    for i, result in enumerate(results):
20        if isinstance(result, Exception):
21            print(f"Task {i}: Failed - {result}")
22        else:
23            print(f"Task {i}: Success - {result}")

步驟 3：使用 TaskGroup（Python 3.11+）

Python 3.11 引入的 TaskGroup 提供更好的結構化並行控制：

 1import asyncio
 2from typing import Optional
 3
 4async def check_all_worktrees_taskgroup(
 5    worktrees: list[str]
 6) -> dict[str, str]:
 7    """
 8    使用 TaskGroup 並行檢查所有 worktree
 9
10    TaskGroup 特性：
11    - 任一任務失敗時，自動取消其他任務
12    - 明確的作用域（context manager）
13    - 異常聚合（ExceptionGroup）
14
15    Args:
16        worktrees: worktree 路徑列表
17
18    Returns:
19        dict[str, str]: {路徑: 狀態} 映射
20    """
21    results: dict[str, str] = {}
22
23    async def check_and_store(path: str) -> None:
24        """Check worktree and store result in shared dict"""
25        success, output = await async_run_git_command(
26            ["status", "-s"],
27            cwd=path
28        )
29        results[path] = output if success else "error"
30
31    async with asyncio.TaskGroup() as tg:
32        for path in worktrees:
33            tg.create_task(check_and_store(path))
34
35    # All tasks complete when exiting the context
36    return results
37
38async def demo_taskgroup():
39    """示範 TaskGroup 的基本用法"""
40    worktrees = ["/repo1", "/repo2", "/repo3"]
41
42    try:
43        results = await check_all_worktrees_taskgroup(worktrees)
44        for path, status in results.items():
45            print(f"{path}: {status}")
46    except* Exception as eg:
47        # Python 3.11+ except* syntax for ExceptionGroup
48        for exc in eg.exceptions:
49            print(f"Task failed: {exc}")

TaskGroup 的錯誤處理模式：

 1async def taskgroup_error_demo():
 2    """示範 TaskGroup 的異常處理"""
 3
 4    async def task_might_fail(name: str, should_fail: bool) -> str:
 5        await asyncio.sleep(0.1)
 6        if should_fail:
 7            raise ValueError(f"{name} failed!")
 8        return f"{name} succeeded"
 9
10    try:
11        async with asyncio.TaskGroup() as tg:
12            tg.create_task(task_might_fail("A", False))
13            tg.create_task(task_might_fail("B", True))   # Will fail
14            tg.create_task(task_might_fail("C", False))  # Gets cancelled
15    except* ValueError as eg:
16        print(f"Caught {len(eg.exceptions)} errors:")
17        for exc in eg.exceptions:
18            print(f"  - {exc}")
19
20# When B fails:
21# 1. TaskGroup cancels C (even though it would succeed)
22# 2. Waits for all tasks to finish
23# 3. Raises ExceptionGroup with the ValueError

步驟 4：並行與循序的混合模式

實際應用中，常需要混合並行和循序操作：

  1async def check_worktrees_batched(
  2    worktrees: list[str],
  3    batch_size: int = 5
  4) -> dict[str, str]:
  5    """
  6    分批並行處理：控制同時執行的任務數量
  7
  8    適用場景：
  9    - 避免同時開啟過多進程
 10    - 防止 API rate limiting
 11    - 控制資源使用
 12
 13    Args:
 14        worktrees: worktree 路徑列表
 15        batch_size: 每批並行數量
 16
 17    Returns:
 18        dict[str, str]: {路徑: 狀態} 映射
 19    """
 20    results: dict[str, str] = {}
 21
 22    # Process in batches
 23    for i in range(0, len(worktrees), batch_size):
 24        batch = worktrees[i:i + batch_size]
 25
 26        async def check_one(path: str) -> tuple[str, str]:
 27            success, output = await async_run_git_command(
 28                ["status", "-s"],
 29                cwd=path
 30            )
 31            return path, output if success else "error"
 32
 33        # Process batch in parallel
 34        batch_results = await asyncio.gather(
 35            *[check_one(path) for path in batch]
 36        )
 37
 38        # Collect results
 39        results.update(dict(batch_results))
 40
 41    return results
 42
 43async def check_worktrees_semaphore(
 44    worktrees: list[str],
 45    max_concurrent: int = 5
 46) -> dict[str, str]:
 47    """
 48    使用 Semaphore 限制並行數量
 49
 50    比分批更靈活：任務完成後立即啟動新任務，
 51    而不是等整批完成。
 52
 53    Args:
 54        worktrees: worktree 路徑列表
 55        max_concurrent: 最大同時執行數
 56
 57    Returns:
 58        dict[str, str]: {路徑: 狀態} 映射
 59    """
 60    semaphore = asyncio.Semaphore(max_concurrent)
 61
 62    async def check_with_limit(path: str) -> tuple[str, str]:
 63        """Check worktree with concurrency limit"""
 64        async with semaphore:
 65            # At most max_concurrent tasks run this block
 66            success, output = await async_run_git_command(
 67                ["status", "-s"],
 68                cwd=path
 69            )
 70            return path, output if success else "error"
 71
 72    # Launch all tasks (they'll wait at semaphore if needed)
 73    tasks = [check_with_limit(path) for path in worktrees]
 74    results = await asyncio.gather(*tasks)
 75
 76    return dict(results)
 77
 78async def pipeline_example():
 79    """
 80    示範流水線模式：前一步的輸出是後一步的輸入
 81    """
 82    # Step 1: Get worktree list (single operation)
 83    worktrees = await async_get_worktree_list()
 84    paths = [wt["path"] for wt in worktrees]
 85
 86    # Step 2: Check status in parallel
 87    statuses = await check_all_worktrees_basic(paths)
 88
 89    # Step 3: For dirty repos, get detailed diff (parallel)
 90    dirty_paths = [p for p, s in statuses.items() if s]
 91
 92    async def get_diff(path: str) -> tuple[str, str]:
 93        success, diff = await async_run_git_command(["diff"], cwd=path)
 94        return path, diff if success else ""
 95
 96    diffs = dict(await asyncio.gather(
 97        *[get_diff(p) for p in dirty_paths]
 98    ))
 99
100    return {"statuses": statuses, "diffs": diffs}

完整程式碼

  1#!/usr/bin/env python3
  2"""
  3並行 I/O 操作工具 - 完整範例
  4
  5展示如何用 asyncio.gather 和 TaskGroup 實現高效的並行 Git 操作。
  6"""
  7
  8import asyncio
  9import time
 10from typing import Optional
 11
 12# ===== Core async function =====
 13
 14async def async_run_git_command(
 15    args: list[str],
 16    cwd: Optional[str] = None,
 17    timeout: float = 10.0
 18) -> tuple[bool, str]:
 19    """
 20    非同步執行 git 命令
 21
 22    Args:
 23        args: git 命令參數列表
 24        cwd: 執行目錄
 25        timeout: 超時時間（秒）
 26
 27    Returns:
 28        (是否成功, 輸出或錯誤訊息)
 29    """
 30    try:
 31        process = await asyncio.create_subprocess_exec(
 32            "git", *args,
 33            cwd=cwd,
 34            stdout=asyncio.subprocess.PIPE,
 35            stderr=asyncio.subprocess.PIPE
 36        )
 37
 38        try:
 39            stdout, stderr = await asyncio.wait_for(
 40                process.communicate(),
 41                timeout=timeout
 42            )
 43        except asyncio.TimeoutError:
 44            process.kill()
 45            await process.wait()
 46            return False, f"Command timed out after {timeout}s"
 47
 48        if process.returncode == 0:
 49            return True, stdout.decode().strip()
 50        else:
 51            return False, stderr.decode().strip()
 52
 53    except FileNotFoundError:
 54        return False, "git command not found"
 55    except Exception as e:
 56        return False, str(e)
 57
 58async def async_get_worktree_list() -> list[dict]:
 59    """獲取 worktree 列表"""
 60    success, output = await async_run_git_command(
 61        ["worktree", "list", "--porcelain"]
 62    )
 63    if not success:
 64        return []
 65
 66    worktrees = []
 67    current_worktree: dict = {}
 68
 69    for line in output.split("\n"):
 70        if line.startswith("worktree "):
 71            if current_worktree:
 72                worktrees.append(current_worktree)
 73            current_worktree = {"path": line[9:]}
 74        elif line.startswith("branch "):
 75            branch_ref = line[7:]
 76            if branch_ref.startswith("refs/heads/"):
 77                branch_ref = branch_ref[11:]
 78            current_worktree["branch"] = branch_ref
 79        elif line == "detached":
 80            current_worktree["detached"] = True
 81
 82    if current_worktree:
 83        worktrees.append(current_worktree)
 84
 85    return worktrees
 86
 87# ===== Parallel strategies =====
 88
 89async def parallel_with_gather(
 90    worktrees: list[str],
 91    return_exceptions: bool = False
 92) -> dict[str, str]:
 93    """
 94    Strategy 1: asyncio.gather
 95
 96    Args:
 97        worktrees: worktree 路徑列表
 98        return_exceptions: 是否將異常作為結果返回
 99
100    Returns:
101        dict[str, str]: 檢查結果
102    """
103    async def check_one(path: str) -> tuple[str, str]:
104        success, output = await async_run_git_command(
105            ["status", "-s"],
106            cwd=path
107        )
108        return path, output if success else "error"
109
110    tasks = [check_one(path) for path in worktrees]
111    results = await asyncio.gather(*tasks, return_exceptions=return_exceptions)
112
113    output = {}
114    for path, result in zip(worktrees, results):
115        if isinstance(result, Exception):
116            output[path] = f"exception: {result}"
117        else:
118            _, status = result
119            output[path] = status if status else "clean"
120
121    return output
122
123async def parallel_with_taskgroup(worktrees: list[str]) -> dict[str, str]:
124    """
125    Strategy 2: TaskGroup (Python 3.11+)
126
127    One task fails -> all cancelled
128    """
129    results: dict[str, str] = {}
130
131    async def check_and_store(path: str) -> None:
132        success, output = await async_run_git_command(
133            ["status", "-s"],
134            cwd=path
135        )
136        results[path] = output if success else "error"
137
138    async with asyncio.TaskGroup() as tg:
139        for path in worktrees:
140            tg.create_task(check_and_store(path))
141
142    return results
143
144async def parallel_with_semaphore(
145    worktrees: list[str],
146    max_concurrent: int = 5
147) -> dict[str, str]:
148    """
149    Strategy 3: Semaphore for rate limiting
150    """
151    semaphore = asyncio.Semaphore(max_concurrent)
152
153    async def check_with_limit(path: str) -> tuple[str, str]:
154        async with semaphore:
155            success, output = await async_run_git_command(
156                ["status", "-s"],
157                cwd=path
158            )
159            return path, output if success else "error"
160
161    tasks = [check_with_limit(path) for path in worktrees]
162    results = await asyncio.gather(*tasks)
163
164    return dict(results)
165
166# ===== Practical helpers =====
167
168async def get_worktree_status_report() -> dict:
169    """
170    生成完整的 worktree 狀態報告
171
172    Returns:
173        dict: 包含狀態、分支、變更的完整報告
174    """
175    # Step 1: Get worktree list
176    worktrees = await async_get_worktree_list()
177    paths = [wt["path"] for wt in worktrees]
178
179    if not paths:
180        return {"error": "No worktrees found"}
181
182    # Step 2: Parallel operations
183    async def get_status(path: str) -> tuple[str, str]:
184        success, output = await async_run_git_command(
185            ["status", "-s"],
186            cwd=path
187        )
188        return path, output if success else "error"
189
190    async def get_branch(path: str) -> tuple[str, str]:
191        success, output = await async_run_git_command(
192            ["branch", "--show-current"],
193            cwd=path
194        )
195        return path, output if success else "unknown"
196
197    async def get_last_commit(path: str) -> tuple[str, str]:
198        success, output = await async_run_git_command(
199            ["log", "-1", "--format=%s"],
200            cwd=path
201        )
202        return path, output if success else "unknown"
203
204    # Execute all queries in parallel
205    status_task = asyncio.gather(*[get_status(p) for p in paths])
206    branch_task = asyncio.gather(*[get_branch(p) for p in paths])
207    commit_task = asyncio.gather(*[get_last_commit(p) for p in paths])
208
209    statuses, branches, commits = await asyncio.gather(
210        status_task, branch_task, commit_task
211    )
212
213    # Combine results
214    report = {}
215    for wt in worktrees:
216        path = wt["path"]
217        status_dict = dict(statuses)
218        branch_dict = dict(branches)
219        commit_dict = dict(commits)
220
221        report[path] = {
222            "branch": branch_dict.get(path, "unknown"),
223            "status": status_dict.get(path, "error"),
224            "is_clean": not status_dict.get(path, "error"),
225            "last_commit": commit_dict.get(path, "unknown"),
226        }
227
228    return report
229
230# ===== Benchmark =====
231
232async def benchmark_strategies(worktrees: list[str]) -> dict[str, float]:
233    """
234    比較不同策略的執行時間
235    """
236    results = {}
237
238    # Strategy 1: Sequential (baseline)
239    start = time.perf_counter()
240    for path in worktrees:
241        await async_run_git_command(["status", "-s"], cwd=path)
242    results["sequential"] = time.perf_counter() - start
243
244    # Strategy 2: gather
245    start = time.perf_counter()
246    await parallel_with_gather(worktrees)
247    results["gather"] = time.perf_counter() - start
248
249    # Strategy 3: TaskGroup
250    start = time.perf_counter()
251    await parallel_with_taskgroup(worktrees)
252    results["taskgroup"] = time.perf_counter() - start
253
254    # Strategy 4: Semaphore
255    start = time.perf_counter()
256    await parallel_with_semaphore(worktrees, max_concurrent=3)
257    results["semaphore(3)"] = time.perf_counter() - start
258
259    return results
260
261# ===== Demo =====
262
263async def demo():
264    """示範並行 I/O 操作"""
265    print("=== 並行 I/O 操作示範 ===\n")
266
267    # Get worktrees
268    print("1. 獲取 worktree 列表:")
269    worktrees = await async_get_worktree_list()
270    paths = [wt["path"] for wt in worktrees]
271
272    for wt in worktrees:
273        branch = wt.get("branch", "detached")
274        print(f"   - {branch}: {wt['path']}")
275    print()
276
277    if len(paths) >= 1:
278        # Benchmark
279        print("2. 效能比較:")
280        times = await benchmark_strategies(paths)
281        for strategy, elapsed in times.items():
282            print(f"   {strategy}: {elapsed:.3f}s")
283
284        speedup = times["sequential"] / times["gather"]
285        print(f"   加速比: {speedup:.1f}x")
286        print()
287
288        # Full report
289        print("3. 完整狀態報告:")
290        report = await get_worktree_status_report()
291        for path, info in report.items():
292            status = "clean" if info["is_clean"] else "dirty"
293            print(f"   [{info['branch']}] {path}")
294            print(f"       狀態: {status}")
295            print(f"       最新提交: {info['last_commit'][:50]}...")
296
297if __name__ == "__main__":
298    asyncio.run(demo())

使用範例

基本使用

 1import asyncio
 2
 3async def main():
 4    # Get all worktree paths
 5    worktrees = await async_get_worktree_list()
 6    paths = [wt["path"] for wt in worktrees]
 7
 8    # Check all in parallel
 9    statuses = await parallel_with_gather(paths)
10
11    for path, status in statuses.items():
12        print(f"{path}: {status or 'clean'}")
13
14asyncio.run(main())

處理大量 worktree

 1async def check_many_worktrees(paths: list[str]):
 2    """處理大量 worktree 時使用 semaphore 限制並行數"""
 3    # Limit to 10 concurrent git processes
 4    results = await parallel_with_semaphore(paths, max_concurrent=10)
 5
 6    clean_count = sum(1 for s in results.values() if not s or s == "clean")
 7    dirty_count = len(results) - clean_count
 8
 9    print(f"Clean: {clean_count}, Dirty: {dirty_count}")
10    return results

與錯誤重試結合

 1async def check_with_retry(
 2    path: str,
 3    max_retries: int = 3
 4) -> tuple[str, str]:
 5    """帶重試的檢查"""
 6    for attempt in range(max_retries):
 7        success, output = await async_run_git_command(
 8            ["status", "-s"],
 9            cwd=path,
10            timeout=5.0
11        )
12
13        if success:
14            return path, output
15
16        if attempt < max_retries - 1:
17            await asyncio.sleep(0.5 * (attempt + 1))  # Backoff
18
19    return path, "error: max retries exceeded"
20
21async def check_all_with_retry(paths: list[str]) -> dict[str, str]:
22    """所有檢查都帶重試機制"""
23    tasks = [check_with_retry(p) for p in paths]
24    results = await asyncio.gather(*tasks)
25    return dict(results)

設計權衡

面向	asyncio.gather	TaskGroup	Semaphore
Python 版本	3.4+	3.11+	3.4+
錯誤處理	`return_exceptions`	自動取消其他任務	同 gather
取消行為	需手動處理	結構化取消	需手動處理
程式碼可讀性	中等	較高	中等
並行控制	無內建限制	無內建限制	可限制數量
適用場景	一般並行	全有或全無	需要限流

選擇指南

1需要並行執行多個獨立 I/O 操作？
2├── 是 → 是否需要「一個失敗全部取消」？
3│        ├── 是 → 使用 TaskGroup
4│        └── 否 → 是否需要限制並行數量？
5│                 ├── 是 → 使用 Semaphore + gather
6│                 └── 否 → 使用 gather（可選 return_exceptions）
7└── 否 → 直接使用 await

什麼時候該用這個技術？

適合使用：

多個獨立的 I/O 操作（HTTP 請求、檔案讀取、資料庫查詢）
需要等待所有操作完成
操作之間沒有依賴關係
單一操作耗時較長（> 10ms）

不建議使用：

CPU 密集計算（應用 multiprocessing）
操作之間有依賴關係（應用循序執行或流水線）
單一操作極快（overhead 可能大於收益）
外部服務有嚴格的 rate limit（需要更精細的控制）

練習

基礎練習

練習 1：用 gather 同時讀取多個設定檔

1async def read_configs(paths: list[str]) -> dict[str, str]:
2    """
3    並行讀取多個設定檔
4
5    提示：使用 aiofiles 或 asyncio.to_thread
6    """
7    # Your implementation here
8    pass

練習 2：實作 worktree 狀態快取

 1class WorktreeCache:
 2    """
 3    快取 worktree 狀態，避免頻繁查詢
 4
 5    提示：
 6    - 使用 dict 儲存狀態
 7    - 設定過期時間
 8    - 過期時重新並行查詢
 9    """
10    def __init__(self, ttl_seconds: float = 30.0):
11        self._cache: dict[str, tuple[str, float]] = {}
12        self._ttl = ttl_seconds
13
14    async def get_status(self, path: str) -> str:
15        # Your implementation here
16        pass
17
18    async def get_all_statuses(self, paths: list[str]) -> dict[str, str]:
19        # Your implementation here
20        pass

進階練習

練習 3：實作帶有重試邏輯的並行下載器

 1async def parallel_download(
 2    urls: list[str],
 3    max_concurrent: int = 5,
 4    max_retries: int = 3
 5) -> dict[str, bytes | Exception]:
 6    """
 7    並行下載多個 URL，支援重試
 8
 9    提示：
10    - 使用 Semaphore 限制並行數
11    - 實作指數退避（exponential backoff）
12    - 使用 aiohttp 進行非同步 HTTP 請求
13    """
14    # Your implementation here
15    pass

挑戰題

練習 4：實作 semaphore 限制並行數量的 TaskGroup

 1class BoundedTaskGroup:
 2    """
 3    限制最大並行數的 TaskGroup
 4
 5    使用方式：
 6        async with BoundedTaskGroup(max_concurrent=5) as tg:
 7            for item in items:
 8                tg.create_task(process(item))
 9
10    提示：
11    - 結合 Semaphore 和 TaskGroup
12    - 保持 TaskGroup 的錯誤處理語義
13    """
14    def __init__(self, max_concurrent: int):
15        self._semaphore = asyncio.Semaphore(max_concurrent)
16        self._tg: asyncio.TaskGroup | None = None
17
18    async def __aenter__(self):
19        # Your implementation here
20        pass
21
22    async def __aexit__(self, *args):
23        # Your implementation here
24        pass
25
26    def create_task(self, coro):
27        # Your implementation here
28        pass

練習 5：實作監控儀表板

建立一個即時監控多個 Git repo 狀態的工具：

 1async def monitor_repos(
 2    repos: list[str],
 3    interval: float = 5.0,
 4    on_change: callable = None
 5):
 6    """
 7    每隔 interval 秒並行檢查所有 repo
 8    狀態變化時呼叫 on_change callback
 9
10    提示：
11    - 使用 asyncio.sleep 控制間隔
12    - 比較前後狀態找出變化
13    - 支援 Ctrl+C 優雅退出
14    """
15    # Your implementation here
16    pass

1.2 協程與 Task 管理

Tue, 20 Jan 2026 00:00:00 +0000

本章深入探討協程的執行機制，以及如何使用 Task 管理並發任務。

先備知識

1.1 基礎概念與事件迴圈

本章目標

學完本章後，你將能夠：

理解協程、Task、Future 的區別與關係
使用 create_task() 建立並發任務
使用 gather()、wait() 和 TaskGroup 管理多個任務
正確處理任務取消與超時

【原理層】可等待物件

協程、Task、Future

在 asyncio 中，有三種「可等待物件」（Awaitable）：

 1import asyncio
 2
 3# 1. 協程（Coroutine）
 4async def my_coroutine():
 5    return 42
 6
 7# 2. Task - 協程的包裝，可追蹤狀態
 8task = asyncio.create_task(my_coroutine())
 9
10# 3. Future - 底層的「未來結果」容器
11future = asyncio.Future()

它們的關係：

 1         ┌─────────────────────┐
 2         │     Awaitable       │
 3         │   （可等待物件）      │
 4         └─────────────────────┘
 5                   ▲
 6         ┌─────────┼─────────┐
 7         │         │         │
 8    Coroutine   Future     Task
 9     （協程）   （未來）  （任務）
10                   ▲
11                   │
12                 Task
13           （Task 繼承自 Future）

await 的語義

當你 await 一個物件時：

如果結果已就緒，立即返回
如果結果未就緒，暫停當前協程，讓出控制權
當結果就緒時，恢復執行

 1async def demo():
 2    # await 協程
 3    result1 = await some_coroutine()
 4
 5    # await Task
 6    task = asyncio.create_task(some_coroutine())
 7    result2 = await task
 8
 9    # await Future
10    future = asyncio.Future()
11    # ... 某處設定 future.set_result(value)
12    result3 = await future

【設計層】Task 管理

create_task() 的時機

create_task() 將協程包裝成 Task 並排程執行：

 1async def worker(name, delay):
 2    print(f"{name} 開始")
 3    await asyncio.sleep(delay)
 4    print(f"{name} 完成")
 5    return f"{name} 結果"
 6
 7async def main():
 8    # 方法 1：依序執行（不並發）
 9    result1 = await worker("A", 1)
10    result2 = await worker("B", 1)
11    # 總時間：2 秒
12
13    # 方法 2：先建立 Task，再 await（並發）
14    task1 = asyncio.create_task(worker("C", 1))
15    task2 = asyncio.create_task(worker("D", 1))
16    result3 = await task1
17    result4 = await task2
18    # 總時間：1 秒
19
20asyncio.run(main())

重要：create_task() 會立即排程任務，即使你還沒 await 它。

gather() vs wait() vs TaskGroup

三種管理多個任務的方式：

 1async def main():
 2    tasks = [worker(f"Task-{i}", 1) for i in range(3)]
 3
 4    # gather()：等待所有完成，返回結果列表
 5    results = await asyncio.gather(*tasks)
 6
 7    # wait()：更細緻的控制
 8    done, pending = await asyncio.wait(
 9        tasks,
10        return_when=asyncio.FIRST_COMPLETED  # 或 ALL_COMPLETED
11    )
12
13    # TaskGroup（Python 3.11+）：結構化並發
14    async with asyncio.TaskGroup() as tg:
15        task1 = tg.create_task(worker("A", 1))
16        task2 = tg.create_task(worker("B", 1))
17    # 離開 context 時，所有任務都已完成

方法	特點	使用場景
`gather()`	簡單，返回結果列表	等待所有任務完成
`wait()`	可選擇等待策略	需要處理先完成的任務
`TaskGroup`	結構化，異常處理更好	Python 3.11+，推薦使用

【實作層】任務生命週期

任務狀態

 1async def demo():
 2    task = asyncio.create_task(asyncio.sleep(1))
 3
 4    print(f"已完成：{task.done()}")      # False
 5    print(f"已取消：{task.cancelled()}")  # False
 6
 7    await task
 8
 9    print(f"已完成：{task.done()}")      # True
10    print(f"結果：{task.result()}")      # None（sleep 返回 None）

取消任務

 1async def long_running():
 2    try:
 3        await asyncio.sleep(10)
 4    except asyncio.CancelledError:
 5        print("任務被取消")
 6        raise  # 重要：要重新拋出
 7
 8async def main():
 9    task = asyncio.create_task(long_running())
10    await asyncio.sleep(1)  # 讓任務開始
11    task.cancel()           # 請求取消
12
13    try:
14        await task
15    except asyncio.CancelledError:
16        print("確認已取消")

超時控制

 1async def main():
 2    # 方法 1：wait_for
 3    try:
 4        result = await asyncio.wait_for(long_running(), timeout=2.0)
 5    except asyncio.TimeoutError:
 6        print("超時")
 7
 8    # 方法 2：timeout（Python 3.11+）
 9    try:
10        async with asyncio.timeout(2.0):
11            result = await long_running()
12    except asyncio.TimeoutError:
13        print("超時")

【常見錯誤】

1. 協程從未執行

1async def main():
2    # 錯誤：只建立了協程物件，沒有執行
3    worker("A", 1)  # RuntimeWarning!
4
5    # 正確
6    await worker("A", 1)

2. Task 被垃圾回收

1async def main():
2    # 錯誤：task 沒有被引用，可能被 GC
3    asyncio.create_task(worker("A", 1))
4
5    # 正確：保持引用
6    task = asyncio.create_task(worker("A", 1))
7    await task

3. 異常被吞掉

1async def failing_task():
2    raise ValueError("出錯了")
3
4async def main():
5    task = asyncio.create_task(failing_task())
6    await asyncio.sleep(1)  # 異常不會在這裡拋出
7    # 必須 await task 才會看到異常

思考題

await task 和 await asyncio.gather(task) 有什麼區別？
為什麼 CancelledError 要重新拋出？
TaskGroup 相比 gather() 有什麼優勢？

實作練習

實作一個函式，並發執行多個任務，但限制同時執行的數量（提示：使用 Semaphore）
實作一個「競速」函式，返回最先完成的任務結果
實作一個任務管理器，可以動態新增和取消任務

延伸閱讀

上一章：基礎概念與事件迴圈 下一章：設計模式與最佳實踐

案例：同步/非同步橋接

Wed, 21 Jan 2026 00:00:00 +0000

本案例基於 .claude/lib 整體架構，展示如何用 run_in_executor 和 asyncio.run 在同步與非同步程式碼之間建立橋樑。

先備知識

問題背景

現有設計

.claude/lib 是一個同步設計的 Python 工具庫，包含多個模組：

 1# .claude/lib/__init__.py
 2"""
 3Claude Hooks 共用程式庫
 4
 5模組結構:
 6- git_utils: Git 操作工具（分支、worktree、專案根目錄）
 7- config_loader: 配置檔案載入
 8- hook_io: Hook 輸入輸出處理
 9- hook_validator: Hook 合規性驗證
10- markdown_link_checker: Markdown 連結檢查
11"""
12
13from .git_utils import (
14    run_git_command,
15    get_current_branch,
16    get_project_root,
17    get_worktree_list,
18)
19
20from .config_loader import (
21    load_config,
22    load_agents_config,
23)
24
25from .hook_io import (
26    read_hook_input,
27    write_hook_output,
28)

這些函式都是同步的：

 1# git_utils.py - 同步的 subprocess 呼叫
 2def run_git_command(
 3    args: list[str],
 4    cwd: Optional[str] = None,
 5    timeout: int = 10
 6) -> tuple[bool, str]:
 7    """Execute git command and return result"""
 8    result = subprocess.run(
 9        ["git"] + args,
10        cwd=cwd,
11        capture_output=True,
12        text=True,
13        timeout=timeout
14    )
15    if result.returncode == 0:
16        return True, result.stdout.strip()
17    return False, result.stderr.strip()
18
19# config_loader.py - 同步的檔案 I/O
20def load_config(config_name: str) -> dict:
21    """Load configuration file"""
22    config_dir = get_config_dir()
23    yaml_path = config_dir / f"{config_name}.yaml"
24
25    with open(yaml_path, "r", encoding="utf-8") as f:
26        return yaml.safe_load(f)
27
28# hook_validator.py - 同步的檔案驗證
29def validate_hook(hook_path: str) -> ValidationResult:
30    """Validate a single hook file"""
31    with open(hook_path, "r", encoding="utf-8") as f:
32        content = f.read()
33    # ... validation logic

這個設計的優點

簡單直覺：不需要了解 asyncio，任何 Python 開發者都能使用
向後相容：可以在任何 Python 環境中執行
測試容易：同步程式碼的測試更直觀
依賴少：不需要額外的非同步依賴庫

這個設計的限制

在非同步環境（如 FastAPI、aiohttp）中使用時：

問題 1：阻塞事件迴圈

 1from fastapi import FastAPI
 2from lib.git_utils import get_current_branch, get_worktree_list
 3
 4app = FastAPI()
 5
 6@app.get("/git/status")
 7async def get_git_status():
 8    # BAD: These synchronous calls block the event loop!
 9    branch = get_current_branch()      # Blocks ~50ms
10    worktrees = get_worktree_list()    # Blocks ~50ms
11
12    # During these 100ms, NO other requests can be processed!
13    return {"branch": branch, "worktrees": worktrees}

問題 2：無法並行執行

 1def validate_all_hooks(hooks_dir: str) -> list[ValidationResult]:
 2    """Validate all hooks - sequential execution"""
 3    results = []
 4    for hook_file in Path(hooks_dir).glob("*.py"):
 5        # Each validation runs one after another
 6        result = validate_hook(str(hook_file))  # ~10ms each
 7        results.append(result)
 8    return results
 9
10# 10 hooks = 100ms total
11# With parallelization, could be ~10ms!

問題 3：無法有效利用等待時間

 1def check_project_health() -> dict:
 2    """Check multiple aspects of project health"""
 3    # All I/O operations execute sequentially
 4    git_status = run_git_command(["status", "-s"])      # Wait...
 5    config = load_config("agents")                       # Wait...
 6    links = check_markdown_links("docs/README.md")       # Wait...
 7
 8    # Total time = sum of all operations
 9    return {
10        "git": git_status,
11        "config": config,
12        "links": links
13    }

進階解決方案

設計目標

在非同步程式碼中安全地呼叫同步函式（不阻塞事件迴圈）
在同步程式碼中使用非同步函式（保持向後相容）
避免巢狀事件迴圈問題
保持原有 API 不變

實作步驟

步驟 1：run_in_executor - 同步到非同步

run_in_executor 將同步函式放到執行緒池中執行，讓事件迴圈可以繼續處理其他任務。

 1import asyncio
 2from concurrent.futures import ThreadPoolExecutor
 3from typing import TypeVar, Callable, Any
 4
 5T = TypeVar('T')
 6
 7# Create a shared thread pool for I/O operations
 8_io_executor = ThreadPoolExecutor(max_workers=10, thread_name_prefix="async_io")
 9
10async def run_sync_in_executor(
11    func: Callable[..., T],
12    *args: Any,
13    **kwargs: Any
14) -> T:
15    """
16    Run a synchronous function in a thread pool executor.
17
18    This prevents blocking the event loop when calling
19    synchronous I/O operations from async code.
20
21    Args:
22        func: The synchronous function to execute
23        *args: Positional arguments for the function
24        **kwargs: Keyword arguments for the function
25
26    Returns:
27        The result of the function call
28
29    Example:
30        # Instead of blocking:
31        result = sync_function(arg1, arg2)
32
33        # Use executor:
34        result = await run_sync_in_executor(sync_function, arg1, arg2)
35    """
36    loop = asyncio.get_running_loop()
37
38    # functools.partial handles kwargs
39    if kwargs:
40        import functools
41        func = functools.partial(func, **kwargs)
42
43    return await loop.run_in_executor(_io_executor, func, *args)

使用範例：包裝現有同步函式

 1from lib.git_utils import get_current_branch, get_worktree_list, run_git_command
 2from lib.config_loader import load_config
 3from lib.hook_validator import validate_hook
 4
 5# Async wrappers for existing sync functions
 6async def async_get_current_branch() -> Optional[str]:
 7    """Async wrapper for get_current_branch"""
 8    return await run_sync_in_executor(get_current_branch)
 9
10async def async_get_worktree_list() -> list[dict]:
11    """Async wrapper for get_worktree_list"""
12    return await run_sync_in_executor(get_worktree_list)
13
14async def async_load_config(config_name: str) -> dict:
15    """Async wrapper for load_config"""
16    return await run_sync_in_executor(load_config, config_name)
17
18async def async_validate_hook(hook_path: str) -> ValidationResult:
19    """Async wrapper for validate_hook"""
20    return await run_sync_in_executor(validate_hook, hook_path)

步驟 2：asyncio.run - 非同步到同步

當你有非同步程式碼，但需要從同步環境呼叫時，使用 asyncio.run。

 1import asyncio
 2from typing import TypeVar, Coroutine
 3
 4T = TypeVar('T')
 5
 6def run_async(coro: Coroutine[Any, Any, T]) -> T:
 7    """
 8    Run an async function from synchronous code.
 9
10    Creates a new event loop if none exists.
11    Safe to call from synchronous entry points.
12
13    Args:
14        coro: The coroutine to execute
15
16    Returns:
17        The result of the coroutine
18
19    Example:
20        # From a synchronous script:
21        result = run_async(async_function(arg1, arg2))
22
23    Warning:
24        Cannot be called when an event loop is already running!
25        Use nest_asyncio or redesign your code structure.
26    """
27    return asyncio.run(coro)
28
29# Synchronous API that uses async implementation internally
30def get_all_worktree_branches() -> dict[str, str]:
31    """
32    Get branches for all worktrees.
33
34    Uses async implementation internally for parallelization,
35    but provides a synchronous API for compatibility.
36    """
37    async def _async_impl():
38        worktrees = await async_get_worktree_list()
39        tasks = []
40        for wt in worktrees:
41            path = wt["path"]
42            tasks.append(_get_branch_for_path(path))
43        results = await asyncio.gather(*tasks)
44        return dict(zip([wt["path"] for wt in worktrees], results))
45
46    return run_async(_async_impl())
47
48async def _get_branch_for_path(path: str) -> str:
49    """Get current branch for a specific path"""
50    success, output = await run_sync_in_executor(
51        run_git_command,
52        ["branch", "--show-current"],
53        cwd=path
54    )
55    return output if success else "unknown"

步驟 3：處理已存在的事件迴圈

當你在已有事件迴圈的環境中（如 Jupyter Notebook、某些 Web 框架），直接呼叫 asyncio.run 會失敗：

1# This will raise RuntimeError in Jupyter or when loop is running
2asyncio.run(some_coroutine())
3# RuntimeError: asyncio.run() cannot be called from a running event loop

解決方案 A：使用 nest_asyncio（快速修復）

 1# pip install nest-asyncio
 2import nest_asyncio
 3
 4def run_async_safe(coro: Coroutine[Any, Any, T]) -> T:
 5    """
 6    Run async code safely, even from a running event loop.
 7
 8    Uses nest_asyncio to allow nested event loops.
 9    This is a pragmatic solution for environments like Jupyter.
10
11    Note:
12        nest_asyncio patches the event loop globally.
13        Use with caution in production code.
14    """
15    try:
16        loop = asyncio.get_running_loop()
17    except RuntimeError:
18        # No running loop - safe to use asyncio.run
19        return asyncio.run(coro)
20
21    # Running loop exists - need to nest
22    nest_asyncio.apply()
23    return loop.run_until_complete(coro)

解決方案 B：偵測執行環境（推薦）

 1import asyncio
 2from typing import TypeVar, Coroutine, Any
 3
 4T = TypeVar('T')
 5
 6def is_event_loop_running() -> bool:
 7    """Check if there's a running event loop"""
 8    try:
 9        asyncio.get_running_loop()
10        return True
11    except RuntimeError:
12        return False
13
14def run_async_adaptive(coro: Coroutine[Any, Any, T]) -> T:
15    """
16    Run async code with automatic environment detection.
17
18    - If no event loop: uses asyncio.run()
19    - If loop running: uses run_in_executor to run in a new thread
20
21    This is safer than nest_asyncio for production use.
22    """
23    if is_event_loop_running():
24        # We're in an async context - run in a new thread
25        import concurrent.futures
26        with concurrent.futures.ThreadPoolExecutor() as executor:
27            future = executor.submit(asyncio.run, coro)
28            return future.result()
29    else:
30        # Safe to run directly
31        return asyncio.run(coro)

解決方案 C：提供雙重 API（最佳實踐）

 1class GitUtils:
 2    """
 3    Git utilities with both sync and async APIs.
 4
 5    Usage:
 6        # Synchronous (traditional)
 7        utils = GitUtils()
 8        branch = utils.get_current_branch()
 9
10        # Asynchronous
11        branch = await utils.async_get_current_branch()
12    """
13
14    def __init__(self, cwd: Optional[str] = None):
15        self.cwd = cwd
16
17    # ===== Synchronous API (original) =====
18
19    def get_current_branch(self) -> Optional[str]:
20        """Get current branch (sync)"""
21        success, output = run_git_command(
22            ["branch", "--show-current"],
23            cwd=self.cwd
24        )
25        return output if success else None
26
27    def get_worktree_list(self) -> list[dict]:
28        """Get worktree list (sync)"""
29        # ... original implementation
30        pass
31
32    # ===== Asynchronous API =====
33
34    async def async_get_current_branch(self) -> Optional[str]:
35        """Get current branch (async)"""
36        return await run_sync_in_executor(self.get_current_branch)
37
38    async def async_get_worktree_list(self) -> list[dict]:
39        """Get worktree list (async)"""
40        return await run_sync_in_executor(self.get_worktree_list)

步驟 4：建立統一的 API

整合以上模式，建立一個統一的適配器：

  1"""
  2Sync/Async Bridge Adapter
  3
  4Provides unified access to .claude/lib modules from both
  5synchronous and asynchronous contexts.
  6"""
  7
  8import asyncio
  9import functools
 10from concurrent.futures import ThreadPoolExecutor
 11from typing import TypeVar, Callable, Any, Optional, Coroutine
 12
 13T = TypeVar('T')
 14
 15# Shared executor for I/O operations
 16_executor = ThreadPoolExecutor(max_workers=10, thread_name_prefix="lib_async")
 17
 18class AsyncAdapter:
 19    """
 20    Adapter for converting sync functions to async.
 21
 22    Provides both decorator and wrapper patterns for flexibility.
 23
 24    Example:
 25        adapter = AsyncAdapter()
 26
 27        # As decorator
 28        @adapter.make_async
 29        def sync_function(x):
 30            return x * 2
 31
 32        result = await sync_function(5)
 33
 34        # As wrapper
 35        result = await adapter.run(other_sync_function, arg1, arg2)
 36    """
 37
 38    def __init__(self, executor: Optional[ThreadPoolExecutor] = None):
 39        self.executor = executor or _executor
 40
 41    async def run(
 42        self,
 43        func: Callable[..., T],
 44        *args: Any,
 45        **kwargs: Any
 46    ) -> T:
 47        """Run a sync function asynchronously"""
 48        loop = asyncio.get_running_loop()
 49
 50        if kwargs:
 51            func = functools.partial(func, **kwargs)
 52
 53        return await loop.run_in_executor(self.executor, func, *args)
 54
 55    def make_async(self, func: Callable[..., T]) -> Callable[..., Coroutine[Any, Any, T]]:
 56        """
 57        Decorator to create async version of sync function.
 58
 59        Example:
 60            @adapter.make_async
 61            def slow_io_operation(path: str) -> str:
 62                with open(path) as f:
 63                    return f.read()
 64
 65            # Now can be awaited
 66            content = await slow_io_operation("file.txt")
 67        """
 68        @functools.wraps(func)
 69        async def wrapper(*args: Any, **kwargs: Any) -> T:
 70            return await self.run(func, *args, **kwargs)
 71        return wrapper
 72
 73class SyncAdapter:
 74    """
 75    Adapter for calling async functions from sync code.
 76
 77    Example:
 78        adapter = SyncAdapter()
 79
 80        # Run async function synchronously
 81        result = adapter.run(async_function(arg1, arg2))
 82    """
 83
 84    @staticmethod
 85    def run(coro: Coroutine[Any, Any, T]) -> T:
 86        """
 87        Run a coroutine from synchronous code.
 88
 89        Automatically handles the case when an event loop
 90        is already running.
 91        """
 92        try:
 93            asyncio.get_running_loop()
 94            # Loop is running - use thread
 95            import concurrent.futures
 96            with concurrent.futures.ThreadPoolExecutor(max_workers=1) as ex:
 97                future = ex.submit(asyncio.run, coro)
 98                return future.result()
 99        except RuntimeError:
100            # No running loop - safe to use asyncio.run
101            return asyncio.run(coro)
102
103    @staticmethod
104    def make_sync(
105        async_func: Callable[..., Coroutine[Any, Any, T]]
106    ) -> Callable[..., T]:
107        """
108        Decorator to create sync version of async function.
109
110        Example:
111            @SyncAdapter.make_sync
112            async def async_fetch(url: str) -> str:
113                async with aiohttp.get(url) as resp:
114                    return await resp.text()
115
116            # Now can be called synchronously
117            content = async_fetch("https://example.com")
118        """
119        @functools.wraps(async_func)
120        def wrapper(*args: Any, **kwargs: Any) -> T:
121            coro = async_func(*args, **kwargs)
122            return SyncAdapter.run(coro)
123        return wrapper

完整程式碼

  1#!/usr/bin/env python3
  2"""
  3Sync/Async Bridge for .claude/lib
  4
  5This module provides async wrappers for the synchronous
  6.claude/lib modules, enabling their use in async contexts
  7like FastAPI without blocking the event loop.
  8
  9Usage:
 10    # In async code (FastAPI, aiohttp, etc.)
 11    from lib_async import (
 12        async_get_current_branch,
 13        async_load_config,
 14        async_validate_hooks,
 15    )
 16
 17    branch = await async_get_current_branch()
 18
 19    # In sync code that needs parallelization
 20    from lib_async import parallel_validate_hooks
 21
 22    results = parallel_validate_hooks(hooks_dir)
 23"""
 24
 25import asyncio
 26import functools
 27from concurrent.futures import ThreadPoolExecutor
 28from pathlib import Path
 29from typing import TypeVar, Callable, Any, Optional, Coroutine
 30
 31# Import original sync modules
 32from lib.git_utils import (
 33    run_git_command,
 34    get_current_branch,
 35    get_project_root,
 36    get_worktree_list,
 37    is_protected_branch,
 38    is_allowed_branch,
 39)
 40from lib.config_loader import (
 41    load_config,
 42    load_agents_config,
 43    load_quality_rules,
 44)
 45from lib.hook_io import (
 46    read_hook_input,
 47    write_hook_output,
 48)
 49from lib.hook_validator import (
 50    validate_hook,
 51    validate_all_hooks,
 52    ValidationResult,
 53)
 54from lib.markdown_link_checker import (
 55    check_markdown_links,
 56    check_directory as check_markdown_directory,
 57    LinkCheckResult,
 58)
 59
 60T = TypeVar('T')
 61
 62# ===== Shared Resources =====
 63
 64# Thread pool for I/O-bound sync operations
 65_io_executor = ThreadPoolExecutor(
 66    max_workers=10,
 67    thread_name_prefix="lib_async_io"
 68)
 69
 70# ===== Core Utilities =====
 71
 72async def run_in_executor(
 73    func: Callable[..., T],
 74    *args: Any,
 75    **kwargs: Any
 76) -> T:
 77    """
 78    Run a synchronous function in the thread pool executor.
 79
 80    Args:
 81        func: Synchronous function to execute
 82        *args: Positional arguments
 83        **kwargs: Keyword arguments
 84
 85    Returns:
 86        Function result
 87    """
 88    loop = asyncio.get_running_loop()
 89
 90    if kwargs:
 91        func = functools.partial(func, **kwargs)
 92
 93    return await loop.run_in_executor(_io_executor, func, *args)
 94
 95def make_async(func: Callable[..., T]) -> Callable[..., Coroutine[Any, Any, T]]:
 96    """
 97    Decorator to create async version of a sync function.
 98
 99    Example:
100        @make_async
101        def slow_operation(x):
102            time.sleep(1)
103            return x * 2
104
105        result = await slow_operation(5)
106    """
107    @functools.wraps(func)
108    async def wrapper(*args: Any, **kwargs: Any) -> T:
109        return await run_in_executor(func, *args, **kwargs)
110    return wrapper
111
112# ===== Async Git Utils =====
113
114async def async_run_git_command(
115    args: list[str],
116    cwd: Optional[str] = None,
117    timeout: int = 10
118) -> tuple[bool, str]:
119    """Async version of run_git_command"""
120    return await run_in_executor(run_git_command, args, cwd=cwd, timeout=timeout)
121
122async def async_get_current_branch() -> Optional[str]:
123    """Async version of get_current_branch"""
124    return await run_in_executor(get_current_branch)
125
126async def async_get_project_root() -> str:
127    """Async version of get_project_root"""
128    return await run_in_executor(get_project_root)
129
130async def async_get_worktree_list() -> list[dict]:
131    """Async version of get_worktree_list"""
132    return await run_in_executor(get_worktree_list)
133
134# ===== Async Config Loader =====
135
136async def async_load_config(config_name: str) -> dict:
137    """Async version of load_config"""
138    return await run_in_executor(load_config, config_name)
139
140async def async_load_agents_config() -> dict:
141    """Async version of load_agents_config"""
142    return await run_in_executor(load_agents_config)
143
144async def async_load_quality_rules() -> dict:
145    """Async version of load_quality_rules"""
146    return await run_in_executor(load_quality_rules)
147
148# ===== Async Hook Validator =====
149
150async def async_validate_hook(hook_path: str) -> ValidationResult:
151    """Async version of validate_hook"""
152    return await run_in_executor(validate_hook, hook_path)
153
154async def async_validate_all_hooks(
155    hooks_dir: Optional[str] = None
156) -> list[ValidationResult]:
157    """
158    Validate all hooks in parallel.
159
160    Unlike the sync version that validates sequentially,
161    this version validates all hooks concurrently.
162    """
163    if hooks_dir is None:
164        hooks_dir = str(Path(await async_get_project_root()) / ".claude" / "hooks")
165
166    hooks_path = Path(hooks_dir)
167    if not hooks_path.is_dir():
168        return []
169
170    # Collect all hook files
171    hook_files = [
172        str(f) for f in sorted(hooks_path.glob("*.py"))
173        if not f.name.startswith("_")
174    ]
175
176    # Validate all in parallel
177    tasks = [async_validate_hook(hook) for hook in hook_files]
178    return await asyncio.gather(*tasks)
179
180# ===== Async Markdown Link Checker =====
181
182async def async_check_markdown_links(file_path: str) -> LinkCheckResult:
183    """Async version of check_markdown_links"""
184    return await run_in_executor(check_markdown_links, file_path)
185
186async def async_check_markdown_directory(
187    dir_path: str,
188    recursive: bool = True
189) -> list[LinkCheckResult]:
190    """
191    Check all markdown files in directory in parallel.
192    """
193    # Get file list synchronously (fast operation)
194    dir_path_obj = Path(dir_path)
195    if not dir_path_obj.is_dir():
196        return []
197
198    if recursive:
199        md_files = list(dir_path_obj.rglob("*.md"))
200    else:
201        md_files = list(dir_path_obj.glob("*.md"))
202
203    # Check all files in parallel
204    tasks = [async_check_markdown_links(str(f)) for f in md_files]
205    return await asyncio.gather(*tasks)
206
207# ===== Parallel Operations =====
208
209async def async_check_all_worktrees() -> dict[str, dict]:
210    """
211    Check status of all worktrees in parallel.
212
213    Returns:
214        dict: {path: {"branch": str, "status": str, "is_clean": bool}}
215    """
216    worktrees = await async_get_worktree_list()
217
218    async def check_one(wt: dict) -> tuple[str, dict]:
219        path = wt["path"]
220
221        # Run git status and branch in parallel for each worktree
222        status_task = async_run_git_command(["status", "-s"], cwd=path)
223        branch_task = async_run_git_command(["branch", "--show-current"], cwd=path)
224
225        (status_ok, status), (branch_ok, branch) = await asyncio.gather(
226            status_task, branch_task
227        )
228
229        return path, {
230            "branch": branch if branch_ok else wt.get("branch", "unknown"),
231            "status": status if status_ok else "error",
232            "is_clean": status_ok and not status,
233        }
234
235    tasks = [check_one(wt) for wt in worktrees]
236    results = await asyncio.gather(*tasks)
237
238    return dict(results)
239
240async def async_project_health_check() -> dict:
241    """
242    Comprehensive project health check with parallel execution.
243
244    Checks:
245    - Git status
246    - Configuration validity
247    - Hook compliance
248    - Documentation links
249
250    Returns:
251        dict: Health check results
252    """
253    # Run all checks in parallel
254    git_task = async_get_current_branch()
255    worktrees_task = async_check_all_worktrees()
256    config_task = async_load_agents_config()
257    hooks_task = async_validate_all_hooks()
258
259    branch, worktrees, config, hook_results = await asyncio.gather(
260        git_task, worktrees_task, config_task, hooks_task,
261        return_exceptions=True  # Don't fail if one check fails
262    )
263
264    return {
265        "git": {
266            "branch": branch if not isinstance(branch, Exception) else str(branch),
267            "worktrees": worktrees if not isinstance(worktrees, Exception) else {},
268        },
269        "config": {
270            "loaded": not isinstance(config, Exception),
271            "agents_count": len(config.get("known_agents", [])) if not isinstance(config, Exception) else 0,
272        },
273        "hooks": {
274            "total": len(hook_results) if not isinstance(hook_results, Exception) else 0,
275            "compliant": sum(1 for r in hook_results if r.is_compliant) if not isinstance(hook_results, Exception) else 0,
276        }
277    }
278
279# ===== Sync Wrappers for Async Functions =====
280
281def parallel_validate_hooks(hooks_dir: Optional[str] = None) -> list[ValidationResult]:
282    """
283    Synchronous API that uses async parallelization internally.
284
285    Use this when you want parallelization but are in sync context.
286    """
287    return asyncio.run(async_validate_all_hooks(hooks_dir))
288
289def parallel_check_worktrees() -> dict[str, dict]:
290    """
291    Synchronous API for parallel worktree checking.
292    """
293    return asyncio.run(async_check_all_worktrees())
294
295def project_health_check() -> dict:
296    """
297    Synchronous API for comprehensive health check.
298    """
299    return asyncio.run(async_project_health_check())
300
301# ===== Demo =====
302
303async def demo():
304    """Demonstrate the sync/async bridge capabilities"""
305    import time
306
307    print("=" * 60)
308    print("Sync/Async Bridge Demo")
309    print("=" * 60)
310
311    # 1. Basic async wrapper usage
312    print("\n1. Basic async wrapper:")
313    branch = await async_get_current_branch()
314    print(f"   Current branch: {branch}")
315
316    # 2. Parallel execution comparison
317    print("\n2. Parallel vs Sequential comparison:")
318
319    # Sequential (simulated)
320    start = time.perf_counter()
321    worktrees = await async_get_worktree_list()
322    seq_time = 0
323    for wt in worktrees:
324        _ = await async_run_git_command(["status", "-s"], cwd=wt["path"])
325        seq_time += time.perf_counter() - start
326        start = time.perf_counter()
327    print(f"   Sequential check: {seq_time:.3f}s")
328
329    # Parallel
330    start = time.perf_counter()
331    results = await async_check_all_worktrees()
332    par_time = time.perf_counter() - start
333    print(f"   Parallel check: {par_time:.3f}s")
334    print(f"   Speedup: {seq_time/par_time:.1f}x")
335
336    # 3. Project health check
337    print("\n3. Project health check (parallel):")
338    start = time.perf_counter()
339    health = await async_project_health_check()
340    elapsed = time.perf_counter() - start
341
342    print(f"   Branch: {health['git']['branch']}")
343    print(f"   Worktrees: {len(health['git']['worktrees'])}")
344    print(f"   Hooks compliant: {health['hooks']['compliant']}/{health['hooks']['total']}")
345    print(f"   Time: {elapsed:.3f}s")
346
347    print("\n" + "=" * 60)
348
349if __name__ == "__main__":
350    asyncio.run(demo())

使用範例

在 FastAPI 中使用同步函式

 1from fastapi import FastAPI, HTTPException
 2from lib_async import (
 3    async_get_current_branch,
 4    async_get_worktree_list,
 5    async_check_all_worktrees,
 6    async_validate_all_hooks,
 7    async_project_health_check,
 8)
 9
10app = FastAPI()
11
12@app.get("/git/branch")
13async def get_branch():
14    """
15    Get current git branch.
16
17    Uses async wrapper to prevent blocking the event loop.
18    """
19    branch = await async_get_current_branch()
20    if branch is None:
21        raise HTTPException(status_code=500, detail="Not a git repository")
22    return {"branch": branch}
23
24@app.get("/git/worktrees")
25async def get_worktrees():
26    """
27    Get all worktrees with their status.
28
29    Checks all worktrees in parallel for fast response.
30    """
31    worktrees = await async_check_all_worktrees()
32    return {"worktrees": worktrees}
33
34@app.get("/health")
35async def health_check():
36    """
37    Comprehensive project health check.
38
39    Runs multiple checks in parallel:
40    - Git status
41    - Configuration
42    - Hook compliance
43    """
44    health = await async_project_health_check()
45    return health
46
47@app.get("/hooks/validate")
48async def validate_hooks():
49    """
50    Validate all hooks in parallel.
51
52    Much faster than sequential validation for many hooks.
53    """
54    results = await async_validate_all_hooks()
55
56    return {
57        "total": len(results),
58        "compliant": sum(1 for r in results if r.is_compliant),
59        "issues": [
60            {
61                "hook": r.hook_path,
62                "issues": [
63                    {"level": i.level, "message": i.message}
64                    for i in r.issues
65                ]
66            }
67            for r in results
68            if not r.is_compliant
69        ]
70    }

在同步腳本中使用非同步函式

 1#!/usr/bin/env python3
 2"""
 3Synchronous script that leverages async parallelization internally.
 4"""
 5
 6from lib_async import (
 7    parallel_validate_hooks,
 8    parallel_check_worktrees,
 9    project_health_check,
10)
11
12def main():
13    print("Project Health Report")
14    print("=" * 50)
15
16    # These functions use asyncio internally for parallelization
17    # but provide a synchronous API
18
19    # 1. Check all worktrees in parallel
20    print("\n1. Worktree Status:")
21    worktrees = parallel_check_worktrees()
22    for path, info in worktrees.items():
23        status = "clean" if info["is_clean"] else "dirty"
24        print(f"   [{info['branch']}] {path}: {status}")
25
26    # 2. Validate all hooks in parallel
27    print("\n2. Hook Validation:")
28    results = parallel_validate_hooks()
29    compliant = sum(1 for r in results if r.is_compliant)
30    print(f"   Compliant: {compliant}/{len(results)}")
31
32    for result in results:
33        if not result.is_compliant:
34            print(f"   - {result.hook_path}:")
35            for issue in result.issues:
36                print(f"     [{issue.level}] {issue.message}")
37
38    # 3. Comprehensive health check
39    print("\n3. Overall Health:")
40    health = project_health_check()
41    print(f"   Git branch: {health['git']['branch']}")
42    print(f"   Config loaded: {health['config']['loaded']}")
43    print(f"   Hooks OK: {health['hooks']['compliant']}/{health['hooks']['total']}")
44
45if __name__ == "__main__":
46    main()

Python 3.9+ 使用 asyncio.to_thread

Python 3.9 引入了 asyncio.to_thread，提供更簡潔的語法：

 1import asyncio
 2from lib.git_utils import get_current_branch, run_git_command
 3from lib.config_loader import load_config
 4
 5# Python 3.9+ simplified syntax
 6async def async_get_current_branch_39() -> Optional[str]:
 7    """Using asyncio.to_thread (Python 3.9+)"""
 8    return await asyncio.to_thread(get_current_branch)
 9
10async def async_load_config_39(config_name: str) -> dict:
11    """Using asyncio.to_thread (Python 3.9+)"""
12    return await asyncio.to_thread(load_config, config_name)
13
14async def async_run_git_command_39(
15    args: list[str],
16    cwd: Optional[str] = None
17) -> tuple[bool, str]:
18    """Using asyncio.to_thread with keyword arguments"""
19    # to_thread supports kwargs directly in Python 3.9+
20    return await asyncio.to_thread(run_git_command, args, cwd)
21
22# Comparison: run_in_executor vs to_thread
23async def comparison_demo():
24    """
25    asyncio.to_thread vs run_in_executor
26
27    to_thread advantages:
28    - Simpler syntax
29    - Better default executor management
30    - Direct kwargs support
31
32    run_in_executor advantages:
33    - Works on Python 3.7+
34    - Can use custom executors
35    - More control over thread pool
36    """
37    # run_in_executor (Python 3.7+)
38    loop = asyncio.get_running_loop()
39    result1 = await loop.run_in_executor(None, get_current_branch)
40
41    # to_thread (Python 3.9+)
42    result2 = await asyncio.to_thread(get_current_branch)
43
44    assert result1 == result2

設計權衡

面向	run_in_executor	asyncio.run	asyncio.to_thread
方向	同步 -> 非同步	非同步 -> 同步	同步 -> 非同步
執行緒	使用執行緒池	建立新事件迴圈	使用預設執行緒池
適用場景	非同步環境呼叫同步 I/O	同步入口點執行非同步	非同步環境呼叫同步 I/O
限制	需要事件迴圈存在	不能巢狀呼叫	需要 Python 3.9+
效能	高（可重用執行緒）	中（建立新迴圈開銷）	高（優化的執行緒池）
複雜度	中	低	低

ThreadPoolExecutor vs ProcessPoolExecutor

面向	ThreadPoolExecutor	ProcessPoolExecutor
適用場景	I/O 密集操作	CPU 密集操作
記憶體	共享記憶體	獨立記憶體空間
GIL	受 GIL 限制	繞過 GIL
啟動成本	低	高（進程建立）
資料傳遞	直接傳遞	需要序列化

 1from concurrent.futures import ThreadPoolExecutor, ProcessPoolExecutor
 2
 3# I/O-bound: use ThreadPoolExecutor
 4io_executor = ThreadPoolExecutor(max_workers=10)
 5
 6# CPU-bound: use ProcessPoolExecutor
 7cpu_executor = ProcessPoolExecutor(max_workers=4)
 8
 9async def io_bound_task():
10    """File I/O, network calls, subprocess"""
11    loop = asyncio.get_running_loop()
12    return await loop.run_in_executor(io_executor, sync_io_function)
13
14async def cpu_bound_task():
15    """Heavy computation"""
16    loop = asyncio.get_running_loop()
17    return await loop.run_in_executor(cpu_executor, sync_cpu_function)

什麼時候該用這個技術？

適合使用

漸進式遷移到 asyncio：有大量同步程式碼，需要逐步遷移
在 FastAPI 中使用同步第三方庫：如 requests、boto3、資料庫驅動
提供同步/非同步雙 API：讓使用者選擇適合的模式
並行化現有同步操作：如批次檔案處理、多 API 呼叫
整合傳統程式碼：舊系統的同步函式需要在新非同步系統中使用

不建議使用

全新專案：直接用原生 asyncio 設計
CPU 密集操作：應用 multiprocessing 或 ProcessPoolExecutor
簡單的單一操作：不需要並行的情況
效能極度敏感：執行緒池有微小開銷
已有原生非同步替代方案：如用 aiohttp 替代 requests

練習

基礎練習

用 run_in_executor 包裝 requests.get

 1import requests
 2import asyncio
 3
 4# TODO: Implement this function
 5async def async_fetch(url: str) -> str:
 6    """
 7    Fetch URL content asynchronously using requests library.
 8
 9    Hint: Use run_in_executor to wrap requests.get
10    """
11    pass
12
13# Test your implementation
14async def test():
15    content = await async_fetch("https://httpbin.org/get")
16    print(content[:200])
17
18asyncio.run(test())

參考解答

1.3 設計模式與最佳實踐

Tue, 20 Jan 2026 00:00:00 +0000

本章介紹 asyncio 的常見設計模式，以及如何避免常見陷阱。

先備知識

1.2 協程與 Task 管理

本章目標

學完本章後，你將能夠：

使用異步上下文管理器管理資源
實作異步迭代器處理串流資料
使用 Semaphore 控制並發
避免阻塞事件迴圈的陷阱

【原理層】異步協議

異步上下文管理器

同步版本使用 __enter__ 和 __exit__，異步版本使用 __aenter__ 和 __aexit__：

 1class AsyncResource:
 2 async def __aenter__(self):
 3 print("獲取資源")
 4 await self.connect()
 5 return self
 6
 7 async def __aexit__(self, exc_type, exc_val, exc_tb):
 8 print("釋放資源")
 9 await self.disconnect()
10
11 async def connect(self):
12 await asyncio.sleep(0.1)
13
14 async def disconnect(self):
15 await asyncio.sleep(0.1)
16
17async def main():
18 async with AsyncResource() as resource:
19 print("使用資源")

異步迭代器

同步版本使用 __iter__ 和 __next__，異步版本使用 __aiter__ 和 __anext__：

 1class AsyncCounter:
 2 def __init__(self, stop):
 3 self.current = 0
 4 self.stop = stop
 5
 6 def __aiter__(self):
 7 return self
 8
 9 async def __anext__(self):
10 if self.current >= self.stop:
11 raise StopAsyncIteration
12 await asyncio.sleep(0.1) # 模擬異步操作
13 self.current += 1
14 return self.current
15
16async def main():
17 async for num in AsyncCounter(5):
18 print(num)

異步生成器

更簡潔的異步迭代器寫法：

1async def async_range(stop):
2 for i in range(stop):
3 await asyncio.sleep(0.1)
4 yield i
5
6async def main():
7 async for num in async_range(5):
8 print(num)

【設計層】常見模式

協程鏈（Chaining）

 1async def fetch(url):
 2 async with aiohttp.ClientSession() as session:
 3 async with session.get(url) as response:
 4 return await response.text()
 5
 6async def parse(html):
 7 # 假設這是 CPU 密集操作，應該放到執行緒池
 8 await asyncio.sleep(0) # 讓出控制權
 9 return html[:100]
10
11async def process(data):
12 await asyncio.sleep(0.1)
13 return f"處理完成：{data}"
14
15async def pipeline(url):
16 html = await fetch(url)
17 parsed = await parse(html)
18 result = await process(parsed)
19 return result

Semaphore 並發控制

限制同時執行的任務數量：

 1async def fetch_with_limit(sem, url):
 2 async with sem: # 獲取信號量
 3 return await fetch(url)
 4
 5async def main():
 6 sem = asyncio.Semaphore(10) # 最多 10 個並發
 7 urls = [f"https://example.com/{i}" for i in range(100)]
 8
 9 tasks = [fetch_with_limit(sem, url) for url in urls]
10 results = await asyncio.gather(*tasks)

生產者-消費者

 1async def producer(queue):
 2 for i in range(10):
 3 await asyncio.sleep(0.1)
 4 await queue.put(i)
 5 print(f"生產：{i}")
 6 await queue.put(None) # 結束信號
 7
 8async def consumer(queue):
 9 while True:
10 item = await queue.get()
11 if item is None:
12 break
13 await asyncio.sleep(0.2)
14 print(f"消費：{item}")
15
16async def main():
17 queue = asyncio.Queue(maxsize=5)
18 await asyncio.gather(
19 producer(queue),
20 consumer(queue)
21 )

【實作層】實用範例

異步 Rate Limiter

 1class RateLimiter:
 2 def __init__(self, rate, per):
 3 self.rate = rate
 4 self.per = per
 5 self.allowance = rate
 6 self.last_check = asyncio.get_event_loop().time()
 7
 8 async def acquire(self):
 9 current = asyncio.get_event_loop().time()
10 elapsed = current - self.last_check
11 self.last_check = current
12 self.allowance += elapsed * (self.rate / self.per)
13
14 if self.allowance > self.rate:
15 self.allowance = self.rate
16
17 if self.allowance < 1.0:
18 wait_time = (1.0 - self.allowance) * (self.per / self.rate)
19 await asyncio.sleep(wait_time)
20 self.allowance = 0
21 else:
22 self.allowance -= 1.0

重試模式

1async def retry(coro_func, max_retries=3, delay=1.0):
2 for attempt in range(max_retries):
3 try:
4 return await coro_func()
5 except Exception as e:
6 if attempt == max_retries - 1:
7 raise
8 print(f"重試 {attempt + 1}/{max_retries}")
9 await asyncio.sleep(delay * (attempt + 1))

【陷阱與避免】

阻塞事件迴圈

 1import time
 2
 3async def bad_example():
 4 time.sleep(1) # 阻塞！整個事件迴圈停止
 5
 6async def good_example():
 7 await asyncio.sleep(1) # 非阻塞
 8
 9# 如果必須執行同步阻塞函式
10async def run_blocking():
11 loop = asyncio.get_running_loop()
12 await loop.run_in_executor(None, time.sleep, 1)

資源洩漏

 1# 錯誤：沒有正確關閉
 2async def bad():
 3 session = aiohttp.ClientSession()
 4 response = await session.get("https://example.com")
 5 return await response.text()
 6
 7# 正確：使用 async with
 8async def good():
 9 async with aiohttp.ClientSession() as session:
10 async with session.get("https://example.com") as response:
11 return await response.text()

思考題

為什麼 Semaphore 在 asyncio 中不需要擔心執行緒安全？
異步生成器在什麼場景下比異步迭代器更適合？
如何檢測程式碼是否阻塞了事件迴圈？

實作練習

實作一個異步連線池
實作一個帶有指數退避的重試裝飾器
實作一個異步的 debounce 函式

延伸閱讀

上一章：協程與 Task 管理 下一章：實戰：與同步程式碼整合

1.4 實戰：與同步程式碼整合

Tue, 20 Jan 2026 00:00:00 +0000

本章討論如何在現有專案中引入 asyncio，以及同步與異步程式碼的整合策略。

先備知識

1.3 設計模式與最佳實踐

本章目標

學完本章後，你將能夠：

在異步程式中呼叫同步函式
在同步程式中呼叫異步函式
制定漸進式遷移策略
與常見框架整合

【原理層】混合程式設計的挑戰

兩個世界的衝突

同步和異步程式碼有根本性的差異：

 1# 同步世界
 2def sync_fetch(url):
 3 response = requests.get(url) # 阻塞等待
 4 return response.text
 5
 6# 異步世界
 7async def async_fetch(url):
 8 async with aiohttp.ClientSession() as session:
 9 async with session.get(url) as response:
10 return await response.text() # 非阻塞等待

問題在於：

在異步函式中呼叫同步函式會阻塞事件迴圈
在同步函式中無法直接 await 異步函式

run_in_executor：橋樑

run_in_executor 在執行緒池中執行同步函式：

 1import asyncio
 2from concurrent.futures import ThreadPoolExecutor
 3
 4async def main():
 5 loop = asyncio.get_running_loop()
 6
 7 # 使用預設執行緒池
 8 result = await loop.run_in_executor(None, sync_blocking_func)
 9
10 # 使用自訂執行緒池
11 with ThreadPoolExecutor(max_workers=4) as pool:
12 result = await loop.run_in_executor(pool, sync_blocking_func)

【設計層】整合策略

在異步程式中呼叫同步函式

 1import asyncio
 2import requests
 3
 4def sync_fetch(url):
 5 return requests.get(url).text
 6
 7async def async_wrapper(url):
 8 loop = asyncio.get_running_loop()
 9 return await loop.run_in_executor(None, sync_fetch, url)
10
11async def main():
12 # 並發呼叫同步函式
13 urls = ["https://example.com"] * 5
14 tasks = [async_wrapper(url) for url in urls]
15 results = await asyncio.gather(*tasks)

在同步程式中呼叫異步函式

 1import asyncio
 2
 3async def async_fetch(url):
 4 async with aiohttp.ClientSession() as session:
 5 async with session.get(url) as response:
 6 return await response.text()
 7
 8def sync_main():
 9 # 方法 1：asyncio.run()
10 result = asyncio.run(async_fetch("https://example.com"))
11
12 # 方法 2：在已有事件迴圈中（例如 Jupyter）
13 loop = asyncio.get_event_loop()
14 result = loop.run_until_complete(async_fetch("https://example.com"))

漸進式遷移策略

 1階段 1：識別 I/O 瓶頸
 2 └─→ profiling，找出最常等待的地方
 3
 4階段 2：引入異步版本
 5 └─→ 新功能用異步，舊功能保持同步
 6
 7階段 3：包裝同步程式碼
 8 └─→ 用 run_in_executor 包裝同步函式
 9
10階段 4：逐步替換
11 └─→ 用異步函式庫替換同步函式庫
12
13階段 5：完全異步（可選）
14 └─→ 整個應用改為異步

【實作層】框架整合

FastAPI / Starlette

FastAPI 原生支援異步：

 1from fastapi import FastAPI
 2import asyncio
 3
 4app = FastAPI()
 5
 6@app.get("/async")
 7async def async_endpoint():
 8 await asyncio.sleep(1)
 9 return {"message": "異步完成"}
10
11@app.get("/sync")
12def sync_endpoint():
13 # FastAPI 會自動在執行緒池中執行
14 time.sleep(1)
15 return {"message": "同步完成"}

aiohttp 客戶端

 1import aiohttp
 2import asyncio
 3
 4async def fetch_all(urls):
 5 async with aiohttp.ClientSession() as session:
 6 async def fetch(url):
 7 async with session.get(url) as response:
 8 return await response.json()
 9
10 return await asyncio.gather(*[fetch(url) for url in urls])

SQLAlchemy 2.0

 1from sqlalchemy.ext.asyncio import create_async_engine, AsyncSession
 2from sqlalchemy.orm import sessionmaker
 3
 4engine = create_async_engine("postgresql+asyncpg://...")
 5async_session = sessionmaker(engine, class_=AsyncSession)
 6
 7async def get_user(user_id):
 8 async with async_session() as session:
 9 result = await session.execute(
10 select(User).where(User.id == user_id)
11 )
12 return result.scalar_one_or_none()

【測試策略】

測試異步程式碼

 1import pytest
 2import asyncio
 3
 4# pytest-asyncio
 5@pytest.mark.asyncio
 6async def test_async_function():
 7 result = await async_fetch("https://example.com")
 8 assert result is not None
 9
10# 使用 asyncio.run
11def test_with_asyncio_run():
12 result = asyncio.run(async_fetch("https://example.com"))
13 assert result is not None

Mock 異步函式

1from unittest.mock import AsyncMock, patch
2
3@pytest.mark.asyncio
4async def test_with_mock():
5 mock_fetch = AsyncMock(return_value="mocked data")
6
7 with patch("module.async_fetch", mock_fetch):
8 result = await process_data()
9 assert result == "processed: mocked data"

思考題

為什麼 FastAPI 可以同時支援同步和異步端點？
run_in_executor 使用執行緒池，會不會有 GIL 的問題？
在什麼情況下不值得遷移到 asyncio？

實作練習

將一個使用 requests 的爬蟲改寫為使用 aiohttp
實作一個支援同步和異步呼叫的函式庫包裝器
為異步程式碼撰寫單元測試

延伸閱讀

上一章：設計模式與最佳實踐 下一模組：模組二：元編程

案例研究：非同步程式設計實戰

Wed, 21 Jan 2026 00:00:00 +0000

本系列案例基於 .claude/lib 的實際程式碼，展示如何用 asyncio 解決實際問題。

案例列表

案例	素材	進階技術	難度
非同步 subprocess	git_utils.py	asyncio.create_subprocess_exec	中階
並行 I/O 操作	git_utils.py	asyncio.gather, TaskGroup	中階
同步/非同步橋接	整個 lib	run_in_executor	高階

學習路徑

1非同步 subprocess（入門）
2 ↓
3並行 I/O 操作（基礎）
4 ↓
5同步/非同步橋接（整合）

先備知識

建議先完成以下章節：

返回：模組一：非同步程式設計

從 threading 到 asyncio：轉換指南

Wed, 21 Jan 2026 00:00:00 +0000

如果你已經熟悉入門系列的 threading 模組，本章將幫助你理解為什麼需要 asyncio，以及如何將現有的多執行緒程式碼轉換為異步版本。

為什麼要從 threading 轉向 asyncio？

threading 的限制

threading 是處理並發的傳統方案，但它有幾個固有限制：

1. 資源消耗高

每個執行緒都需要分配記憶體（預設約 8MB stack）：

1import threading
2
3# 建立 100 個執行緒
4threads = [threading.Thread(target=some_task) for _ in range(100)]
5# 記憶體消耗：約 800MB 的 stack 空間

當需要處理數千個並發連線時，執行緒模型會面臨資源瓶頸。

2. 上下文切換成本

作業系統需要在執行緒之間切換，這涉及：

保存和恢復 CPU 暫存器
切換記憶體映射
快取失效

1執行緒 1 執行 → 上下文切換（耗時）→ 執行緒 2 執行 → 上下文切換（耗時）→ ...

3. GIL 的限制

由於 GIL，多個執行緒無法真正並行執行 Python 程式碼：

1# 這段程式碼實際上是序列執行的
2def cpu_task():
3    total = 0
4    for i in range(1000000):
5        total += i
6    return total
7
8# 即使使用多執行緒，也無法利用多核 CPU
9threads = [threading.Thread(target=cpu_task) for _ in range(4)]

asyncio 的優勢

asyncio 採用不同的並發模型來解決這些問題：

1. 輕量級協程

協程只是普通的 Python 物件，記憶體消耗極低：

1import asyncio
2
3# 建立 10000 個協程
4async def some_task():
5    await asyncio.sleep(1)
6
7# 記憶體消耗：幾十 KB
8tasks = [some_task() for _ in range(10000)]

2. 協作式切換

協程只在 await 點切換，沒有強制的上下文切換：

1協程 1 執行 → await（主動讓出）→ 協程 2 執行 → await（主動讓出）→ ...

3. 單執行緒高並發

asyncio 在單執行緒中處理所有任務，避免了執行緒同步問題：

1async def handle_request(client):
2    data = await client.read()    # 等待時處理其他請求
3    result = process(data)
4    await client.write(result)    # 等待時處理其他請求

並發模型比較

特性	threading	asyncio
執行模型	多執行緒並行	單執行緒協作
切換方式	作業系統搶佔	程式主動讓出
記憶體消耗	高（每執行緒 ~8MB）	低（每協程 ~KB）
並發數量	百級	萬級
GIL 影響	受限制	無影響（不需要多核）
同步複雜度	需要鎖（Lock、Semaphore）	較少（單執行緒）
適用場景	I/O 密集 + 共享記憶體	I/O 密集 + 大規模並發

程式碼轉換模式

模式 1：簡單函式轉換

threading 版本：

 1import time
 2import threading
 3
 4def fetch_data(url):
 5    time.sleep(1)  # 模擬網路延遲
 6    return f"Data from {url}"
 7
 8def main():
 9    urls = ["url1", "url2", "url3"]
10    threads = []
11    results = []
12
13    for url in urls:
14        t = threading.Thread(target=lambda u=url: results.append(fetch_data(u)))
15        threads.append(t)
16        t.start()
17
18    for t in threads:
19        t.join()
20
21    return results

asyncio 版本：

 1import asyncio
 2
 3async def fetch_data(url):
 4    await asyncio.sleep(1)  # 非阻塞等待
 5    return f"Data from {url}"
 6
 7async def main():
 8    urls = ["url1", "url2", "url3"]
 9
10    # 使用 gather 並發執行
11    results = await asyncio.gather(*[fetch_data(url) for url in urls])
12
13    return results
14
15# 執行
16asyncio.run(main())

轉換要點：

原本	轉換後
`def`	`async def`
`time.sleep()`	`await asyncio.sleep()`
`threading.Thread` + `join`	`asyncio.gather()`

模式 2：ThreadPoolExecutor 轉換

threading 版本：

1from concurrent.futures import ThreadPoolExecutor
2
3def process_file(filepath):
4    with open(filepath) as f:
5        return len(f.read())
6
7with ThreadPoolExecutor(max_workers=4) as executor:
8    results = list(executor.map(process_file, file_paths))

asyncio 版本（使用 aiofiles）：

 1import asyncio
 2import aiofiles
 3
 4async def process_file(filepath):
 5    async with aiofiles.open(filepath) as f:
 6        content = await f.read()
 7        return len(content)
 8
 9async def main():
10    tasks = [process_file(fp) for fp in file_paths]
11    results = await asyncio.gather(*tasks)
12    return results
13
14asyncio.run(main())

模式 3：保留同步程式碼（混合模式）

有時候你無法（或不想）將所有程式碼都轉為異步。asyncio 提供了 run_in_executor 來處理這種情況：

 1import asyncio
 2from concurrent.futures import ThreadPoolExecutor
 3
 4# 保持原有的同步函式
 5def blocking_operation(data):
 6    # 這是一個阻塞的第三方函式庫呼叫
 7    import time
 8    time.sleep(1)
 9    return f"Processed: {data}"
10
11async def main():
12    loop = asyncio.get_event_loop()
13
14    # 在執行緒池中執行同步函式
15    with ThreadPoolExecutor() as pool:
16        result = await loop.run_in_executor(
17            pool,
18            blocking_operation,
19            "my_data"
20        )
21
22    return result
23
24asyncio.run(main())

這種模式讓你可以漸進式地將程式碼遷移到 asyncio。

何時選擇哪種方案？

選擇 threading

需要與不支援 asyncio 的函式庫整合
需要共享記憶體且修改頻繁
並發數量較少（< 100）
團隊對 threading 更熟悉

選擇 asyncio

需要處理大量並發連線（Web 伺服器、聊天室）
主要是 I/O 操作（網路、檔案）
使用現代 async 函式庫（aiohttp、httpx、asyncpg）
需要高效能的單機並發

選擇 multiprocessing

CPU 密集任務（資料處理、科學計算）
需要真正的並行計算
各任務相對獨立，不需要頻繁通訊

決策流程圖

 1任務類型是什麼？
 2    │
 3    ├─ CPU 密集 ────────────────→ multiprocessing
 4    │
 5    └─ I/O 密集
 6        │
 7        ├─ 並發數 > 100 ─────────→ asyncio
 8        │
 9        ├─ 需要共享記憶體 ────────→ threading
10        │
11        └─ 第三方函式庫支援 async？
12            │
13            ├─ 是 ───────────────→ asyncio
14            │
15            └─ 否 ───────────────→ threading 或 asyncio + run_in_executor

常見轉換陷阱

陷阱 1：忘記 await

1# 錯誤：忘記 await
2async def main():
3    result = fetch_data("url")  # 這只會建立協程物件，不會執行
4    print(result)  # 
5
6# 正確
7async def main():
8    result = await fetch_data("url")
9    print(result)

陷阱 2：在異步函式中使用阻塞呼叫

1# 錯誤：使用阻塞的 time.sleep
2async def bad_sleep():
3    time.sleep(1)  # 這會阻塞整個事件迴圈！
4
5# 正確：使用非阻塞的 asyncio.sleep
6async def good_sleep():
7    await asyncio.sleep(1)  # 這會讓出控制權

陷阱 3：在同步函式中呼叫異步函式

1# 錯誤：在普通函式中直接呼叫
2def sync_function():
3    result = await fetch_data("url")  # SyntaxError!
4
5# 正確：使用 asyncio.run
6def sync_function():
7    result = asyncio.run(fetch_data("url"))

實戰練習

練習 1：轉換簡單的多執行緒下載器

將以下 threading 程式碼轉換為 asyncio 版本：

 1import threading
 2import time
 3
 4def download(url):
 5    print(f"Downloading {url}...")
 6    time.sleep(2)  # 模擬下載
 7    print(f"Finished {url}")
 8    return f"Content of {url}"
 9
10def main():
11    urls = ["url1", "url2", "url3", "url4"]
12    threads = []
13
14    for url in urls:
15        t = threading.Thread(target=download, args=(url,))
16        threads.append(t)
17        t.start()
18
19    for t in threads:
20        t.join()
21
22if __name__ == "__main__":
23    main()

練習 2：使用 run_in_executor 整合同步函式庫

假設你有一個只支援同步的第三方 API 客戶端，寫一個異步包裝器。

下一步

理解了 threading 和 asyncio 的區別後，你可以開始深入學習 asyncio 的核心概念：

1.1 基礎概念與事件迴圈 - 理解 asyncio 的運作原理
1.2 協程與 Task 管理 - 掌握 async/await 語法
1.4 實戰：與同步程式碼整合 - 學習混合模式的最佳實踐

上一章：入門系列 3.7 並行處理 下一章：1.1 基礎概念與事件迴圈