python安装操作流程-FastAPI + PostgreSQL简单流程

一、项目环境版本信息（必看，确保兼容性）

以下版本组合经过适配测试，可避免版本冲突，建议严格按照此版本搭建环境：

工具/组件	完整版本详情	核心作用
Conda	conda 25.11.0	虚拟环境管理，隔离项目依赖
Python	3.12	项目开发核心编程语言
PostgreSQL	PostgreSQL 16.11 on x86_64-pc-linux-gnu, compiled by gcc (GCC) 8.5.0 20210514 (Red Hat 8.5.0-28), 64-bit	关系型数据库，存储项目业务数据

二、Conda命令无法使用的解决方案（完整步骤）

安装Anaconda后，若终端/命令行提示"conda不是内部或外部命令"，可通过以下两种方式彻底解决，任选其一即可：

方式1：手动配置环境变量（永久生效，推荐）

右键点击「此电脑」→ 选择「属性」→ 点击「高级系统设置」（右上角）；
在弹出的窗口中，切换到「高级」选项卡 → 点击下方「环境变量」按钮；
在「用户变量」列表中，找到「Path」变量，双击进行编辑；
点击「新建」，依次添加以下3个路径（替换"你的用户名"为实际Windows用户名 ，例如"张三"则为C:\Users\张三\anaconda3）：

C:\Users\你的用户名\anaconda3
C:\Users\你的用户名\anaconda3\Scripts
C:\Users\你的用户名\anaconda3\Library\bin
点击「确定」保存所有配置窗口，关闭当前所有终端；
重新打开终端，输入「conda --version」，若显示conda 25.11.0，则配置生效。

环境变量配置界面参考：

方式2：通过Anaconda Prompt初始化（快速生效）

打开Windows开始菜单，在搜索框中输入「Anaconda Prompt」，点击运行该程序；
在Anaconda Prompt窗口中，复制并执行以下命令（替换"你的用户名"为实际用户名 ）：
C:\Users\你的用户名\anaconda3\Scripts\conda.exe init base
执行完成后，关闭Anaconda Prompt和所有其他终端；
重新打开任意终端，输入「conda --version」，显示版本号即生效。

三、后端项目目录结构（固定规范，完整无缺失）

项目采用标准FastAPI分层结构，目录清晰，无需修改，直接按此结构创建文件夹和文件即可：

markdown 复制代码

backend/
├── app/                     # 核心业务代码目录（项目核心文件夹，不可删除）
│   ├── main.py              # 项目启动入口（最关键文件，启动服务依赖此文件）
│   ├── database.py          # 数据库连接配置（初始化数据库引擎和会话）
│   ├── models.py            # 数据表结构定义（数据库表与Python类映射）
│   ├── schemas.py           # 接口请求/响应数据格式校验（参数合法性校验）
│   ├── crud.py              # 数据库CRUD操作（增删改查核心逻辑）
│   └── config.py            # 全局配置文件（含数据库连接URL等核心配置）
├── requirements.txt         # 项目依赖包清单（安装依赖时直接使用）
└── README.md                # 项目说明文档（可补充项目介绍、启动说明等）

四、核心文件完整代码（可直接复制运行，无一行遗漏）

以下所有文件代码均完整可运行，复制后按目录结构保存到对应文件夹中，无需修改格式即可使用。

1. requirements.txt（依赖包清单）

创建文件命名为「requirements.txt」，保存到backend目录下，内容如下：

txt 复制代码

fastapi
uvicorn[standard]
sqlalchemy
psycopg2-binary
python-dotenv
pydantic

2. app/config.py（数据库配置文件）

在backend/app目录下创建「config.py」，内容如下（数据库连接URL优先读取环境变量，默认适配本地数据库）：

python 复制代码

# app/config.py
import os

# 数据库连接URL配置：优先从环境变量读取，默认使用本地PostgreSQL配置
DATABASE_URL = os.getenv(
    "DATABASE_URL",
    "postgresql://postgres:postgres@localhost:5432/report_platform"
)

3. app/database.py（数据库连接初始化）

在backend/app目录下创建「database.py」，内容如下（初始化数据库引擎、会话工厂和数据表基类）：

python 复制代码

