FastAPI + Uvicorn 集成结构

本文档说明 lyedu-api-python 中 pip install fastapi uvicorn 的依赖关系与集成方式。

一、依赖配置

requirements.txt
├── fastapi>=0.115.0      # Web 框架：路由、中间件、OpenAPI 文档
└── uvicorn[standard]>=0.34.0   # ASGI 服务器：运行 FastAPI 应用

• fastapi：构建 REST API，提供路由、请求校验（Pydantic）、自动文档（/docs）、CORS 等
• uvicorn[standard]：[standard] 含 uvloop、httptools，提升异步性能

二、集成结构

lyedu-api-python/
├── main.py                 # 入口：创建 FastAPI 实例，注册路由，启动 uvicorn
├── config.py               # 配置（HOST/PORT/MYSQL/REDIS 等）
├── routers/                # 路由模块（挂载到 /api 下）
│   ├── auth.py
│   ├── course.py
│   └── ...
├── services/               # 业务逻辑层
├── models/                 # 数据模型
├── util/                   # 工具（logger、jwt、upload 等）
└── alembic/                # 数据库迁移

main.py 中的集成关系

┌─────────────────────────────────────────────────────────────┐
│  from fastapi import FastAPI                                 │
│  app = FastAPI(title='LyEdu API', lifespan=...)              │
│  app.add_middleware(CORSMiddleware, ...)                     │
│  app.include_router(xxx.router, prefix='/api')               │
└─────────────────────────────────────────────────────────────┘
                              │
                              ▼
┌─────────────────────────────────────────────────────────────┐
│  if __name__ == "__main__":                                  │
│      if "--serve" in sys.argv:                               │
│          import uvicorn                                       │
│          uvicorn.run(app, host=config.HOST, port=config.PORT) │
└─────────────────────────────────────────────────────────────┘

• FastAPI：定义 app，挂载所有 router
• Uvicorn：加载 app，监听端口，处理 HTTP 请求

三、启动方式

方式	命令	适用场景
开发	python main.py	主进程启动子进程 --serve，后台运行并等待就绪后退出
直接	python main.py --serve	内部使用，由主进程 fork 后调用
命令行	uvicorn main:app --host 0.0.0.0 --port 9700	Docker、生产环境常用
打包 exe	双击运行	Windows 下等价于 python main.py

Docker 中的用法

# Dockerfile：pip install -r requirements.txt
ENTRYPOINT ["./docker-entrypoint.sh"]

# docker-entrypoint.sh 末尾
exec uvicorn main:app --host 0.0.0.0 --port 9700

四、请求链路

HTTP 请求
    │
    ▼
Uvicorn (ASGI 服务器)
    │
    ▼
FastAPI (Starlette 应用)
    │
    ├─→ CORS 中间件
    ├─→ NoCache 中间件
    ├─→ 路由匹配 /api/xxx
    │       │
    │       ▼
    │   routers/*.py 中的 @router.get/post/...
    │       │
    │       ▼
    │   services/*.py 业务逻辑
    │       │
    │       ▼
    │   db / Redis 等
    │
    ▼
HTTP 响应

五、相关配置

变量	默认值	说明
HOST	0.0.0.0	监听地址，0.0.0.0 允许外网访问
PORT	9700	监听端口

配置来源：.env / .env.dev（开发）或 ~/.lyedu/conf/config.ini（打包后）。

---

六、接口文档

文档	路径	说明
Swagger UI	/docs	FastAPI 自动生成，可在线调试接口
OpenAPI JSON	/openapi.json	标准 OpenAPI 3.0 规范
接口说明（人工维护）	docs/LYEDU_API_PYTHON.md	业务说明、入参/出参、示例，供前端对接
接口文档（运行时）	/interface-doc	服务运行时提供接口说明 Markdown（开发环境含仓库文档时可用）

文档关系

LYEDU_API_PYTHON.md  ←→  代码 routers/*.py
        │                         │
        │                         ▼
        │                   OpenAPI schema
        │                         │
        └─────────────────────────┼──→ /docs (Swagger UI)
                                 └──→ /interface-doc (Markdown)

• Swagger /docs：随代码自动更新，适合快速调试
• LYEDU_API_PYTHON.md：人工编写，含业务规则、可见性说明、错误示例，便于前后端协同
• 新增接口时建议同步更新 docs/LYEDU_API_PYTHON.md