文章目录
- 前言
- 一、阶段学习目标
- 二、项目最终工程结构（完整版）
- 三、单元测试：pytest \+ TestClient 全套实战
- 3\.1 安装测试依赖
- 3\.2 基础测试：测试普通接口
- 3\.3 带参数、POST、异常场景测试
- 3\.4 鉴权接口测试（Token 携带）
- 3\.5 异步接口测试写法
- 3\.6 全局测试夹具（conftest）
- 3\.7 执行测试 \+ 覆盖率
- 四、生产部署核心：Gunicorn \+ Uvicorn 高性能部署
- 4\.1 为什么开发不能直接上线 uvicorn？
- 4\.2 安装部署依赖
- 4\.3 生产启动命令（可直接上线）
- 4\.4 进程守护与开机自启（服务器必备）
- 五、Docker 容器化部署（企业标准）
- 5\.1 Dockerfile
- 5\.2 \.dockerignore
- 5\.3 构建与运行
- 六、生产环境安全优化（上线必改）
前言
经过前面8个阶段的学习，我们已经完整掌握 FastAPI 基础接口、Pydantic 校验、依赖注入、JWT 鉴权、SQLModel 数据库、中间件工程化、后台任务、WebSocket 高阶能力。
但是能跑 ≠ 能上线。
真实生产上线必须解决两个核心问题：
1.质量可控：代码迭代不崩、接口回归稳定、边界错误可覆盖（单元测试）；
2.稳定部署：告别 uvicorn 裸跑、支持进程守护、高并发、Docker 容器化、线上安全配置。
本阶段为系列最终落地阶段，1天时间补齐 FastAPI 项目从开发 → 测试 → 上线的完整闭环，学完即可交付企业级可上线项目。
一、阶段学习目标
1. 掌握 FastAPI + pytest 全套单元测试方案，测试接口、鉴权、数据库、异常场景；
2. 学会同步/异步接口测试、全局测试夹具、测试隔离、覆盖率统计；
3. 区分开发启动、生产启动差异，掌握 Gunicorn + Uvicorn 组合部署；
4. 实现 Dockerfile 容器打包、镜像构建、容器启停；
5. 掌握线上安全优化：日志、端口、进程、超时、跨域、密钥防护；
6. 学会服务器后台常驻、开机自启、故障自动重启；
7. 完整打通：开发 → 测试 → 打包 → 部署 → 运维整套流程。
二、项目最终工程结构（完整版）
这是本系列最终上线级目录结构，包含测试目录、容器配置、依赖管理：
fastapi-final-project/ ├── main.py # 项目入口 ├── requirements.txt # 项目依赖 ├── .env # 环境变量 ├── Dockerfile # 容器部署脚本 ├── .dockerignore ├── pytest.ini # 测试配置 ├── core/ # 核心配置、中间件、异常、日志 ├── db/ # 数据库会话、迁移 ├── models/ # 数据库实体 ├── schemas/ # DTO模型 ├── crud/ # 业务CRUD ├── routers/ # 模块化路由 ├── utils/ # 工具类 └── tests/ # 单元测试目录 ├── conftest.py # 全局测试夹具 ├── test_api.py # 接口测试 └── test_auth.py # 鉴权测试三、单元测试：pytest + TestClient 全套实战
3.1 安装测试依赖
pipinstallpytest httpx pytest-cov说明：
- pytest：主流 Python 测试框架
- httpx：TestClient 底层请求库，支持同步/异步
- pytest-cov：统计代码测试覆盖率
3.2 基础测试：测试普通接口
FastAPI 内置TestClient，完全模拟真实请求，无需启动服务即可测试所有接口。
tests/test_api.py
fromfastapi.testclientimportTestClientfrommainimportapp client=TestClient(app)deftest_root():"""测试根路径接口"""resp=client.get("/")assertresp.status_code==200assert"msg"inresp.json()3.3 带参数、POST、异常场景测试
deftest_user_register():"""测试用户注册正常场景"""resp=client.post("/api/auth/register",json={"username":"testdemo","email":"test@demo.com","password":"Demo123456"})# 正常返回200assertresp.status_code==200deftest_register_error():"""测试参数非法异常场景"""resp=client.post("/api/auth/register",json={"username":"1","email":"wrong-email","password":"123"})# 参数校验失败返回422assertresp.status_code==4223.4 鉴权接口测试（Token 携带）
先登录获取 Token，再请求需要登录的接口，覆盖真实业务链路。
deftest_user_profile():# 1. 登录获取tokenlogin_resp=client.post("/api/auth/login",data={"username":"testdemo","password":"Demo123456"})token=login_resp.json()["access_token"]# 2. 携带token请求个人信息headers={"Authorization":f"Bearer{token}"}resp=client.get("/api/user/me",headers=headers)assertresp.status_code==200assertresp.json()["data"]["username"]=="testdemo"3.5 异步接口测试写法
如果项目存在 async 异步接口，需要使用异步测试客户端。
importpytestfromhttpximportAsyncClientfrommainimportapp@pytest.mark.asyncioasyncdeftest_async_interface():asyncwithAsyncClient(app=app,base_url="http://test")asac:resp=awaitac.get("/")assertresp.status_code==2003.6 全局测试夹具（conftest）
统一生成测试客户端、测试数据库，所有测试文件共享。
tests/conftest.py
importpytestfromfastapi.testclientimportTestClientfrommainimportapp@pytest.fixture(scope="function")defclient():returnTestClient(app)3.7 执行测试 + 覆盖率
# 执行所有测试pytest# 详细输出pytest-v# 统计代码覆盖率pytest--cov=.四、生产部署核心：Gunicorn + Uvicorn 高性能部署
4.1 为什么开发不能直接上线 uvicorn？
- uvicorn 单进程、不支持负载均衡、崩溃不重启、无法高并发；
- 生产标准组合：Gunicorn 进程管理 + Uvicorn 异步工作核。
4.2 安装部署依赖
pipinstallgunicorn uvicorn4.3 生产启动命令（可直接上线）
# 核心参数讲解# -w：工作进程数（CPU核心数*2+1）# -k：使用uvicorn异步worker# -b：绑定端口# --daemon：后台守护运行# --log-file：日志输出gunicorn main:app\-w4\-kuvicorn.workers.UvicornWorker\-b0.0.0.0:8000\--daemon\--log-level=info4.4 进程守护与开机自启（服务器必备）
使用 systemd 托管进程，崩溃自动重启、开机自启。
新建：/etc/systemd/system/fastapi.service
[Unit] Description=FastAPI Production Service After=network.target [Service] User=root WorkingDirectory=/项目绝对路径 ExecStart=/虚拟环境绝对路径/bin/gunicorn main:app -w 4 -k uvicorn.workers.UvicornWorker -b 0.0.0.0:8000 Restart=always [Install] WantedBy=multi-user.target常用命令：
systemctl daemon-reload systemctl start fastapi systemctlenablefastapi systemctl status fastapi五、Docker 容器化部署（企业标准）
5.1 Dockerfile
FROM python:3.11-slim WORKDIR /app COPY requirements.txt . RUN pip install --no-cache-dir -r requirements.txt COPY . . EXPOSE 8000 CMD ["gunicorn","main:app","-w","4","-k","uvicorn.workers.UvicornWorker","-b","0.0.0.0:8000"]5.2 .dockerignore
__pycache__ *.pyc .env tests .git .gitignore5.3 构建与运行
# 构建镜像dockerbuild-tfastapi-pro.# 启动容器dockerrun-d-p8000:8000--namefastapi-service fastapi-pro六、生产环境安全优化（上线必改）
1.关闭 DEBUG：生产禁止开启调试模式，防止信息泄露；
2.密钥环境变量化：SECRET_KEY、数据库密码禁止硬编码；
3.CORS 严格域名限制：禁止 * 通配符；
4.关闭 SQL 日志 echo=False；
5.禁用自动建表：生产只用 alembic 迁移；
6.开启进程自动重启，防止服务挂死；
7.统一日志持久化，方便线上排错。