像素小筑

【FastAPI实战】项目初始化及启动服务

## 一、环境准备 ### 1.1 检查 Python 版本 FastAPI 需要 Python 3.7 或更高版本。在终端执行以下命令检查版本： ```bash python --version # 或 python3 --version ``` 如果版本低于 3.7，请先升级 Python。 ### 1.2 创建虚拟环境（推荐） 使用虚拟环境可以隔离项目依赖，避免与全局环境冲突（请先选定一个空目录作为项目更目录，然后在选定的根目录下运行命令）： macOS/Linux： ```bash python -m venv fastapi_env source fastapi_env/bin/activate ``` Windows： ```bash python -m venv fastapi_env fastapi_env\Scripts\activate ``` 激活成功后，终端提示符前会出现 (fastapi_env) 字样。 ## 1.3 安装 FastAPI 和 Uvicorn 在激活的虚拟环境中安装依赖： ```bash pip install fastapi uvicorn[standard] ``` > fastapi：框架核心 > uvicorn[standard]：ASGI 服务器，[standard] 选项会安装必要的中间件依赖 💡 如果安装速度较慢，可使用国内镜像源加速，例如： ```bash pip install fastapi uvicorn[standard] -i https://pypi.tuna.tsinghua.edu.cn/simple ``` ## 二、创建 FastAPI 应用 ### 2.1 编写入口文件 创建一个名为 main.py 的文件，写入以下代码： ```python from fastapi import FastAPI # 创建 FastAPI 应用实例 app = FastAPI() # 定义根路由 @app.get("/") async def read_root(): return {"message": "Welcome to FastAPI"} ``` 这里 @app.get("/") 装饰器将函数 read_root 映射到根路径 / 的 GET 请求上，返回一个 JSON 格式的响应。 ### 2.2 启动服务 在终端中（确保当前目录包含 main.py），执行以下命令： ```bash uvicorn main:app --reload ``` 命令解析： > main:app：main 表示 Python 文件名，app 是文件中创建的 FastAPI 实例变量名 > --reload：启用自动重载，代码修改后服务器会自动重启，便于开发调试 ## 三、访问路由与 API 文档 ### 3.1 访问根路由 打开浏览器，访问以下地址： ```text http://127.0.0.1:8000 ``` 你应该能看到返回的 JSON 数据： ```json {"message": "Welcome to FastAPI"} ``` ### 3.2 查看自动生成的 API 文档 FastAPI 基于代码中的类型注解自动生成交互式 API 文档，默认提供以下访问端点： > Swagger UI（交互式）：访问 http://127.0.0.1:8000/docs，可以直接在浏览器中测试 API > ReDoc（文档式）：访问 http://127.0.0.1:8000/redoc，适合浏览和查阅 API 定义 > OpenAPI JSON（原始规范）：访问 http://127.0.0.1:8000/openapi.json，可供 Postman 等工具消费 💡 Swagger UI 支持点击 "Try it out" 发送真实请求，非常适合调试 POST 等浏览器无法直接测试的接口。 ## 四、项目结构规划（可选） 当项目逐渐复杂时，建议采用模块化的项目结构： ```text project/ ├── app/ │ ├── main.py # 入口文件 │ ├── routers/ # 路由模块 │ │ ├── __init__.py │ │ └── items.py │ ├── models/ # 数据模型 │ ├── schemas/ # 请求/响应模型 │ └── dependencies.py # 依赖注入 └── requirements.txt # 依赖清单 ``` ## 五、总结 通过以上步骤，你已经完成了： > 1. Python 虚拟环境的创建与依赖安装 > 2. FastAPI 应用的编写与启动 > 3. 路由的访问与自动生成 API 文档的查看 FastAPI 凭借其异步支持、自动文档生成、类型提示校验等特性，成为现代 Web API 开发的优选方案。接下来可以继续深入学习依赖注入、异步 API 开发、中间件等进阶内容。