# app/database.py
from sqlalchemy import create_engine
from sqlalchemy.orm import sessionmaker, declarative_base
from app.config import DATABASE_URL

# 创建数据库引擎（核心连接对象，负责与PostgreSQL建立连接）
engine = create_engine(DATABASE_URL)
# 创建数据库会话工厂（每次接口请求会生成独立会话，避免数据冲突）
SessionLocal = sessionmaker(bind=engine)
# 声明数据表基类（所有数据表模型必须继承此类，用于自动创建表）
Base = declarative_base()

4. app/models.py（数据表定义，仅创建1张工作日志表）

在backend/app目录下创建「models.py」，内容如下（仅定义WorkLog工作日志表，字段完整，适配业务需求）：

python 复制代码

# app/models.py
from sqlalchemy import Column, String, Date, Text, Numeric
from sqlalchemy.dialects.postgresql import UUID, JSONB
import uuid
from app.database import Base

class WorkLog(Base):
    """工作日志表：存储用户工作记录信息，包含用户名、工作日期、时长、内容等字段"""
    __tablename__ = "work_log"  # 数据库中表的名称，不可重复

    # 主键：UUID格式，自动生成，唯一标识每条工作记录
    id = Column(UUID(as_uuid=True), primary_key=True, default=uuid.uuid4)
    # 用户名：最长50个字符，存储提交日志的用户名称
    user_name = Column(String(50))
    # 工作日期：日期类型，存储工作的具体日期（格式：YYYY-MM-DD）
    work_date = Column(Date)
    # 工作时长：数值类型，保留2位小数（例如8.5表示8小时30分钟）
    work_hours = Column(Numeric(5, 2))
    # 工作内容：长文本类型，存储详细的工作内容描述
    content = Column(Text)
    # 额外数据：JSONB格式，灵活存储额外信息（如项目ID、任务类型等）
    extra_data = Column(JSONB)

5. app/schemas.py（接口数据格式校验）

在backend/app目录下创建「schemas.py」，内容如下（校验前端请求参数和后端响应格式，避免非法数据）：

python 复制代码

# app/schemas.py
from pydantic import BaseModel
from typing import Optional, Dict
from datetime import date

class WorkLogCreate(BaseModel):
    """创建工作日志的请求数据格式：校验前端提交的参数合法性"""
    user_name: str               # 用户名（必填，字符串类型）
    work_date: date              # 工作日期（必填，日期类型，格式YYYY-MM-DD）
    work_hours: float            # 工作时长（必填，浮点型，如8.5）
    content: Optional[str] = None# 工作内容（可选，字符串类型，默认值为None）
    extra_data: Optional[Dict] = None  # 额外数据（可选，JSON格式，默认值为None）

class WorkLogOut(WorkLogCreate):
    """查询工作日志的响应数据格式：返回给前端的数据结构（继承创建格式，新增ID字段）"""
    id: str  # 工作记录ID（返回给前端，用于唯一标识每条记录）

6. app/crud.py（数据库CRUD操作逻辑）

在backend/app目录下创建「crud.py」，内容如下（封装数据库增删改查操作，供接口调用）：

python 复制代码

# app/crud.py
from sqlalchemy.orm import Session
from app import models, schemas

def create_worklog(db: Session, data: schemas.WorkLogCreate):
    """创建工作日志：将前端提交的合法数据存入数据库"""
    # 将Pydantic模型数据转换为数据库模型对象（**data.dict()自动解包参数**）
    db_worklog = models.WorkLog(**data.dict())
    # 将对象添加到数据库会话（暂存，未提交到数据库）
    db.add(db_worklog)
    # 提交事务（将数据永久写入数据库）
    db.commit()
    # 刷新对象（获取数据库自动生成的ID等字段，同步到对象中）
    db.refresh(db_worklog)
    # 返回创建后的对象（供接口返回给前端）
    return db_worklog

def list_worklogs(db: Session):
    """查询所有工作日志：从数据库中获取所有工作记录并返回"""
    return db.query(models.WorkLog).all()

7. app/main.py（项目启动入口，最关键文件）

在backend/app目录下创建「main.py」，内容如下（项目启动核心文件，包含接口路由、依赖注入等）：

python 复制代码

# app/main.py
from fastapi import FastAPI, Depends
from sqlalchemy.orm import Session
from app.database import SessionLocal, engine
from app import models, schemas, crud

