py - fastapi

项目初始化（建文件夹 + 装依赖）

现在开始建项目文件夹，结构要像企业项目一样规范（别把所有文件放根目录）。

建项目文件夹比如项目名叫fastapi-perm-system，文件夹结构如下（先建空文件夹，后续慢慢填内容）：

bash

$ mkdir fastapi-demo
fastapi-demo/         # 项目根目录
├── app/              # 核心代码文件夹（所有业务代码放这）
│   ├── __init__.py   # Python包标记（必须有）
│   ├── routes/       # 路由（接口地址，比如/users、/roles）
│   ├── models/       # ORM模型（对应数据库表，比如User、Role）
│   ├── schemas/      # Pydantic模型（请求/响应体，比如UserCreate、UserResponse）
│   ├── services/     # 服务层（业务逻辑，比如UserService）
│   ├── config/       # 配置文件（数据库连接、JWT密钥）
│   └── utils/        # 工具函数（日志、密码加密）
├── .env              # 环境变量文件（数据库密码、JWT密钥，别传git）
├── requirements.txt  # 依赖库列表（要装的Python包）
└── main.py           # 项目入口文件（启动FastAPI）

写 requirements.txt（依赖库列表）把要装的库列出来，后续用pip install -r requirements.txt一键安装：

ini

fastapi==0.104.1                  # FastAPI核心库
uvicorn==0.24.0.post1             # ASGI服务器（跑FastAPI）
sqlalchemy==2.0.23                # ORM框架（操作数据库）
pymysql==1.1.0                    # MySQL驱动（SQLAlchemy连接MySQL用）
python-dotenv==1.0.0              # 加载.env环境变量
passlib==1.7.4                    # 密码哈希（加密用户密码）
python-jose[cryptography]==3.3.0  # JWT生成与验证
pydantic==2.5.2                   # 数据校验（FastAPI依赖）

安装依赖打开 cmd，进入项目根目录，输入：

bash

pip install -r requirements.txt

注意：如果报错 “pip 不是内部命令”，说明 Python 没加环境变量 —— 重新安装 Python，勾选 “Add Python to PATH”。

四、第三步：写第一个 FastAPI 接口（跑通！）现在写main.py和app/routes/hello.py，实现一个简单的/hello接口，验证环境是否正常。

写 main.py（项目入口） main.py是 FastAPI 的启动文件，负责创建 FastAPI 实例、注册路由：

python

from fastapi import FastAPI
from app.routes import hello  # 导入hello路由
 
# 创建FastAPI实例
app = FastAPI(
    title="企业级用户权限管理系统",  # 文档标题
    description="基于FastAPI的用户、角色、权限管理系统",  # 文档描述
    version="1.0.0"  # 版本号
)
 
# 注册路由（把hello.py的路由挂载到/app前缀下）
app.include_router(hello.router, prefix="/app")

写 app/routes/hello.py（第一个路由） routes文件夹放所有接口的路由（比如用户接口放user.py，角色接口放role.py），现在写hello.py：

python

from fastapi import APIRouter
 
# 创建路由实例（相当于“接口分组”）
router = APIRouter()
 
# 定义GET请求接口：/app/hello
@router.get("/hello")
def say_hello(name: str = "World"):
    """
    第一个FastAPI接口，返回问候语
    :param name: 可选参数，默认是World
    """
    return {"message": f"Hello, {name}!"}

五、第四步：运行项目（见证奇迹！）现在启动 FastAPI，看接口能不能访问。

启动命令打开 cmd，进入项目根目录，输入：

bash

uvicorn main:app --reload --port 8000

解释：

main:app：main.py里的app实例（FastAPI 对象）； --reload：开发模式（修改代码自动重启，不用手动关服务）； --port 8000：服务跑在 8000 端口（访问http://localhost:8000）。

验证接口启动成功后，会看到类似输出：

INFO:     Uvicorn running on http://127.0.0.1:8000 (Press CTRL+C to quit)
INFO:     Started reloader process [12345] using WatchFiles
INFO:     Started server process [12346]
INFO:     Waiting for application startup.
INFO:     Application startup complete.

（1）用浏览器访问接口打开浏览器，输入http://localhost:8000/app/hello，会看到：

{"message": "Hello, World!"}

如果传参数，比如http://localhost:8000/app/hello?name=小明，返回：

{"message": "Hello, 小明!"}

（2）用 Swagger 文档看接口 FastAPI 自动生成 Swagger 文档，访问http://localhost:8000/docs，会看到一个交互式文档：

找到/app/hello接口，点 “Try it out”；输入name参数（比如 “小红”），点 “Execute”；下面会显示请求 URL、响应结果 —— 这就是你写的接口！

六、常见问题排查（小白踩坑高频区）

启动报错 “Address already in use” 原因：8000 端口被其他程序占用（比如 Chrome、QQ）；解决：换个端口，比如uvicorn main:app --reload --port 8080。
浏览器访问接口报 “404 Not Found” 原因：路由路径错了（比如把/app/hello写成/hello）；解决：检查main.py里的prefix="/app"，hello.py里的@router.get("/hello")，组合起来是/app/hello。
Docker 启动 MySQL 报错 “port is already allocated” 原因：本地 3306 端口被其他 MySQL 占用（比如之前装过 MySQL）；解决：停掉本地 MySQL 服务，或者换 Docker 映射端口（比如-p 3307:3306，本地用 3307 访问）。 ———————————————— 版权声明：本文为CSDN博主「青翎_」的原创文章，遵循CC 4.0 BY-SA版权协议，转载请附上原文出处链接及本声明。原文链接：https://blog.csdn.net/weixin_42743844/article/details/157065312

特性	`uvicorn main:app --reload`	`fastapi dev main.py`
依赖	仅需要安装 `uvicorn`	需要安装 `fastapi-cli`
运行方式	手动指定应用实例位置（如 `main:app`）	自动检测应用实例
热重载支持	通过 `--reload` 参数启用	默认启用热重载
适用场景	适用于开发和生产环境	专为开发环境设计
额外功能	仅提供运行服务的功能	提供其他开发相关命令，如测试和模板生成
生产部署支持	支持生产环境（移除 `--reload`）	不适合直接用于生产环境

py - fastapi ​

项目初始化（建文件夹 + 装依赖） ​

py - fastapi

项目初始化（建文件夹 + 装依赖）