Python | Home

APScheduler（Advanced Python Scheduler）

Sat, 04 Nov 2023 00:00:00 +0000

Python 里的“定时任务 / 调度框架”，类似 Java 生态里的 Quartz。

如果你后面学习 FastAPI + AI Agent + 微服务，APScheduler 很有价值，例如：

每天凌晨同步数据
每5分钟检查任务状态
定期清理 Redis
定时调用第三方 API
定期生成报表
定时执行 RAG 数据同步
定期刷新缓存

不过需要特别注意：APScheduler 是任务调度器，不是消息队列，也不是分布式任务系统。

一、APScheduler 主要有哪些功能？

核心功能可以概括成：

APScheduler
 │
 ├── Scheduler 调度器
 │
 ├── Trigger 触发器
 │
 ├── Job 任务
 │
 ├── Executor 执行器
 │
 ├── Job Store 持久化
 │
 ├── Interval 定时
 │
 ├── Cron 定时
 │
 ├── Date 一次性任务
 │
 ├── AsyncIO
 │
 ├── Pause / Resume
 │
 ├── Job 管理
 │
 └── Misfire / Coalescing / Max Instances

你真正需要掌握的是前面几个核心概念。

二、APScheduler 的整体架构

先记住这一张图：

 APScheduler
 │
 ┌───────┴───────┐
 │ Scheduler │
 └───────┬───────┘
 │
 Trigger
 │
 ┌──────────┼──────────┐
 ↓ ↓ ↓
 Date Interval Cron
 │ │ │
 └──────────┼──────────┘
 ↓
 Job
 │
 ↓
 Executor
 │
 ┌─────────┼─────────┐
 ↓ ↓ ↓
 AsyncIO Thread Process

如果你把这个模型搞懂，APScheduler 基本就入门了。

三、Scheduler：调度器

Scheduler 是 APScheduler 的核心。

它负责：

什么时候执行？
执行哪个 Job？
Job 是否应该执行？
执行多少次？
错过了怎么办？
是否允许并发执行？

例如：

from apscheduler.schedulers.asyncio import AsyncIOScheduler

scheduler = AsyncIOScheduler()

scheduler.start()

在 FastAPI 中非常常见：

FastAPI
 │
 └── AsyncIOScheduler
 │
 ├── Job A
 ├── Job B
 └── Job C

四、Trigger：什么时候执行？

Trigger 是 APScheduler 最核心的概念之一。

主要有三个：

Date
Interval
Cron

五、Date Trigger：一次性任务

例如：

2026-08-20 10:00 执行一次。

scheduler.add_job(
 my_job,
 "date",
 run_date="2026-08-20 10:00:00"
)

执行一次：

10:00
 ↓
Job
 ↓
执行
 ↓
结束

适合：

延迟任务
一次性任务
定时提醒
预约任务

六、Interval Trigger：固定间隔

例如：

每 10 秒执行一次。

scheduler.add_job(
 my_job,
 "interval",
 seconds=10
)

执行：

10:00:00
10:00:10
10:00:20
10:00:30
...

也可以：

scheduler.add_job(
 my_job,
 "interval",
 minutes=5
)

或者：

scheduler.add_job(
 my_job,
 "interval",
 hours=1
)

适合：

定期检查
缓存刷新
健康检查
数据同步
轮询第三方 API

七、Cron Trigger：最重要

如果你做后台系统，Cron 是必须掌握的。

例如：

每天凌晨 2 点执行。

scheduler.add_job(
 my_job,
 "cron",
 hour=2,
 minute=0
)

每天：

02:00
 ↓
Job

每天 10:30

scheduler.add_job(
 my_job,
 "cron",
 hour=10,
 minute=30
)

每周一 9 点

scheduler.add_job(
 my_job,
 "cron",
 day_of_week="mon",
 hour=9
)

工作日执行

scheduler.add_job(
 my_job,
 "cron",
 day_of_week="mon-fri",
 hour=9
)

每个月 1 号

scheduler.add_job(
 my_job,
 "cron",
 day=1,
 hour=0,
 minute=0
)

八、Job：真正执行的任务

例如：

async def clean_cache():
 print("Cleaning cache...")

然后：

scheduler.add_job(
 clean_cache,
 "interval",
 minutes=10
)

这里：

clean_cache
 ↓
Job
 ↓
Scheduler
 ↓
每10分钟执行

九、Job ID

实际项目中一定要给 Job 设置 ID。

scheduler.add_job(
 clean_cache,
 "interval",
 minutes=10,
 id="clean_cache_job"
)

之后可以：

scheduler.get_job("clean_cache_job")

删除：

scheduler.remove_job("clean_cache_job")

暂停：

scheduler.pause_job("clean_cache_job")

恢复：

scheduler.resume_job("clean_cache_job")

所以 Job ID 很重要。

十、Job 参数

可以传参数：

def send_email(user_id):
 print(user_id)

scheduler.add_job(
 send_email,
 "date",
 run_date=...,
 args=[100]
)

或者：

scheduler.add_job(
 send_email,
 "date",
 run_date=...,
 kwargs={
 "user_id": 100
 }
)

十一、AsyncIO Scheduler

如果你使用 FastAPI：

优先理解 AsyncIOScheduler。

例如：

from apscheduler.schedulers.asyncio import AsyncIOScheduler

scheduler = AsyncIOScheduler()

任务：

async def sync_data():
 await fetch_data()

然后：

scheduler.add_job(
 sync_data,
 "interval",
 minutes=5
)

形成：

FastAPI
 │
 ↓
Event Loop
 │
 ├── HTTP Request
 ├── WebSocket
 ├── Async DB
 └── APScheduler
 │
 ├── Job A
 ├── Job B
 └── Job C

这也是为什么你刚才学习 asyncio 后，接着学习 APScheduler 是很合理的。