# 初始化数据库：第一次启动服务时，自动创建所有数据表（models中定义的表）
models.Base.metadata.create_all(bind=engine)

# 创建FastAPI应用实例（项目核心对象，配置接口文档标题和描述）
app = FastAPI(title="Report Platform", description="工作日志上报平台后端API服务")

def get_db():
    """依赖注入函数：获取数据库会话，每次请求独立创建和关闭会话"""
    db = SessionLocal()
    try:
        yield db  # 向接口提供数据库会话
    finally:
        db.close()  # 请求结束后，关闭会话，释放资源

@app.get("/")
def root():
    """根接口：测试服务是否正常运行"""
    return {"msg": "backend running"}

@app.post("/worklogs", response_model=schemas.WorkLogOut)
def create_worklog(
    data: schemas.WorkLogCreate, 
    db: Session = Depends(get_db)
):
    """创建工作日志接口（POST请求）：接收前端数据，调用CRUD函数存入数据库"""
    return crud.create_worklog(db, data)

@app.get("/worklogs", response_model=list[schemas.WorkLogOut])
def list_worklogs(db: Session = Depends(get_db)):
    """查询所有工作日志接口（GET请求）：调用CRUD函数，返回所有工作记录"""
    return crud.list_worklogs(db)

五、数据库配置（仅需执行1句SQL，完整步骤）

项目启动前，必须先在PostgreSQL中创建项目专用数据库，步骤如下：

打开PostgreSQL客户端（如pgAdmin、psql命令行工具）；
登录PostgreSQL（用户名默认postgres，密码默认postgres，若已修改请使用修改后的密码）；
执行以下SQL语句，创建数据库（数据库名称必须为report_platform，与config.py配置一致）：

sql 复制代码

CREATE DATABASE report_platform;

重要提示：数据表无需手动创建！第一次启动FastAPI服务时，会自动根据models.py中的定义创建work_log表。

六、项目启动步骤（严格按顺序执行，一次成功）

以下步骤完整无缺失，严格按照顺序执行，可确保项目正常启动，适配Windows/Linux/Mac所有系统：

步骤1：创建并激活虚拟环境（仅需执行1次）

打开终端（Windows：CMD/PowerShell/Anaconda Prompt；Linux/Mac：终端）；
进入后端项目根目录（即backend文件夹所在目录，例如：cd D:\projects\backend）：
cd backend
创建Python虚拟环境（环境名称为venv，默认创建在backend目录下）：
python -m venv venv
激活虚拟环境（激活成功后，终端前缀会显示「(venv)」）：

Windows系统（CMD/PowerShell）：
venv\Scripts\activate
Linux/Mac系统：
source venv/bin/activate

步骤2：安装项目依赖（激活虚拟环境后执行）

在激活虚拟环境的终端中，执行以下命令，自动安装requirements.txt中的所有依赖：

bash 复制代码

pip install -r requirements.txt

安装成功提示：所有依赖包显示"Successfully installed"，无报错信息。

步骤3：启动项目服务

在激活虚拟环境的终端中，执行以下命令启动FastAPI服务：

bash 复制代码

uvicorn app.main:app --reload

参数说明：

app.main:app：指定启动入口（app文件夹→main.py文件→app实例）；
--reload：热重载模式，修改代码后自动重启服务（开发环境专用，生产环境可删除此参数）。

步骤4：验证服务启动成功

服务启动成功后，终端会输出以下信息（无报错，显示访问地址）：

bash 复制代码

Uvicorn running on http://127.0.0.1:8000 (Press CTRL+C to quit)
Watching for file changes with StatReload

此时，服务已正常启动，本地访问地址：http://127.0.0.1:8000

步骤5：接口测试（两种方式，完整操作）

服务启动后，可通过以下两种方式测试接口，确保接口正常可用：

方式1：使用FastAPI自动生成的接口文档（无需额外工具）

