FastAPI零基础教程（九）- 测试与部署，1天完成生产落地

文章目录前言一、阶段学习目标二、项目最终工程结构完整版三、单元测试pytest \ TestClient 全套实战3\.1 安装测试依赖3\.2 基础测试测试普通接口3\.3 带参数、POST、异常场景测试3\.4 鉴权接口测试Token 携带3\.5 异步接口测试写法3\.6 全局测试夹具conftest3\.7 执行测试 \ 覆盖率四、生产部署核心Gunicorn \ Uvicorn 高性能部署4\.1 为什么开发不能直接上线 uvicorn4\.2 安装部署依赖4\.3 生产启动命令可直接上线4\.4 进程守护与开机自启服务器必备五、Docker 容器化部署企业标准5\.1 Dockerfile5\.2 \.dockerignore5\.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 测试框架- httpxTestClient 底层请求库支持同步/异步- pytest-cov统计代码测试覆盖率3.2 基础测试测试普通接口FastAPI 内置TestClient完全模拟真实请求无需启动服务即可测试所有接口。tests/test_api.pyfromfastapi.testclientimportTestClientfrommainimportapp clientTestClient(app)deftest_root():测试根路径接口respclient.get(/)assertresp.status_code200assertmsginresp.json()3.3 带参数、POST、异常场景测试deftest_user_register():测试用户注册正常场景respclient.post(/api/auth/register,json{username:testdemo,email:testdemo.com,password:Demo123456})# 正常返回200assertresp.status_code200deftest_register_error():测试参数非法异常场景respclient.post(/api/auth/register,json{username:1,email:wrong-email,password:123})# 参数校验失败返回422assertresp.status_code4223.4 鉴权接口测试Token 携带先登录获取 Token再请求需要登录的接口覆盖真实业务链路。deftest_user_profile():# 1. 登录获取tokenlogin_respclient.post(/api/auth/login,data{username:testdemo,password:Demo123456})tokenlogin_resp.json()[access_token]# 2. 携带token请求个人信息headers{Authorization:fBearer{token}}respclient.get(/api/user/me,headersheaders)assertresp.status_code200assertresp.json()[data][username]testdemo3.5 异步接口测试写法如果项目存在 async 异步接口需要使用异步测试客户端。importpytestfromhttpximportAsyncClientfrommainimportapppytest.mark.asyncioasyncdeftest_async_interface():asyncwithAsyncClient(appapp,base_urlhttp://test)asac:respawaitac.get(/)assertresp.status_code2003.6 全局测试夹具conftest统一生成测试客户端、测试数据库所有测试文件共享。tests/conftest.pyimportpytestfromfastapi.testclientimportTestClientfrommainimportapppytest.fixture(scopefunction)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核心数*21# -k使用uvicorn异步worker# -b绑定端口# --daemon后台守护运行# --log-file日志输出gunicorn main:app\-w4\-kuvicorn.workers.UvicornWorker\-b0.0.0.0:8000\--daemon\--log-levelinfo4.4 进程守护与开机自启服务器必备使用 systemd 托管进程崩溃自动重启、开机自启。新建/etc/systemd/system/fastapi.service[Unit] DescriptionFastAPI Production Service Afternetwork.target [Service] Userroot WorkingDirectory/项目绝对路径 ExecStart/虚拟环境绝对路径/bin/gunicorn main:app -w 4 -k uvicorn.workers.UvicornWorker -b 0.0.0.0:8000 Restartalways [Install] WantedBymulti-user.target常用命令systemctl daemon-reload systemctl start fastapi systemctlenablefastapi systemctl status fastapi五、Docker 容器化部署企业标准5.1 DockerfileFROM 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 日志 echoFalse5.禁用自动建表生产只用 alembic 迁移6.开启进程自动重启防止服务挂死7.统一日志持久化方便线上排错。