十二、Executor：任务到底在哪里执行？

APScheduler 可以通过 Executor 执行任务。

常见概念：

AsyncIO
ThreadPool
ProcessPool

例如：

AsyncIO
 ↓
异步任务

ThreadPool
 ↓
线程执行

ProcessPool
 ↓
进程执行

对于 FastAPI：

异步 I/O
 ↓
AsyncIO

同步阻塞代码
 ↓
ThreadPool

这个概念需要掌握，但一般不需要深入实现 Executor。

十三、Job Store：任务是否持久化？

这是 APScheduler 比简单 while + sleep 强大的地方之一。

Job Store 可以保存 Job。

例如：

Memory
SQLAlchemy
Redis 等

你可以理解：

Scheduler
 │
 ↓
Job Store
 │
 ├── Job A
 ├── Job B
 └── Job C

如果只是：

scheduler.add_job(...)

通常 Job 是内存中的。

程序重启：

Process Stop
 ↓
Memory Job
 ↓
消失

如果使用持久化 Job Store：

Process Stop
 ↓
Database
 ↓
Process Restart
 ↓
恢复 Job

十四、Misfire：错过执行时间怎么办？

这是生产环境必须理解的概念。

例如：

Job 应该 02:00 执行
 ↓
服务器 01:59 崩溃
 ↓
服务器 02:10 恢复

那么：

02:00 的 Job 要不要补执行？

这就是 Misfire。

十五、Coalescing：多次错过是否合并？

这个概念非常重要。

例如：

Job 每分钟执行一次

02:00
02:01
02:02
02:03

服务器挂了 10 分钟。

恢复后可能出现：

02:00 Job
02:01 Job
02:02 Job
02:03 Job
...

如果这些任务没有必要一个一个补执行，可以使用：

coalesce=True

让多个错过的执行合并成一次。

简单理解：

coalesce=False

missed
 ↓
Job
Job
Job
Job
Job


coalesce=True

missed
 ↓
Job

十六、max_instances：防止 Job 重叠

这是生产环境非常重要的知识。

假设：

Job 每 1 分钟执行

但一次 Job 需要：

5 分钟

那么：

10:00 → Job A
10:01 → Job B
10:02 → Job C
10:03 → Job D

可能导致大量任务并发。

所以需要限制：

max_instances=1

意思：

同一个 Job 同时最多运行一个实例。

这和你之前学习的并发控制非常相关。

十七、暂停和恢复

APScheduler 支持：

scheduler.pause()

恢复：

scheduler.resume()

也可以针对 Job：

scheduler.pause_job("my_job")

以及：

scheduler.resume_job("my_job")

适合：

系统维护
流量高峰
临时停止任务
手工运维

十八、监听 Job Event

APScheduler 可以监听事件。

例如：

Job 开始
Job 完成
Job 失败
Job 错过
Job 被提交

可以做：

Job
 ↓
Event Listener
 ↓
Logging
 ↓
Monitoring
 ↓
Alert

例如生产环境你可能希望：

Job失败
 ↓
日志
 ↓
Prometheus
 ↓
Grafana
 ↓
告警

这个对于你熟悉的 Observability / OpenTelemetry 方向也很有价值。

十九、Timezone

定时任务非常容易踩坑。

例如：

scheduler.add_job(
 my_job,
 "cron",
 hour=9
)

问题来了：

9 点是哪个时区？

生产系统尤其需要考虑：

UTC
America/Los_Angeles
Asia/Shanghai
Europe/London

所以需要理解：

timezone

尤其如果你的 FastAPI 部署在 Kubernetes / Cloud 上，服务器很可能使用 UTC。

二十、APScheduler 和 asyncio 的关系

这个关系你现在尤其需要理解：

 FastAPI
 │
 ↓
 Event Loop
 │
 ┌─────────┴─────────┐
 ↓ ↓
 HTTP Request APScheduler
 │
 ↓
 Job
 │
 ┌───────┴───────┐
 ↓ ↓
 async I/O Thread

所以：

asyncio 负责异步执行模型，APScheduler 负责“什么时候执行任务”。

非常简单地说：

asyncio
 ↓
怎么异步执行？

APScheduler
 ↓
什么时候执行？

二十一、APScheduler 和 Quartz 对比

你有 Java 背景，这个对照非常有用：

Java Quartz	APScheduler
Scheduler	Scheduler
Job	Job
Trigger	Trigger
CronTrigger	Cron Trigger
SimpleTrigger	Interval / Date
JobStore	Job Store
ThreadPool	Executor
Misfire	Misfire
JobDataMap	args / kwargs
JobListener	Event Listener

所以如果你学过 Quartz：

APScheduler 的思想基本不会陌生。

二十二、APScheduler 和 Celery 不一样

这个非常重要。

很多初学者容易把它们混在一起。

APScheduler

核心：

什么时候执行？

例如：

每天 2 点执行数据清理

Celery

核心：

把任务分发给 Worker 执行

例如：

FastAPI
 ↓
Redis/RabbitMQ
 ↓
Celery Worker
 ↓
Task

所以：

APScheduler
 = Scheduler

Celery
 = Distributed Task Queue

二十三、APScheduler 和 Kubernetes CronJob 也不同

生产环境还经常会遇到：

APScheduler
Celery
Kubernetes CronJob

它们的定位不同。

APScheduler
 ↓
应用内部调度

Celery
 ↓
分布式任务执行

Kubernetes CronJob
 ↓
容器级别定时任务

例如：

每天凌晨 2 点启动一个容器

更适合：

Kubernetes CronJob

而：

每 10 分钟调用一个 API

可以考虑：

APScheduler

二十四、必须掌握的核心知识

⭐⭐⭐⭐⭐ 必须掌握

1. Scheduler

2. Job

3. Trigger

4. Date Trigger

