第01章：AI帮我搭Python项目结构，但它漏掉了什么？

“AI给了你一个项目骨架，但骨架和能跑的代码之间，还差一个能打的开发者。”

ℹ️ 版本说明：本章基于 Python 3.14.5（2026年6月最新稳定版）、uv 0.7.x 包管理器、FastAPI 0.115.x 框架。版本说明中的工具链命令以此为准。

1.1 AI默认会生成什么

你打开 Claude Code 或 Cursor，输入：

“帮我创建一个 Python Web 项目，使用 FastAPI，包含用户认证功能”

AI 会给你一个看起来还不错的项目结构：

my-project/
├── main.py
├── requirements.txt
├── models.py
├── routes/
│   ├── users.py
│   └── auth.py
└── database.py

requirements.txt 里会有：

fastapi
uvicorn
sqlalchemy
pydantic
python-jose
passlib

main.py 会长这样：

from fastapi import FastAPI
from routes import users, auth

app = FastAPI()
app.include_router(users.router)
app.include_router(auth.router)

它能跑。 你运行 pip install -r requirements.txt && python main.py，确实能启动。

然后你部署到服务器，两周后收到用户反馈：登录突然坏了。你查日志，发现是 python-jose 的某个版本和 cryptography 不兼容。你花了三个小时解决一个跟业务完全无关的依赖冲突问题。

这是因为 AI 给你的项目结构在原型阶段够用，但没有为生产做准备。

1.2 AI通常遗漏的5个坑

⚠️ 坑1：requirements.txt 没有锁定版本

AI 生成的 requirements.txt 通常只写包名，不写版本号：

fastapi
uvicorn
sqlalchemy

后果：每次 pip install 都可能装到不同版本。在你电脑上能跑的代码，在 CI 环境或生产服务器上可能因版本差异报错。这是 Python 项目"在我机器上能跑"问题的根本原因之一。

正确做法：使用 uv 或 pip-tools 生成带哈希锁定的 requirements.lock，或使用 pyproject.toml + uv.lock。

⚠️ 坑2：没有 `.python-version` 或运行时声明

AI 不会帮你声明这个项目需要哪个 Python 版本。你用 Python 3.14 开发，同事用 Python 3.11，服务器装的是 Python 3.9。

Python 3.10 引入了 match-case 语句，Python 3.12 改了 f-string 解析，Python 3.13 加入了 JIT 编译器，Python 3.14 引入了免费线程模式（free-threaded mode）——版本不同，相同代码的行为可能截然不同。

正确做法：在项目根目录添加 .python-version 文件（内容就是 3.14），或在 pyproject.toml 中声明 requires-python = ">=3.14"。

⚠️ 坑3：没有环境变量管理

AI 生成的代码里，数据库 URL、密钥、API Token 通常是硬编码的或者只用了 os.getenv()，但没有：

默认值的说明
缺失时的明确报错
.env.example 文件（让协作者知道需要配置哪些变量）
生产环境和开发环境的隔离

你把代码推到 GitHub，密钥被扫描工具发现，账号被盗用——这不是假设，而是每天都在发生的事故。

正确做法：使用 pydantic-settings 创建类型安全的配置类，强制要求关键变量必须存在。

⚠️ 坑4：没有日志配置

AI 生成的项目里，日志通常是这样的：

print("用户登录成功")
print(f"错误: {e}")

生产环境里，你需要的是结构化日志、日志级别、日志旋转、追踪 ID——这些 print 都给不了。

后果：出了问题你完全不知道发生了什么，只能靠猜。

⚠️ 坑5：项目结构不适合团队协作

AI 倾向于生成扁平的结构，把所有东西堆在根目录里。当项目增长到20个文件时，你会发现：

models.py 里有500行
routes/users.py 里混杂着业务逻辑、数据库查询、验证逻辑
没有 services/ 层，导致逻辑复用困难
没有 schemas/ 和 models/ 的分离，Pydantic schema 和 SQLAlchemy model 混在一起

正确做法：采用分层架构，把路由、业务逻辑、数据访问分离。

1.3 更好的提示词

提示词 P01：带版本锁定的 Python 项目初始化

使用时机：开始一个新 Python 项目时

比默认多了什么：

明确指定 Python 3.14 + uv 工具链
要求 pyproject.toml 而不是 requirements.txt
要求声明 Python 版本约束
要求创建 .env.example

帮我用 Python 3.14 和 uv 包管理器初始化一个 FastAPI 项目。

要求：
1. 使用 pyproject.toml 管理依赖，不要用 requirements.txt
2. 在 pyproject.toml 中设置 requires-python = ">=3.14"
3. 创建 .python-version 文件，内容为 3.14
4. 创建 .env.example，列出所有需要的环境变量及说明
5. 添加 uv.lock 到 .gitignore 的排除列表以外（即 uv.lock 应该提交到版本控制）
6. 项目结构采用分层架构：
   - app/api/（路由层）
   - app/services/（业务逻辑层）
   - app/repositories/（数据访问层）
   - app/schemas/（Pydantic v2 schema）
   - app/models/（SQLAlchemy 2.x ORM 模型）
   - app/core/（配置、安全、日志等基础设施）

