知识小屋

    从零初始化项目

    这一节先把项目创建起来，并安装基础依赖。

    示例使用 uv，因为它适合管理 Python 项目、虚拟环境和锁文件。如果你还没用 uv，也可以用 pip，核心代码不受影响。

    一、创建项目

    uv init my-fastapi
cd my-fastapi

    指定 Python 版本可以写在 .python-version：

    3.12

    你的参考项目使用 Python >=3.13，新项目可以用 3.12 或更新版本。教程代码使用 Python 3.10+ 语法。

    二、安装依赖

    uv add "fastapi[standard]" sqlalchemy pymysql alembic pydantic-settings pyjwt "pwdlib[argon2]"

    依赖说明：

    依赖作用
    fastapi[standard]FastAPI 和常用标准依赖，包含开发命令
    sqlalchemyORM，操作数据库
    pymysqlMySQL 驱动
    alembic数据库迁移
    pydantic-settings读取 .env 和环境变量
    pyjwt签发和校验 JWT
    pwdlib[argon2]密码哈希，FastAPI 官方安全教程也使用它

    如果不用 uv，可以执行：

    pip install "fastapi[standard]" sqlalchemy pymysql alembic pydantic-settings pyjwt "pwdlib[argon2]"

    三、创建目录

    mkdir -p app/api/routes app/controllers app/services app/models app/schemas app/db app/dependencies app/middlewares app/core

    Windows PowerShell 可以逐个创建：

    New-Item -ItemType Directory -Force app/api/routes, app/controllers, app/services, app/models, app/schemas, app/db, app/dependencies, app/middlewares, app/core

    给 Python 包目录补上 __init__.py：

    app/__init__.py
app/api/__init__.py
app/api/routes/__init__.py
app/controllers/__init__.py
app/services/__init__.py
app/models/__init__.py
app/schemas/__init__.py
app/db/__init__.py
app/dependencies/__init__.py
app/middlewares/__init__.py
app/core/__init__.py

    四、创建环境变量模板

    .env.example：

    APP_NAME=my-fastapi
APP_ENV=local
APP_HOST=127.0.0.1
APP_PORT=8000
APP_DEBUG=true
DB_ECHO=false

DATABASE_URL=mysql+pymysql://root:password@127.0.0.1:3306/my_fastapi?charset=utf8mb4

JWT_SECRET_KEY=please-change-this-secret-key-at-least-32-bytes
JWT_ALGORITHM=HS256
JWT_ACCESS_TOKEN_EXPIRE_MINUTES=1440

    复制一份真实配置：

    cp .env.example .env

    Windows：

    Copy-Item .env.example .env

    .env 里会有数据库密码和 JWT 密钥，不要提交到 Git。

    .gitignore：

    .env
.venv
__pycache__/
.pytest_cache/
dist/

    五、创建最小 app/main.py

    app/main.py：

    from fastapi import FastAPI


def create_app() -> FastAPI:
    # 应用工厂：后续中间件、异常处理、路由都在这里统一装配。
    app = FastAPI(title="my-fastapi")

    @app.get("/")
    def index():
        return {"message": "Hello FastAPI"}

    return app


app = create_app()

    启动：

    uv run fastapi dev app/main.py

    或者：

    fastapi dev app/main.py

    访问：

    http://127.0.0.1:8000/docs

    到这里，项目骨架已经能跑起来了。

    六、可选：本地开发启动入口

    参考项目里有一个根目录 main.py，用于打印服务地址、文档地址、数据库信息，并检查端口。

    初学阶段可以先不用。等项目变大后，再加这个文件提升本地开发体验。