5. Interval Trigger

6. Cron Trigger

7. AsyncIOScheduler

8. add_job()

9. Job ID

10. remove_job()

11. pause_job()

12. resume_job()

⭐⭐⭐⭐ 生产环境必须理解

13. misfire_grace_time

14. coalesce

15. max_instances

16. timezone

17. Job Store

18. Executor

19. Job Event Listener

20. Job 异常处理

⭐⭐⭐ 理解即可

21. ThreadPoolExecutor

22. ProcessPoolExecutor

23. SQLAlchemy Job Store

24. 自定义 Trigger

25. 自定义 Executor

26. APScheduler 内部源码

二十五、5 个场景

场景 1：定时清理缓存

Every 10 minutes
 ↓
APScheduler
 ↓
Redis
 ↓
清理过期数据

场景 2：定时同步数据

Every 5 minutes
 ↓
APScheduler
 ↓
External API
 ↓
PostgreSQL

场景 3：每天生成报表

02:00
 ↓
APScheduler
 ↓
Query DB
 ↓
Generate Report
 ↓
Upload

场景 4：AI RAG 数据同步

Every 30 minutes
 ↓
APScheduler
 ↓
读取新的 PDF / Documents
 ↓
Chunk
 ↓
Embedding
 ↓
Vector DB

场景 5：AI Agent 定时任务

例如：

Every morning 8:00
 ↓
APScheduler
 ↓
Agent
 ↓
获取新闻
 ↓
LLM Summary
 ↓
Email / Notification

二十六、最值得掌握的一张图

把 APScheduler 和刚才的 asyncio 放在一起：

 FastAPI
 │
 ↓
 Event Loop
 │
 ┌───────┴────────┐
 │ │
 HTTP请求 APScheduler
 │
 Scheduler
 │
 ┌───────────┼───────────┐
 ↓ ↓ ↓
 Cron Interval Date
 │ │ │
 └───────────┼───────────┘
 ↓
 Job
 │
 ┌─────────┴─────────┐
 ↓ ↓
 async Job blocking Job
 │ │
 await ThreadPool
 │
 ↓
 Async I/O / DB / Redis

你只需要真正搞懂：

Scheduler → Trigger → Job → Executor → Event Loop

以及：

Cron / Interval / Date + async/await + misfire + coalesce + max_instances

APScheduler 的核心就基本掌握了。

asyncio 的核心知识

Sat, 04 Nov 2023 00:00:00 +0000

asyncio = Python 的异步 I/O 框架，核心解决“一个线程如何高效地同时处理大量 I/O 等待”。

一、asyncio 到底解决什么问题？

假设 FastAPI 同时收到 3 个请求：

Request A → 调用数据库 → 等待 100ms
Request B → 调用 Redis → 等待 50ms
Request C → 调用 HTTP API → 等待 200ms

传统同步代码：

A ────────等待────────>
 B ─────等待────>
 C ───────────等待────────>

总耗时可能接近：

100 + 50 + 200 = 350ms

异步：

A ──等待──┐
B ─等待───┼──→ Event Loop
C ───等待─┘

当 A 在等待数据库时，程序可以去处理 B。

所以：

asyncio
 ↓
Event Loop
 ↓
Task
 ↓
await
 ↓
非阻塞 I/O

这是理解 asyncio 最重要的一条主线。

二、asyncio 的核心知识地图

如果按照重要程度，我建议你这样划分：

★★★★★ 必须掌握

async / await
Coroutine
Event Loop
Task
Future
asyncio.gather()
asyncio.create_task()
同步 vs 异步
阻塞 vs 非阻塞
异步 I/O

★★★★ 强烈建议掌握

asyncio.Queue
asyncio.Lock
asyncio.Semaphore
asyncio.Event
asyncio.wait_for()
asyncio.timeout()
asyncio.wait()
asyncio.as_completed()

★★★ 工作中需要

asyncio.to_thread()
run_in_executor()
TaskGroup
异步上下文管理器
异步迭代器

★★ 了解即可

Protocol
Transport
低级 Event Loop API
自定义 Event Loop

三、第一必须掌握：async / await

这是 asyncio 的基础。

import asyncio

async def hello():
 print("Hello")

asyncio.run(hello())

这里：

async def

定义的是 Coroutine Function（协程函数）。

而：

hello()

返回的是：

Coroutine Object

四、await 是最重要的关键字

例如：

async def task():
 print("Start")

 await asyncio.sleep(2)

 print("End")

注意：

await asyncio.sleep(2)

不是：

当前线程睡眠 2 秒。

而是：

当前协程暂时挂起，把执行机会让给 Event Loop。

所以：

task A
 ↓
await
 ↓
Event Loop
 ↓
task B
 ↓
await
 ↓
task C

这就是异步并发。

五、第二必须掌握：Coroutine

这是 Java 开发者最容易混淆的地方。

async def foo():
 return 100

执行：

result = foo()

此时：

result ≠ 100

而是：

Coroutine Object

必须：

result = await foo()

才能得到：

所以：

async def
 ↓
Coroutine Function

foo()
 ↓
Coroutine Object

await foo()
 ↓
执行 Coroutine
 ↓
得到结果

这三个概念一定要分清。

六、第三必须掌握：Event Loop

这是 asyncio 的核心。

可以把 Event Loop 理解成：

负责调度所有异步任务的“调度器”。

例如：

 Event Loop
 │
 ┌───────────┼───────────┐
 ↓ ↓ ↓
 Task A Task B Task C
 │ │ │
 await await await
 │ │ │
 └───────────┼───────────┘
 ↓
 I/O Ready
 ↓
 继续执行

简单例子：

import asyncio

async def main():
 print("Hello")

asyncio.run(main())

这里：

asyncio.run(main())

实际上就是：

创建 Event Loop
 ↓
运行 main()
 ↓