给我完整的初始化步骤和所有文件内容。

AI 输出示例（关键部分）：

# pyproject.toml
[project]
name = "my-project"
version = "0.1.0"
requires-python = ">=3.14"
dependencies = [
    "fastapi>=0.115.0",
    "uvicorn[standard]>=0.32.0",
    "sqlalchemy>=2.0.0",
    "pydantic>=2.0.0",
    "pydantic-settings>=2.0.0",
]

提示词 P02：带 pydantic-settings 的类型安全配置

使用时机：需要管理环境变量和配置时

比默认多了什么：

强制类型验证，缺失的必填变量启动时报错
开发/生产环境分离
敏感字段自动脱敏（不会出现在日志里）

为我的 Python 3.14 / FastAPI 项目创建一个使用 pydantic-settings 的配置系统。

要求：
1. 使用 pydantic-settings v2，BaseSettings 子类
2. 区分必填变量（无默认值，缺失时启动报错）和可选变量（有默认值）
3. DATABASE_URL 和 SECRET_KEY 是必填的
4. 使用 SecretStr 类型保护密钥字段，防止日志泄露
5. 支持从 .env 文件读取（开发环境）
6. 在 app/core/config.py 中实现，导出一个 settings 单例
7. 创建对应的 .env.example 文件

同时告诉我怎么在 FastAPI 的 lifespan 事件里验证配置是否完整。

提示词 P03：为现有 AI 生成的项目补充生产就绪结构

使用时机：AI 已经生成了初版代码，你想让它"升级"为可上线状态

比默认多了什么：

不推翻已有代码，而是补充缺失的生产要素
明确要求结构化日志
要求 Makefile 简化常用命令

我有一个 AI 生成的 FastAPI 项目，基本功能已经实现，但缺少生产就绪的基础设施。请帮我补充以下内容，不要修改已有的业务逻辑：

1. 结构化日志：使用 structlog 库，每条日志包含 timestamp、level、request_id、user_id（如果有认证的话）
2. 健康检查端点：GET /health 返回 {"status": "ok", "version": "xxx", "python": "3.14.x"}
3. Makefile：包含 make dev（启动开发服务器）、make test（运行测试）、make lint（ruff检查）、make format（ruff format）
4. .gitignore：完整的 Python 项目 .gitignore，包含 uv 相关文件
5. Dockerfile：多阶段构建，基于 python:3.14-slim，使用 uv 安装依赖，非 root 用户运行

基于 Python 3.14 + uv 0.7.x 生成。

1.4 验收清单

在把 AI 生成的 Python 项目结构推到仓库之前，检查以下项目：

检查项	验证方法	AI辅助
Python 版本已声明	存在 `.python-version` 文件	让 AI 检查并添加
依赖版本已锁定	存在 `uv.lock` 或 `requirements.lock`	运行 `uv lock` 生成
无硬编码密钥	`grep -r "password\|secret\|token" --include="*.py"` 无直接赋值	让 AI 扫描并替换为环境变量
存在 `.env.example`	根目录有 `.env.example`	让 AI 根据代码生成
日志不是 print	搜索 `print(` 在业务代码中的使用	让 AI 替换为 logging/structlog
项目分层清晰	路由、服务、数据访问分离	让 AI 重构为分层结构
`.gitignore` 完整	包含 `.env`、`__pycache__`、`.venv`	使用 gitignore.io 生成

1.5 本章小结

如果你只记一件事：AI 帮你搭的 Python 项目结构是个能跑的原型，而不是一个能活下去的生产系统。差距在于版本锁定、配置管理、日志基础设施这三块"看不见的脚手架"。

三个立即可用的行动：

用 uv 替换 pip：在新项目里一律用 uv init 初始化，uv add 添加依赖，告别 requirements.txt 版本混乱
强制配置验证：项目启动时如果缺少必要环境变量，应该立即报错退出，而不是在运行中悄悄出问题
要求 AI 生成 .env.example：每次让 AI 写涉及配置的代码，都追加一句"同时更新 .env.example"

本章给了你一个健壮的项目起点。下一章，我们来看 AI 生成的依赖管理——那个看起来很平常的 requirements.txt，在生产环境里是怎么把你搞死的。

→ 第2章：AI生成的依赖管理，上线后会爆炸吗？

第01章：AI帮我搭Python项目结构，但它漏掉了什么？

第01章：AI帮我搭Python项目结构，但它漏掉了什么？

1.1 AI默认会生成什么

1.2 AI通常遗漏的5个坑

⚠️ 坑1：requirements.txt 没有锁定版本

⚠️ 坑2：没有 .python-version 或运行时声明

⚠️ 坑3：没有环境变量管理

⚠️ 坑4：没有日志配置

⚠️ 坑5：项目结构不适合团队协作

1.3 更好的提示词

提示词 P01：带版本锁定的 Python 项目初始化

提示词 P02：带 pydantic-settings 的类型安全配置

提示词 P03：为现有 AI 生成的项目补充生产就绪结构

1.4 验收清单

1.5 本章小结

⚠️ 坑2：没有 `.python-version` 或运行时声明