• 示例工程
• 教程

本文是围绕仓库 README.md 主干结构整理而成的技术指南：它把"基础语法 → 进阶编程 → FastAPI 后端 → MongoDB → Vercel 部署"整条学习路线映射到仓库中真实可运行的代码目录，并补充源码级实现细节，帮助初学者与希望系统复习 Python 的开发者快速定位每个知识点的教学视频与配套代码。读完本文，你将掌握该项目的完整目录结构、每条学习路线的核心知识点清单，以及如何在本机运行和部署 FastAPI 后端。

1. 项目概览：一门在直播中完成的免费 Python 课程

Hello-Python 是一个面向零基础初学者的 Python 课程仓库，课程内容在直播过程中逐步沉淀为代码与视频。README 明确指出这是一门"从零开始、面向初学者的 Python 编程语言课程"，课程总规模约为 100 节课、44 小时视频内容，覆盖Fundamentos（基础）、Intermediate（进阶）、Backend（后端）、Testing（测试）、IA（人工智能）等主题。

仓库对技术栈给出了明确的版本基线：

项目代码组织为三个主目录，分别对应三条学习路线：

• Basic/ —— 基础语法课程，15 个主题由浅入深；
• Intermediate/ —— 进阶课程，覆盖日期、推导式、lambda、错误处理、文件、正则、包管理等；
• Backend/ —— 用 Python 实现后端 REST API，包含认证、数据库与云部署。

课程状态说明（引自 README）：目前课程处于暂停状态，基础、进阶、后端三个模块已全部完成，这正是项目最初的目标；仓库作者不排除未来继续追加新课程。

2. 基础路线：15 个主题的入门代码

README 将基础课程的视频入口指向一个完整的直播合集，并注明对应代码位于Basic 目录。该目录以编号命名，与视频课程逐一对应：

这一部分的阅读建议是：每个文件都短小精悍，恰好覆盖一个语法主题，适合"看一节视频、跑一个脚本"的节奏。例如13_modules.py配合my_module.py演示了 Python 模块的导入机制，这是理解后续包管理与大型项目组织的基础。

3. 进阶路线：从日期到正则表达式

进阶课程视频合集同样对应一个独立目录Intermediate，并引入了第一个自定义包 mypackage/（含init.py 与 arithmetics.py），用于演示 Python 包的组织方式。

目录中还附带三个示例数据文件，供文件处理课程练习使用：my_file.csv、my_file.json、my_file.txt。练习文件读写时，可以对照06_file_handling.py中对应的 CSV、JSON、文本读取逻辑进行验证。

4. 后端路线：用 FastAPI 构建完整 REST API

README 将后端课程定义为："用 Python 做后端，实现带认证、数据库的 REST API，并部署到真实服务器"，对应代码位于Backend 目录。这部分是仓库中信息密度最高的模块，下面结合源码逐层展开。

4.1 应用入口与路由组织

Backend/FastAPI/main.py 是整条后端路线的入口文件，其组装逻辑清晰对应课程节奏：

• 创建FastAPI()实例；
• 通过app.include_router(...)挂载 5 个功能路由模块；
• 通过app.mount("/static", StaticFiles(directory="static"), name="static")提供静态资源服务（对应视频中"Recursos estáticos"一课，静态图片位于 Backend/FastAPI/static/images/python.jpg）；
• 提供两个演示路由GET /（返回字符串"Hola FastAPI!"）与GET /url（返回 JSON），其中GET /url就是第一个用 Pydantic 校验响应结构的示例。

入口文件中还给出了本机运行与调试的关键命令：

# 安装依赖 pip install "fastapi[all]" # 启动开发服务器（支持热重载） uvicorn main:app --reload # 停止服务器 CTRL+C # 交互式 API 文档 # Swagger UI: http://127.0.0.1:8000/docs # ReDoc: http://127.0.0.1:8000/redoc

4.2 从内存数据到路径参数：products 与 users 路由

products 路由（routers/products.py）展示了APIRouter的基本用法：定义prefix="/products"与tags=["products"]，用内存列表products_list提供GET /products/全量查询，以及GET /products/{id}按整数下标查询，并演示了responses={404: ...}自定义错误响应。

users 路由（routers/users.py）则完整覆盖了 REST 的核心动作，是学习 HTTP 方法的最佳样例：

• GET /usersjson：手工构造 JSON 列表返回；
• GET /users：返回由 Pydantic 模型User组成的列表；
• GET /user/{id}（Path 参数）与GET /user/（Query 参数）两种取值方式，通过search_user(id)查询；
• POST /user/：以response_model=User, status_code=201声明创建语义，若用户已存在则抛出HTTPException(404, "El usuario ya existe")；
• PUT /user/：按id更新内存列表中的元素，未找到时返回错误字典；
• DELETE /user/{id}：删除指定元素。

其中search_user使用filter(lambda user: user.id == id, users_list)配合异常捕获实现查找，展示了 lambda 在真实业务中的落地写法。

4.3 两种认证方案：OAuth2 基础认证与 JWT

后端课程包含两条认证路线，源码位于 routers/basic_auth_users.py 与 routers/jwt_auth_users.py。

方案一：OAuth2 基础认证（对应"Autorización OAuth2"一课）

• 通过OAuth2PasswordBearer(tokenUrl="login")声明令牌获取地址；
• POST /basicauth/login接收OAuth2PasswordRequestForm表单（username/password），校验通过后返回{"access_token": username, "token_type": "bearer"}，即用用户名本身充当令牌（教学简化实现）；
• GET /basicauth/users/me通过Depends(current_user)保护：current_user先解析令牌得到用户，再检查disabled状态，未认证返回 401，禁用用户返回 400。

方案二：OAuth2 JWT（对应"OAuth2 JWT"一课）