处理异步任务
 ↓
关闭 Event Loop

七、第四必须掌握：Task

这是非常重要的。

Coroutine：

coro = foo()

并不代表它已经被并发调度。

如果：

task = asyncio.create_task(foo())

那么：

把 Coroutine 包装成 Task，并交给 Event Loop 调度。

例如：

async def task_a():
 await asyncio.sleep(2)
 return "A"

async def task_b():
 await asyncio.sleep(1)
 return "B"

同步执行：

await task_a()
await task_b()

大约：

2s + 1s = 3s

并发执行：

a = asyncio.create_task(task_a())
b = asyncio.create_task(task_b())

result_a = await a
result_b = await b

大约：

max(2s, 1s) = 2s

这就是 asyncio 的价值。

八、第五必须掌握：asyncio.gather()

实际项目里非常常用。

results = await asyncio.gather(
 task_a(),
 task_b(),
 task_c()
)

例如：

async def get_user():
 ...

async def get_orders():
 ...

async def get_products():
 ...

user, orders, products = await asyncio.gather(
 get_user(),
 get_orders(),
 get_products()
)

这相当于：

 FastAPI
 │
 ┌────────┼────────┐
 ↓ ↓ ↓
 User Orders Products
 │ │ │
 └────────┼────────┘
 ↓
 gather
 ↓
 Response

对于 FastAPI：

这是非常值得掌握的 API。

九、Task 和 gather 有什么区别？

这是面试经常问的问题。

create_task

task = asyncio.create_task(foo())

重点：

创建一个可以独立调度的 Task。

gather

await asyncio.gather(
 foo(),
 bar()
)

重点：

并发执行多个 awaitable，并收集结果。

可以理解：

create_task()
 ↓
创建任务

gather()
 ↓
批量并发 + 收集结果

十、Future 是什么？

这是必须理解，但不需要大量使用。

可以简单理解：

Future 是一个代表“未来某个时间会产生结果”的低层对象。

关系：

Coroutine
 ↓
Task
 ↓
Future
 ↓
最终结果

但在现代 Python 开发中：

业务代码很少直接操作 Future。

你需要知道它是什么，但不需要每天写：

asyncio.Future()

十一、阻塞和非阻塞必须彻底搞懂

这个对 FastAPI 特别重要。

例如：

import time

async def foo():
 time.sleep(5)

这是一个错误示范。

因为：

time.sleep(5)

是阻塞操作。

它会阻塞 Event Loop。

正确：

async def foo():
 await asyncio.sleep(5)

这样：

Event Loop
 │
 ├── Task A
 │ ↓
 │ await sleep
 │
 ├── Task B ← 继续执行
 │
 └── Task C ← 继续执行

所以你一定要理解：

async ≠ 自动异步

await ≠ 所有操作都非阻塞

真正关键的是：

await 的操作本身必须是异步/非阻塞的，或者正确地把阻塞工作移出 Event Loop。

十二、asyncio.sleep()

这是学习 asyncio 最简单的例子。

await asyncio.sleep(1)

它主要用于：

模拟 I/O
定时任务
重试
限速
测试异步代码

例如：

async def retry():
 for i in range(3):
 try:
 return await call_api()
 except Exception:
 await asyncio.sleep(1)

十三、asyncio.Queue

这个在微服务和后台任务中很重要。

queue = asyncio.Queue()

生产者：

await queue.put(data)

消费者：

data = await queue.get()

形成：

Producer
 ↓
┌──────────────┐
│ asyncio.Queue│
└──────────────┘
 ↓
Consumer

可以实现：

生产者 / 消费者
异步任务处理
任务缓冲
并发控制

十四、asyncio.Lock

如果多个 Coroutine 修改共享数据：

lock = asyncio.Lock()

使用：

async with lock:
 balance -= 100

类似 Java：

synchronized

或者：

Lock

但是注意：

asyncio.Lock 是给同一个 Event Loop 中的协程并发控制使用的，不是 Java ReentrantLock 的直接替代品。

十五、Semaphore

这个非常实用。

假设你最多允许：

同时 10 个 HTTP 请求

可以：

semaphore = asyncio.Semaphore(10)

然后：

async with semaphore:
 await call_api()

形成：

1000 requests
 ↓
 Semaphore(10)
 ↓
最多10个同时执行

这和你之前学习的 Rate Limiter / 并发控制非常相关。

十六、asyncio.Event

用于协程之间通知。

event = asyncio.Event()

等待：

await event.wait()

触发：

event.set()

例如：

Worker
 ↓
等待系统初始化
 ↓
Event.wait()
 ↓
初始化完成
 ↓
Event.set()
 ↓
Worker继续执行

十七、超时控制

实际生产环境非常重要。

例如：

await asyncio.wait_for(
 call_api(),
 timeout=3
)

意思：

3 秒还没完成，就超时。

现代 Python 也可以使用：

async with asyncio.timeout(3):
 await call_api()

这对于：

HTTP API
Database
Redis
LLM
Microservice

都非常重要。

十八、asyncio.to_thread()

这个对你特别重要。

假设你有一个同步阻塞函数：

def blocking_function():
 time.sleep(5)

如果直接：

await blocking_function()

是不行的。

可以：

result = await asyncio.to_thread(
 blocking_function
)

变成：

Event Loop
 │
 ├───────────────┐
 ↓ ↓
Async Task Thread
 ↓
 Blocking Task

这样不会直接堵住 Event Loop。

十九、asyncio.TaskGroup

Python 新版本中非常值得学习。

例如：

async with asyncio.TaskGroup() as tg:

 tg.create_task(task_a())

 tg.create_task(task_b())

 tg.create_task(task_c())

它提供结构化并发。

可以理解成：

TaskGroup
 │
 ├── Task A
 ├── Task B
 └── Task C

