FastAPI路由必须用async def定义，因其异步优先设计，普通def会阻塞事件循环降低吞吐量；uvicorn--workers设为N-1（如CPU≥4时设3），--loop用auto默认值；返回JSON应直接return dict而非字符串，避免content-type错误。
FastAPI项目初始化时为什么必须用 async def 定义路由
因为 FastAPI 的核心设计是异步优先，所有路由函数默认在 uvicorn 的事件循环中执行。如果写成普通 def，虽然也能跑通，但会阻塞整个事件循环——比如调用一个同步数据库查询或 HTTP 请求，后续所有并发请求都会排队等待，吞吐量直接掉到单线程水平。
实操建议：
- 所有接口函数必须以
async def开头，即使当前逻辑没 await 任何东西 - 若必须调用同步函数（如
json.loads()、hashlib.sha256()），可直接调用；但涉及 I/O（文件读写、requests.get、sqlite3）务必用asyncio.to_thread()或对应异步库（如aiohttp、aiosqlite） - 返回值类型提示要写清楚，例如
-> dict或-> List[Item]，FastAPI 依赖它做自动文档和序列化
uvicorn 启动命令里 --workers 和 --loop 参数怎么选
--workers 控制的是进程数，不是协程数；uvicorn 默认只启 1 个 worker（即单进程），靠 asyncio 调度成千上万协程。加 worker 是为利用多核 CPU，但要注意：每个 worker 都会独立加载一次 app，且全局变量不共享。
常见错误现象：RuntimeError: There is no current event loop in thread 'ThreadPoolExecutor-0_0' —— 多半是开了多个 worker 却在模块顶层创建了 asyncio.EventLoop 实例。
立即学习“Python免费学习笔记（深入）”；
实操建议：
- 开发阶段用
uvicorn main:app --reload就够了，不用指定--workers - 生产环境若 CPU 核心数 ≥ 4，可设
--workers 3（N-1 原则），避免调度争抢 -
--loop auto（默认）即可，别硬切uvloop，除非压测确认有收益；macOS 上uvloop可能触发kqueue相关报错 - 务必加
--host 0.0.0.0和--port 8000，否则默认只监听 127.0.0.1，容器或远程访问会连不上
如何让 FastAPI 正确识别并返回 JSON 而不是字符串
很多人写 return '{"msg": "ok"}'，结果响应头是 text/plain，前端 response.json() 报错。FastAPI 不会自动解析字符串为 JSON，它只对 dict、list、Pydantic 模型等原生可序列化对象做 json.dumps() 并设 application/json 头。
让 macOS 自动化像说话一样简单 —— 用代码控制你的 Mac，无需学习 AppleScript 系统要求 macOS 14+ (Sonoma) Python 3.9+ 需要开启：辅助功能 + 屏幕录制权限
使用场景：需要手动控制 JSON 格式（如保留 NaN、处理 Decimal）、或兼容旧协议返回 raw bytes。
实操建议：
- 正常返回直接写
return {"msg": "ok", "data": []}，别加json.dumps() - 若需自定义序列化，用
JSONResponse：from fastapi.responses import JSONResponse，然后return JSONResponse(content={"error": "not found"}, status_code=404) - 绝对不要用
Response包一层字符串并手动设media_type="application/json"，容易漏转义、乱码、状态码错位 - 检查响应头：用
curl -I http://localhost:8000/xxx确认content-type: application/json
启动后接口 500 但控制台没报错，怎么快速定位
FastAPI 默认捕获所有未处理异常并返回 500，同时把 traceback 写进日志——但 uvicorn 默认日志等级是 INFO，ERROR 级的 traceback 被屏蔽了。
性能影响：开 --log-level debug 会打满磁盘，但调试阶段值得；线上应配 Sentry 或结构化日志。
实操建议：
- 启动时加
--log-level error，至少能看到异常堆栈 - 在路由函数开头加
print("debug:", request.url)，确认是否走到该函数（注意：print 在多 worker 下可能不实时显示） - 用
try/except Exception as e:包住关键逻辑，print(f"ERR: {e}")+raise，避免静默失败 - 检查依赖注入（
Depends()）里的函数是否抛了异常——它比路由体更早执行，出错也 500
最常被忽略的是 Pydantic 模型字段类型与传入数据不匹配（比如期望 int 却收到 "123" 字符串），它不会报 SyntaxError，而是默默转成 None 或触发后续空指针——得开 validate_assignment=True 并配合日志观察。