• 引入python-jose与passlib（配合 bcrypt）两个核心库，配置常量ALGORITHM = "HS256"、ACCESS_TOKEN_DURATION = 1（分钟）与SECRET密钥；
• login使用crypt.verify(form.password, user.password)对 bcrypt 哈希口令做校验（仓库中users_db存的是$2a$12$...格式的 bcrypt 密文，而非明文）；
• 登录成功后构造 payload{"sub": username, "exp": now + timedelta(minutes=1)}，用jwt.encode(..., algorithm="HS256")签发令牌；
• auth_user依赖通过jwt.decode(token, SECRET, algorithms=[ALGORITHM])解析并校验签名，捕获JWTError统一返回 401；current_user再叠加禁用状态检查。

两条路线形成清晰的对比：基础认证适合演示流程，JWT 方案展示了真实项目中的令牌签发、签名校验与过期机制，且两者都依赖Depends()依赖注入体系。

4.4 连接 MongoDB：模型、Schema 与 CRUD

后端课程的数据库部分由三个文件协作完成：

• db/models/user.py：Pydantic 模型User，字段为id: Optional[str]、username: str、email: str，id可选以兼容 MongoDB 自动生成的_id；
• db/schemas/user.py：user_schema/users_schema两个转换函数，把 Mongo 文档映射为{"id": str(user["_id"]), "username": ..., "email": ...}的 Python 字典；
• db/client.py：基于pymongo的客户端。本地模式为db_client = MongoClient().local（连接mongodb://localhost），远程模式可切换为 MongoDB Atlas 的mongodb+srv://<user>:<password>@<url>/...连接串，注释中提供了社区版下载、安装与sudo mongod --dbpath ...启动说明。

在此基础上，routers/users_db.py 实现了数据库版 CRUD：

• GET /userdb/：users_schema(db_client.users.find())全量查询；
• GET /userdb/{id}：用ObjectId(id)按 MongoDB 主键查询；
• POST /userdb/：先按 email 查重（存在则抛 404），再insert_one并回读新文档，status_code=201返回创建结果；
• PUT /userdb/：find_one_and_replace按_id整体替换；
• DELETE /userdb/{id}：find_one_and_delete，未找到时返回错误字典。

建议按client.py → models/user.py → schemas/user.py → routers/users_db.py的顺序阅读，即可完整还原"连接数据库 → 定义模型 → 文档与模型互转 → 路由 CRUD"的完整链路。

4.5 生产部署：Vercel 配置与安全注意事项

README 特别标注了部署环节的更新：原课程使用的Deta 服务已不存在，推荐改用 FastAPI 官方文档中的部署方案，并给出了在 Vercel 部署所需的两个文件：

• Backend/FastAPI/vercel.json：Vercel 构建与路由配置，builds指定main.py由@vercel/python构建，routes将所有请求/(.*)转发到main.py；
• Backend/FastAPI/requirements.txt：依赖清单fastapi[standard]、python-jose、passlib、bcrypt、pymongo。

在 Vercel 平台创建项目时，需将根目录指向Backend/FastAPI。同时，db/client.py 的注释对生产部署给出了明确的安全建议：

• 永远不要把敏感变量值提交到公开仓库；
• 可使用dotenv管理本地环境变量；
• 在托管平台侧配置环境变量（如 SECRET 密钥、MongoDB Atlas 连接串）。

换言之，仓库中的SECRET与users_db中的密码仅供本地教学演示，线上必须通过环境变量注入真实密钥。

4.6 配套支撑：Type Hints 与 AI 集成课

在后端路线中，README 提到一课Type Hints（类型提示），对应 Backend/type_hints.py：该脚本演示了str类型标注的变量在运行时依然可以重新赋值为整数（如my_typed_variable: str = "..."后赋值5），直观说明Python 类型提示是给开发者与工具看的"文档"，而非运行时强制约束——这是理解 FastAPI 中 Pydantic 类型校验为何独立存在的重要背景。

此外，README 还列出两条 AI 相关课程："从零开始把 ChatGPT 集成进你的项目"（1 小时课程，演示对话与上下文设定）与"AI 语音翻译器"（约 100 行代码实现多语言语音翻译 Web 应用）。这两部分代码以课程作者公开发布的形式提供，仓库内不包含对应源码文件。

5. 测试入门与其他内容

README 提及一门与测试专家合作的"Python 测试入门工作坊"，作为课程体系的补充模块；另有"Python 的 15 个冷知识"趣味内容，适合作为学习间隙的扩展。需要说明的是，这两个主题在仓库中同样没有对应代码目录，仅作为视频课程存在。

6. 学习路径总览与快速上手

综合 README 与仓库结构，可以梳理出一条完整的自学路径：

1. 入门：按编号顺序运行 Basic/ 下的 15 个脚本，建立语法基础；
2. 进阶：学习 Intermediate/ 的 9 个主题，重点掌握列表推导式、lambda、高阶函数、文件与正则；
3. 后端：先看 Backend/type_hints.py 理解类型提示，再按main.py → routers/ → db/的顺序阅读 FastAPI 工程；本机运行uvicorn main:app --reload后用http://127.0.0.1:8000/docs交互调试接口；
4. 数据层：本地安装 MongoDB 后切换 db/client.py 的本地连接，逐条验证 routers/users_db.py 的增删改查；
5. 部署：参照 vercel.json 与 requirements.txt，将根目录设为Backend/FastAPI后在 Vercel 发布，并牢记用环境变量保护密钥。

整个仓库的价值在于：每个视频知识点都对应一段可直接运行的代码，配合 README 中的视频时间戳，即可实现"看课 → 跑码 → 改造"的闭环学习，这也是该项目作为零基础 Python 课程的核心设计。

• 示例工程
• 教程