打开任意浏览器，访问接口文档地址：
http://127.0.0.1:8000/docs
在文档页面中，找到「/worklogs」接口（POST方法，创建工作日志）；
点击接口右侧的「Try it out」按钮（展开测试界面）；
在「Request body」中填写JSON格式测试数据（示例如下），可直接复制修改：
{ "user_name": "测试用户", "work_date": "2026-02-04", "work_hours": 8.0, "content": "测试FastAPI接口，创建工作日志", "extra_data": {"project_name": "工作日志平台", "task_id": "TEST-001"} }
点击「Execute」按钮，发送请求；
若返回「200 OK」状态码和创建的日志数据，则接口正常；
测试查询接口：找到「/worklogs」接口（GET方法），点击「Try it out」→「Execute」，可返回所有创建的工作日志。

方式2：使用Apifox测试（推荐，团队协作更高效）

打开Apifox工具（新建项目或进入现有项目）；
点击左侧「接口管理」→ 顶部「导入」→ 选择「URL导入」；
在「URL」输入框中，填入FastAPI自动生成的OpenAPI文档地址：
http://127.0.0.1:8000/openapi.json
点击「确定」，Apifox会自动导入所有接口（含请求参数、响应格式、数据校验规则）；
导入完成后，选择任意接口（如POST /worklogs），填写测试数据，点击「发送」即可测试；
Apifox界面参考：

七、Git配置文件（完整无缺失，直接使用）

以下两个Git配置文件放在项目根目录（与backend文件夹同级），用于规范Git提交格式、忽略无用文件，避免团队协作冲突，完整保留所有配置项。

1. .gitattributes（规范文件格式，统一跨平台行为）

gitattributes 复制代码

##############################################################################
# 1. 全局通用配置：统一换行符规范，适配所有平台 Windows/macOS/Linux
##############################################################################
# 自动识别文本文件和二进制文件，提交时统一转为LF，检出时适配系统
*               text=auto

# 强制指定以下文本文件使用LF换行（标准化配置，避免跨平台格式冲突）
*.text          eol=lf
*.md            eol=lf
*.json          eol=lf
*.yaml          eol=lf
*.yml           eol=lf
*.toml          eol=lf
*.conf          eol=lf
*.env.example   eol=lf
*.gitignore     eol=lf
*.gitattributes  eol=lf

##############################################################################
# 2. 前端 Vue3 专项配置（frontend/ 目录下所有前端相关文件，预留前端集成）
##############################################################################
# 核心代码文件（文本格式，LF换行）
frontend/**/*.vue       text eol=lf
frontend/**/*.js         text eol=lf
frontend/**/*.ts         text eol=lf
frontend/**/*.jsx        text eol=lf
frontend/**/*.tsx        text eol=lf
frontend/**/*.html       text eol=lf
# 样式文件（文本格式，LF换行）
frontend/**/*.css        text eol=lf
frontend/**/*.scss       text eol=lf
frontend/**/*.less       text eol=lf
# 配置文件（文本格式，LF换行，依赖锁文件合并冲突时保留本地版本）
frontend/**/.eslintrc.*  text eol=lf
frontend/**/prettierrc.* text eol=lf
frontend/**/vite.config.* text eol=lf
frontend/**/package.json text eol=lf
frontend/**/pnpm-lock.yaml text eol=lf merge=ours
frontend/**/yarn.lock    text eol=lf merge=ours
frontend/**/package-lock.json text eol=lf merge=ours

# 前端二进制资源（禁止换行转换，不做文本diff对比，避免文件损坏）
frontend/**/*.png        -text diff=binary
frontend/**/*.jpg        -text diff=binary
frontend/**/*.jpeg       -text diff=binary
frontend/**/*.gif        -text diff=binary
frontend/**/*.svg        text eol=lf  # SVG为文本格式，可正常diff对比
frontend/**/*.ico        -text diff=binary
frontend/**/*.woff       -text diff=binary
frontend/**/*.woff2      -text diff=binary
frontend/**/*.ttf        -text diff=binary
frontend/**/*.eot        -text diff=binary

# 前端构建产物/第三方依赖（标记为生成文件，GitHub不统计代码量）
frontend/dist/**         linguist-generated=true
frontend/node_modules/** linguist-vendored=true

##############################################################################
# 3. 后端 Python (FastAPI) 专项配置（backend/ 目录下所有后端文件）
##############################################################################
# Python 核心代码（文本格式，LF换行，支持Python语法diff对比）
backend/**/*.py          text eol=lf diff=python
backend/**/*.pyi         text eol=lf
# Python 依赖/环境配置（文本格式，LF换行，依赖锁文件合并冲突时保留本地版本）
backend/**/requirements.txt    text eol=lf
backend/**/pyproject.toml      text eol=lf
backend/**/poetry.lock         text eol=lf merge=ours
backend/**/Pipfile             text eol=lf
backend/**/Pipfile.lock        text eol=lf merge=ours