相比过去大量使用：

asyncio.create_task()

TaskGroup 对任务生命周期和异常处理更加规范。

二十、异步上下文管理器

你以后使用数据库、HTTP Client 时经常遇到：

async with ...

例如：

async with http_client as client:
 response = await client.get(url)

对应同步：

with ...

异步：

async with ...

这个在 FastAPI 项目中应该掌握。

二十一、异步 HTTP

真正开发 FastAPI 时，你会经常使用：

httpx
aiohttp

例如 HTTPX：

import httpx

async with httpx.AsyncClient() as client:

 response = await client.get(
 "https://example.com"
 )

这才是实际的：

FastAPI
 ↓
await
 ↓
Async HTTP Client
 ↓
External Service

二十二、asyncio 和多线程、多进程不要混淆

这是面试重点。

asyncio

主要解决：

I/O 并发

例如：

HTTP
DB
Redis
Kafka
文件
网络

Thread

适合：

阻塞 I/O
同步第三方库

Process

适合：

CPU 密集型任务

例如：

图像处理
大规模计算
机器学习计算
复杂算法

可以简单记：

 Python 并发
 │
 ┌─────────┼─────────┐
 ↓ ↓ ↓
 asyncio Thread Process
 │ │ │
 I/O I/O CPU

二十三、你必须掌握的知识分级

如果你的目标是：

FastAPI + AI Full-Stack + 微服务开发

我建议：

第一优先级 ⭐⭐⭐⭐⭐

一定掌握：

async / await
Coroutine
Event Loop
Task
create_task()
gather()
asyncio.run()
sleep()
阻塞 vs 非阻塞
同步 vs 异步

尤其是这张图：

async def
 ↓
Coroutine
 ↓
create_task()
 ↓
Task
 ↓
Event Loop
 ↓
await
 ↓
I/O
 ↓
Task Resume

第二优先级 ⭐⭐⭐⭐

工作中非常有用：

asyncio.Queue
asyncio.Lock
asyncio.Semaphore
asyncio.Event
asyncio.wait_for()
asyncio.timeout()
asyncio.as_completed()
asyncio.wait()

第三优先级 ⭐⭐⭐

建议掌握：

asyncio.to_thread()
TaskGroup
Async Context Manager
Async Iterator
Async Generator
run_in_executor()

第四优先级 ⭐⭐

知道概念即可：

Future
Transport
Protocol
低级 Event Loop API
自定义 Event Loop

二十四、结合 FastAPI，你真正应该掌握什么？

我建议你不要单独把 asyncio 学成一门“理论课”。

直接结合 FastAPI 学：

 FastAPI
 │
 ↓
 async def
 │
 ↓
 await
 │
 ┌─────────┼─────────┐
 ↓ ↓ ↓
 HTTP Redis DB
 │ │ │
 httpx redis asyncpg
 │ │ │
 └─────────┼─────────┘
 ↓
 Event Loop

然后重点练习：

实战 1：并发调用 3 个 API

await asyncio.gather(
 call_api_1(),
 call_api_2(),
 call_api_3()
)

实战 2：限制并发

semaphore = asyncio.Semaphore(10)

实战 3：超时

asyncio.timeout(3)

实战 4：任务队列

asyncio.Queue()

实战 5：阻塞代码

await asyncio.to_thread(...)

实战 6：FastAPI + Async HTTP

httpx.AsyncClient

实战 7：FastAPI + Async PostgreSQL

FastAPI
 ↓
SQLAlchemy Async
 ↓
asyncpg
 ↓
PostgreSQL

二十五、最后给你一个非常重要的认知

如果你以前是 Java/Spring Boot 开发者，可以这样建立映射：

Java Python

Thread Pool → asyncio Event Loop
Future → asyncio Future
CompletableFuture → Coroutine / Task / gather
ExecutorService → Task scheduling
synchronized → asyncio.Lock
Semaphore → asyncio.Semaphore
Blocking I/O → 不应该阻塞 Event Loop
WebFlux → async FastAPI

不过不要把它们简单认为是“一一对应”，尤其是 CompletableFuture ≠ Coroutine。

fastAPI基本功能

Sat, 04 Nov 2023 00:00:00 +0000

Python 世界里的一个现代、高性能 Web API 开发框架，定位有点类似 Java 的 Spring Boot，但更加轻量。

如果你熟悉 Java + Spring Boot，学习 FastAPI 会非常容易。它特别适合开发 REST API、微服务、AI 应用后端、RAG/LLM 服务。

一、FastAPI 主要有哪些功能？

FastAPI 的核心功能可以分成下面几个方面：

功能	FastAPI 能做什么	类似 Java/Spring
HTTP API	GET/POST/PUT/DELETE	`@GetMapping` / `@PostMapping`
路由	URL → Python 函数	`@RequestMapping`
参数校验	自动校验请求参数	`@Valid`
数据模型	Pydantic Model	DTO
JSON 序列化	Python 对象 ↔ JSON	Jackson
Swagger	自动生成 API 文档	SpringDoc
OpenAPI	自动生成 OpenAPI Schema	OpenAPI
Dependency Injection	依赖注入	`@Autowired`
Middleware	请求/响应拦截	Filter
Authentication	JWT/OAuth2/API Key	Spring Security
Async	异步 API	WebFlux
WebSocket	实时通信	Spring WebSocket
Background Task	后台任务	`@Async` 等
文件上传	UploadFile	MultipartFile
CORS	跨域处理	CorsFilter
Streaming	流式返回	StreamingResponse
微服务	REST 微服务	Spring Boot Microservice

二、最核心的功能：开发 REST API

最简单的 FastAPI：

from fastapi import FastAPI

app = FastAPI()

@app.get("/hello")
def hello():
 return {"message": "Hello World"}

启动：

uvicorn main:app --reload

访问：

