职责单一
每一层只做一类事情，路由不写业务细节，业务不直接暴露给外部请求。
FastAPI 分层架构
FastAPI 入门阶段可以先把代码写在一个 main.py 里，但项目一旦变复杂，就需要拆分目录和职责。分层架构的目标，是把复杂应用拆成多个清晰层次，每一层只负责一类事情。
什么是分层架构
Section titled “什么是分层架构”分层架构就是把复杂的应用逻辑拆成多个独立层次，每一层专注于单一职责，实现“分而治之”。
易于维护
修改某一层逻辑时，尽量不影响其他层级的功能。
代码复用
通用业务逻辑、校验模型、数据操作可以被多个接口复用。
便于排查
系统出错时，可以快速判断问题来自路由、参数校验、业务处理还是数据访问。
生活里可以类比餐厅分工：服务员负责接待，配菜师负责备菜，厨师负责烹饪，采购员负责采购。每个人职责明确，整体才更容易高效运转。
为什么要分层
Section titled “为什么要分层”如果所有逻辑都写在一个文件里，项目刚开始会显得很快，但后期会越来越难改。
| 问题 | 单文件写法的表现 | 分层后的改善 |
|---|---|---|
| 职责混在一起 | 路由、校验、业务、数据操作都堆在接口函数里 | 每层只处理自己的职责 |
| 复用困难 | 相同逻辑在多个接口里复制 | 公共逻辑抽到 service 或 crud |
| 修改风险大 | 改一段代码可能影响多个接口 | 修改范围更集中 |
| 排查困难 | 出错后不知道从哪里看 | 按层定位问题来源 |
一个基础 FastAPI 项目，可以先按四层理解：路由层、校验层、业务层、数据库层。
路由层负责接收客户端请求，根据 URL 和请求方法，把请求转发给对应的业务模块。
常见文件：app/api/user_router.py
关注点：
- 声明接口路径和请求方法
- 接收请求参数
- 调用业务层
- 返回统一响应
路由层不应该堆复杂业务逻辑。
校验层负责定义请求和响应的数据结构，验证数据的合法性和完整性。
常见文件：app/schemas/user_schema.py
关注点：
- 请求体字段定义
- 字段类型和长度规则
- 响应数据结构
- Pydantic 模型复用
校验层让外部数据先过规则，再进入业务逻辑。
业务层负责实现核心业务逻辑，协调不同模块之间的数据流转。
常见文件：app/services/user_service.py
关注点：
- 用户创建、查询、更新、删除等业务流程
- 密码加密等业务规则
- 调用数据库层完成数据读写
- 处理业务异常和边界情况
业务层是系统的核心大脑。
数据库层负责与数据存储交互，执行数据的增删改查。
常见文件：app/crud/user_crud.py
关注点：
- 新增数据
- 查询数据
- 更新数据
- 删除数据
入门实战里可以先用内存字典模拟数据库，后续再替换成真实数据库。
基础分层目录可以这样组织：
Directoryproject/
Directoryapp/
Directoryapi/ 路由层
- user_router.py
Directoryschemas/ 校验层
- user_schema.py
Directoryservices/ 业务层
- user_service.py
Directorycrud/ 数据库层
- user_crud.py
- main.py 项目入口
- requirements.txt
| 目录 | 层级 | 职责 |
|---|---|---|
api/ |
路由层 | 定义接口路径，接收请求，调用业务层 |
schemas/ |
校验层 | 定义请求 / 响应模型，做参数校验 |
services/ |
业务层 | 编写核心业务逻辑，协调数据流转 |
crud/ |
数据库层 | 封装数据增删改查 |
main.py |
项目入口 | 创建应用，注册路由，启动服务 |
三个核心原则
Section titled “三个核心原则”单一职责原则
每层只承担一类职责，确保系统结构清晰、可维护。
依赖向下原则
上层可以调用下层服务，但下层不要反向调用上层，避免循环依赖。
数据隔离原则
外部请求必须经过校验层，数据库数据必须经过业务层处理后返回。
实战案例：用户管理 API
Section titled “实战案例：用户管理 API”用户管理 API 可以作为理解分层架构的最小实战：实现用户创建和查询，并通过 Pydantic 做数据校验。
核心技术栈：
| 能力 | 工具 | 作用 |
|---|---|---|
| Web 框架 | FastAPI |
定义接口和路由 |
| 数据校验 | Pydantic |
定义请求 / 响应模型 |
| 密码加密 | passlib[bcrypt] |
对密码做哈希处理，避免明文存储 |
| 数据存储 | 内存字典 | 入门阶段模拟数据库 |
用户管理分层流程
Section titled “用户管理分层流程”-
路由层接收请求：例如
POST /users接收创建用户请求。 -
校验层检查数据：用 Pydantic 校验
username、password等字段。 -
业务层处理规则：检查用户名是否重复，对密码进行哈希加密。
-
数据库层保存数据：入门阶段先写入内存字典，后续可替换为真实数据库。
-
业务层组织返回结果：不要把密码明文或敏感信息直接返回给客户端。
AI 生成项目时的提示词
Section titled “AI 生成项目时的提示词”用 AI 辅助生成 FastAPI 项目时，提示词要明确技术栈、目录结构、约束规则和验收目标。
# 根据 FastAPI 初始化项目代码，要求如下：
1. 创建虚拟环境并激活，安装相关依赖；2. 按路由层、校验层、业务层、数据库层四层组织代码；3. 数据库层仅用内存字典模拟，不连接真实数据库；4. 实现用户信息增删改查接口，用户包含 id、username、password 字段；5. 密码使用 passlib[bcrypt] 做哈希加密，存储时不保留明文；6. 使用 Pydantic v2 做请求和响应参数校验；7. 代码简洁高效，并合理添加注释。