# Python 缓存/虚拟环境（标记为第三方/生成文件，忽略代码统计）
backend/**/__pycache__/**      linguist-generated=true
backend/**/.venv/**            linguist-vendored=true
backend/**/venv/**             linguist-vendored=true
backend/**/env/**              linguist-vendored=true

# 日志/临时数据文件（日志为文本格式，数据库文件为二进制，禁止diff对比）
backend/**/*.log         text eol=lf linguist-generated=true
backend/**/*.sqlite       -text diff=binary
backend/**/*.db           -text diff=binary

##############################################################################
# 4. 大文件管理 Git LFS 配置（可选，用于大于100MB的资源文件）
##############################################################################
# 若项目包含视频、模型文件、大型压缩包等，需先安装Git LFS，再启用以下规则
#*.zip           filter=lfs diff=lfs merge=lfs -text
#*.rar           filter=lfs diff=lfs merge=lfs -text
#*.mp4           filter=lfs diff=lfs merge=lfs -text
#*.h5            filter=lfs diff=lfs merge=lfs -text
#*.ckpt          filter=lfs diff=lfs merge=lfs -text

##############################################################################
# 5. 合并冲突优化：锁文件强制保留本地版本，避免依赖冲突
##############################################################################
# merge=ours 表示合并冲突时，自动保留当前分支的文件，适用于依赖锁文件
[merge "ours"]
    driver = true

2. .gitignore（忽略无用文件，减小仓库体积）

gitignore 复制代码

# ==============================================
# 全局通用忽略规则（系统/编辑器缓存，全项目生效）
# ==============================================
# 系统缓存文件（Windows/macOS系统自动生成，无需提交）
.DS_Store
.DS_Store?
._*
.Spotlight-V100
.Trashes
ehthumbs.db
Thumbs.db

# 编辑器/IDE 配置文件（适配VS Code、IDEA、Sublime等，无需提交）
.idea/
.vscode/
*.swp
*.swo
*~
.project
.c9/
*.launch

# 环境变量敏感文件（核心：禁止提交真实密钥、数据库密码等敏感信息）
.env
.env.local
.env.development.local
.env.test.local
.env.production.local
.env.*.local

# 日志/临时文件（自动生成，无需提交）
*.log
logs/
tmp/
temp/
*.tmp

# ==============================================
# 前端 Vue3 (Vite) 专用忽略规则（适配frontend/目录，预留前端集成）
# ==============================================
# 依赖包（体积大，可通过package.json重新安装，无需提交）
frontend/node_modules/

# 构建打包产物（自动生成，无需提交，部署时重新构建）
frontend/dist/
frontend/build/

# 前端缓存文件（自动生成，无需提交）
frontend/.cache/
frontend/.vite/
frontend/.eslintcache
frontend/.stylelintcache

# 测试覆盖率文件（自动生成，无需提交）
frontend/coverage/

# ==============================================
# 后端 Python (FastAPI) 专用忽略规则（适配backend/目录）
# ==============================================
# Python 字节码缓存（自动生成，无需提交）
backend/**/__pycache__/
backend/**/*.py[cod]
backend/**/*$py.class
backend/**/.Python

# 虚拟环境（自动生成，可重新创建，无需提交）
backend/.venv/
backend/venv/
backend/env/
backend/ENV/
backend/.env/

# 依赖安装缓存（自动生成，无需提交）
backend/*.egg-info/
backend/.eggs/
backend/dist/
backend/build/
backend/*.egg

# 数据库文件（本地测试库，禁止提交，避免数据冲突）
backend/*.db
backend/*.sqlite3
backend/*.sql

# 测试/覆盖率文件（自动生成，无需提交）
backend/htmlcov/
backend/.coverage
backend/.pytest_cache/

# Mypy 类型检查缓存（自动生成，无需提交）
backend/.mypy_cache/