http://localhost:8000/hello

{
 "message": "Hello World"
}

如果用 Spring Boot 思维理解：

@RestController
public class HelloController {

 @GetMapping("/hello")
 public Map<String, String> hello() {
 return Map.of("message", "Hello World");
 }
}

所以：

FastAPI @app.get()
 ↓
Spring Boot @GetMapping

三、HTTP 方法

FastAPI 支持标准 HTTP 方法：

@app.get("/users")
def get_users():
 pass

@app.post("/users")
def create_user():
 pass

@app.put("/users/{user_id}")
def update_user(user_id: int):
 pass

@app.delete("/users/{user_id}")
def delete_user(user_id: int):
 pass

对应：

GET 查询
POST 创建
PUT 更新
DELETE 删除
PATCH 部分更新

这部分和 Spring MVC 非常类似。

四、强大的参数校验

这是 FastAPI 非常重要的一个功能。

例如：

@app.get("/users/{user_id}")
def get_user(user_id: int):
 return {"user_id": user_id}

这里：

user_id: int

意味着 FastAPI 会自动进行类型校验。

请求：

/users/100

正常。

请求：

/users/abc

FastAPI 会自动返回类似：

{
 "detail": [
 {
 "type": "int_parsing",
 "loc": ["path", "user_id"],
 "msg": "Input should be a valid integer"
 }
 ]
}

你不需要自己写：

if not isinstance(user_id, int):
 ...

五、Pydantic：FastAPI 的核心

如果你要认真学习 FastAPI，Pydantic 是必须掌握的。

例如创建用户：

from pydantic import BaseModel

class User(BaseModel):
 name: str
 age: int
 email: str

然后：

@app.post("/users")
def create_user(user: User):
 return user

客户端：

{
 "name": "Vincent",
 "age": 30,
 "email": "vincent@example.com"
}

FastAPI 会自动：

JSON
 ↓
Pydantic
 ↓
User 对象
 ↓
业务代码

这和 Java：

public class UserDTO {

 private String name;

 private Integer age;

 private String email;
}

非常类似。

六、自动生成 Swagger API 文档

这是 FastAPI 最好用的功能之一。

启动：

uvicorn main:app --reload

访问：

http://localhost:8000/docs

就可以看到 Swagger UI。

它会自动显示：

GET /users
POST /users
PUT /users/{id}
DELETE /users/{id}

而且可以直接点击：

Try it out

测试 API。

另外：

http://localhost:8000/redoc

可以看到 ReDoc 文档。

所以你不需要手动维护 API 文档。

七、OpenAPI

FastAPI 天生支持 OpenAPI。

访问：

http://localhost:8000/openapi.json

可以得到 API Schema。

例如：

{
 "openapi": "3.1.0",
 "paths": {
 "/users": {
 "get": {
 ...
 }
 }
 }
}

这对于：

API Gateway
API 文档
自动生成客户端
前后端协作
自动化测试

都非常有用。

八、Dependency Injection 依赖注入

FastAPI 也有自己的 DI。

例如：

from fastapi import Depends

def get_db():
 db = create_database_connection()

 try:
 yield db
 finally:
 db.close()

Controller：

@app.get("/users")
def get_users(db = Depends(get_db)):
 return db.query_users()

这里：

Depends(get_db)

就是依赖注入。

如果你来自 Spring：

@Autowired
private UserService userService;

FastAPI 的：

Depends(...)

可以理解成一种轻量级 DI 机制。

九、Middleware

FastAPI 支持 Middleware。

例如记录请求时间：

@app.middleware("http")
async def log_request(request, call_next):

 start = time.time()

 response = await call_next(request)

 duration = time.time() - start

 print(f"Request took {duration}s")

 return response

典型用途：

Request
 ↓
Middleware
 ↓
Authentication
 ↓
Controller
 ↓
Service
 ↓
Response
 ↓
Middleware
 ↓
Client

可以用于：

Logging
Trace ID
Authentication
CORS
Metrics
Request timing
Exception handling

十、Authentication / Authorization

FastAPI 对安全认证支持也很好。

例如：

Authorization: Bearer eyJhbGciOi...

可以使用：

OAuth2
JWT
API Key
HTTP Basic

典型架构：

Client
 ↓
JWT
 ↓
FastAPI
 ↓
Authentication
 ↓
Authorization
 ↓
Business Service

如果你熟悉 Spring Security，可以把这一块理解成：

FastAPI Security
 ≈
Spring Security

当然，两者实现方式差别比较大。

十一、异步编程

这是 FastAPI 非常重要的特点。

可以直接写：

@app.get("/users")
async def get_users():
 users = await query_users()
 return users

Python：

async
await

配合：

asyncio

可以实现高并发 I/O 服务。

例如：

HTTP Request
 ↓
FastAPI
 ↓
async
 ↓
Database
 ↓
Redis
 ↓
External API

特别适合：

AI API
LLM
RAG
外部 API 调用
高并发 I/O
微服务

十二、WebSocket

FastAPI 不只是 REST API。

还支持 WebSocket。

例如：

@app.websocket("/ws")
async def websocket_endpoint(websocket: WebSocket):

 await websocket.accept()

 while True:
 data = await websocket.receive_text()

 await websocket.send_text(
 f"Message: {data}"
 )

可以用于：

聊天系统
实时通知
在线状态
实时监控
AI Streaming

十三、文件上传

例如：

from fastapi import UploadFile, File

@app.post("/upload")
async def upload(file: UploadFile = File(...)):

 content = await file.read()

 return {
 "filename": file.filename
 }

可以处理：

图片
PDF
Excel
CSV
Word
音频
视频

这对于 AI 应用特别重要。

例如：

用户上传 PDF
 ↓
FastAPI
 ↓
PDF Parser
 ↓
Text
 ↓
Embedding
 ↓
Vector DB

这就是典型的 RAG 后端。

十四、Background Tasks

FastAPI 可以执行后台任务。

例如：

from fastapi import BackgroundTasks

@app.post("/send-email")
def send_email(
 background_tasks: BackgroundTasks
):

 background_tasks.add_task(
 send_email_task
 )

 return {
 "message": "Email will be sent"
 }

请求不需要等待：

Client
 ↓
FastAPI
 ↓
立即返回
 ↓
Background Task
 ↓
Send Email

不过要注意：

FastAPI BackgroundTasks 适合轻量后台任务，不等同于 Kafka/Celery 这种真正的分布式任务队列。

十五、CORS

如果你的前端是 React：

React
localhost:3000
 ↓
FastAPI
localhost:8000

会遇到跨域。

FastAPI 可以：

from fastapi.middleware.cors import CORSMiddleware

app.add_middleware(
 CORSMiddleware,
 allow_origins=["http://localhost:3000"],
 allow_credentials=True,
 allow_methods=["*"],
 allow_headers=["*"],
)

这和你之前做 React + Spring Boot 时遇到的 CORS 问题非常类似。

十六、Streaming Response

这个功能对你尤其值得学习。

比如 AI：

用户
 ↓
React
 ↓
FastAPI
 ↓
LLM
 ↓
Token 1
Token 2
Token 3
Token 4
...

而不是：

用户
 ↓
FastAPI
 ↓
等待 10 秒
 ↓
一次性返回完整答案

可以实现：

Hello
Hello, how
Hello, how are
Hello, how are you

这种流式输出。

所以现在很多：

ChatGPT 类应用
AI Agent
RAG
LLM Gateway

都会使用 FastAPI。

十七、数据库

FastAPI 本身不是 ORM。

它通常和其他数据库框架组合。

例如：

FastAPI
 │
 ├── SQLAlchemy
 │
 ├── SQLModel
 │
 ├── Tortoise ORM
 │
 └── asyncpg
 │
 ↓
 PostgreSQL

例如：

@app.get("/users")
async def users():
 result = await db.execute(...)
 return result

你可以使用：

PostgreSQL
MySQL
Oracle
MongoDB
Redis
Elasticsearch

等。

十八、FastAPI 的整体架构

如果按照你熟悉的 Spring Boot 思维，可以这样理解：

 ┌───────────────┐
 │ React │
 └───────┬───────┘
 │
 HTTP
 │
 ┌───────▼───────┐
 │ FastAPI │
 │ Controller │
 └───────┬───────┘
 │
 ┌─────────────┼─────────────┐
 │ │ │
 Pydantic Depends Middleware
 │ │ │
 └─────────────┼─────────────┘
 │
 ┌───────▼───────┐
 │ Service │
 └───────┬───────┘
 │
 ┌──────────────┼──────────────┐
 │ │ │
 Redis PostgreSQL Kafka
 │ │ │
 └──────────────┼──────────────┘
 │
 ┌───────▼───────┐
 │ External APIs │
 │ LLM / AI │
 └───────────────┘

SQLAlchemy基本功能

Sat, 04 Nov 2023 00:00:00 +0000

SQLAlchemy 是 Python 生态里最主流的数据库工具之一。它不只是一个 ORM，更准确地说，它由 SQL Expression Language + ORM + Engine/Connection + Transaction 等部分组成。

如果你熟悉 Java 的 Spring Boot + JPA/Hibernate + MyBatis，可以这样理解：

SQLAlchemy	Java 中类似
Engine	DataSource / Connection Pool
Connection	JDBC Connection
SQL Expression Language	MyBatis / JDBC SQL
ORM	JPA / Hibernate
Session	EntityManager
Model	Entity
relationship	`@OneToMany` / `@ManyToOne`
Alembic	Flyway / Liquibase

1. 数据库连接

SQLAlchemy 可以管理数据库连接：

from sqlalchemy import create_engine

engine = create_engine(
 "postgresql+psycopg2://user:password@localhost/mydb"
)

支持很多数据库，例如：

PostgreSQL
MySQL
SQLite
Oracle
SQL Server

而且自带 Connection Pooling。

例如：

engine = create_engine(
 "mysql+pymysql://user:password@localhost/test",
 pool_size=10,
 max_overflow=20
)

这相当于 Java 中配置 HikariCP。

2. 执行原生 SQL

SQLAlchemy 可以直接执行 SQL。

from sqlalchemy import text

with engine.connect() as conn:
 result = conn.execute(
 text("SELECT * FROM users WHERE age > :age"),
 {"age": 18}
 )

 for row in result:
 print(row)

这一点比较像：

jdbcTemplate.query(...)

或者 MyBatis：

<select id="findUsers">
 SELECT * FROM users WHERE age > #{age}
</select>

3. SQL Expression Language

这是 SQLAlchemy 非常重要的功能。

你可以不用 ORM，直接用 Python 构造 SQL。

例如：

from sqlalchemy import select

stmt = select(user_table).where(
 user_table.c.age > 18
)

with engine.connect() as conn:
 result = conn.execute(stmt)

SQLAlchemy 会生成类似：

SELECT *
FROM users
WHERE age > 18

复杂查询也可以组合：

stmt = (
 select(users)
 .where(users.c.age > 18)
 .order_by(users.c.name)
 .limit(10)
)

所以 SQLAlchemy 并不是简单的 ORM。

4. ORM

这是大家最熟悉的功能。

定义 Model：

from sqlalchemy.orm import DeclarativeBase
from sqlalchemy.orm import Mapped
from sqlalchemy.orm import mapped_column


class Base(DeclarativeBase):
 pass


class User(Base):
 __tablename__ = "users"

 id: Mapped[int] = mapped_column(primary_key=True)
 name: Mapped[str]
 age: Mapped[int]

这相当于 Java：

@Entity
@Table(name = "users")
public class User {

 @Id
 private Long id;

 private String name;

 private Integer age;
}

5. CRUD

SQLAlchemy ORM 可以完成完整 CRUD。

Create

user = User(
 name="Vincent",
 age=30
)

session.add(user)
session.commit()

Read

users = session.query(User).all()

现代 SQLAlchemy 更推荐：

stmt = select(User)

users = session.scalars(stmt).all()

Update

user = session.get(User, 1)

user.age = 35

session.commit()

Delete

user = session.get(User, 1)

session.delete(user)

session.commit()

6. 条件查询

例如：

stmt = (
 select(User)
 .where(User.age >= 18)
 .where(User.name == "Vincent")
)

users = session.scalars(stmt).all()

对应：

SELECT *
FROM users
WHERE age >= 18
AND name = 'Vincent';

还可以：

from sqlalchemy import or_

stmt = select(User).where(
 or_(
 User.age < 18,
 User.age > 60
 )
)

7. JOIN

SQLAlchemy 对 JOIN 支持非常完整。

例如：

stmt = (
 select(User, Order)
 .join(Order, User.id == Order.user_id)
)

相当于：

SELECT *
FROM users u
JOIN orders o
 ON u.id = o.user_id;

也支持：

INNER JOIN
LEFT JOIN
RIGHT JOIN
OUTER JOIN
多表 JOIN
子查询
CTE

8. 一对多 / 多对一关系

例如：

User
 │
 ├── Order
 ├── Order
 └── Order

定义：

class User(Base):
 __tablename__ = "users"

 id: Mapped[int] = mapped_column(primary_key=True)

 orders: Mapped[list["Order"]] = relationship(
 back_populates="user"
 )


class Order(Base):
 __tablename__ = "orders"

 id: Mapped[int] = mapped_column(primary_key=True)

 user_id: Mapped[int] = mapped_column(
 ForeignKey("users.id")
 )

 user: Mapped["User"] = relationship(
 back_populates="orders"
 )

然后：

user.orders

就可以获取用户订单。

这非常类似 Hibernate：

@OneToMany
private List<Order> orders;

9. Lazy Loading / Eager Loading

SQLAlchemy 支持不同的数据加载策略。

例如：

select(User).options(
 selectinload(User.orders)
)

常见策略：

lazy loading
selectin loading
joined loading
subquery loading

这对于解决 N+1 Query 问题非常重要。

例如：

查询 100 个 User
 ↓
每个 User 再查询一次 Order
 ↓
101 次 SQL

这就是典型的 N+1。

SQLAlchemy 可以通过：

selectinload(User.orders)

把它优化成少量 SQL。

10. Transaction 事务

SQLAlchemy 支持事务。

with Session(engine) as session:

 with session.begin():

 user = User(name="Tom", age=20)

 session.add(user)

如果发生异常：

Exception
 ↓
Rollback

正常完成：

commit

这和 Spring：

@Transactional

的思想非常接近。

11. Transaction Isolation

可以配置：

READ UNCOMMITTED
READ COMMITTED
REPEATABLE READ
SERIALIZABLE

例如：

engine = create_engine(
 url,
 isolation_level="REPEATABLE READ"
)

对于你之前学习的数据库事务、并发控制，这部分非常值得掌握。

12. Connection Pool

SQLAlchemy 内置连接池。

例如：

engine = create_engine(
 url,
 pool_size=10,
 max_overflow=20,
 pool_timeout=30,
 pool_recycle=1800
)

主要参数：

pool_size
max_overflow
pool_timeout
pool_recycle
pool_pre_ping

这部分可以直接和你熟悉的 HikariCP 对比学习。

13. Schema / Table 定义

SQLAlchemy 可以定义数据库表：

from sqlalchemy import Table, Column
from sqlalchemy import Integer, String

users = Table(
 "users",
 metadata,
 Column("id", Integer, primary_key=True),
 Column("name", String(100)),
 Column("age", Integer)
)

所以它也可以作为一个 SQL Schema Definition 工具。

14. Index

可以定义索引：

from sqlalchemy import Index

Index(
 "idx_user_name",
 users.c.name
)

也可以联合索引：

Index(
 "idx_user_name_age",
 users.c.name,
 users.c.age
)

对应：

CREATE INDEX idx_user_name_age
ON users(name, age);

15. Constraint

支持：

Primary Key
Foreign Key
Unique
Check
Not Null

例如：

age = mapped_column(
 Integer,
 CheckConstraint("age >= 0")
)

16. 数据库迁移

SQLAlchemy 本身主要负责数据库访问，数据库 Migration 通常搭配：

Alembic

例如：

alembic revision --autogenerate

然后：

alembic upgrade head

如果你熟悉 Java：

SQLAlchemy + Alembic
 ≈
Hibernate/JPA + Flyway/Liquibase

17. Async 异步数据库

现代 Python 后端非常重要。

SQLAlchemy 支持 Async API：

from sqlalchemy.ext.asyncio import create_async_engine

engine = create_async_engine(
 "postgresql+asyncpg://user:password@localhost/test"
)

然后：

async with AsyncSession(engine) as session:

 result = await session.execute(
 select(User)
 )

 users = result.scalars().all()

这在：

FastAPI
+
SQLAlchemy
+
PostgreSQL

架构中非常常见。

18. SQLAlchemy 的整体架构

你可以把它理解成：

 SQLAlchemy
 │
 ┌─────────────┼─────────────┐
 │ │ │
 Engine SQL Expression ORM
 │ │ │
 Connection select() Session
 │ │ │
 Connection Pool JOIN Model
 │ │ │
 └─────────────┼─────────────┘
 │
 DB Driver
 │
 ┌─────────────┼─────────────┐
 │ │ │
 PostgreSQL MySQL SQLite