尧图网页设计 
1. 项目背景业务场景第 15 章交付的任务协作 API在大师眼中是合格的 Demo但在运维和架构师眼中问题重重一个main.py包含了 20 个app.include_router()调用每次新加模块都要手动在 main 里加一行忘加一次线上事故。用户模块、订单模块、支付模块、通知模块全在一个 Python 包里——某人改了User模型的email字段支付模块的序列化突然全崩了。from app.models.user import User和from app.schemas.user import UserCreate被团队三人以三种方式 importPyCharm 自动补全列出的候选多达 30 个。产品要求支付接口要同时支持 v1 和 v2 两个版本共存 6 个月——但现在的路由全部写在/api/v1/下v2 不知从哪儿下手。数据库迁移脚本alembic/versions/下已经有 15 个文件编号乱七八糟——abc123、def456、xyz789……根本不知道哪个先执行。痛点从一个能跑的 Demo 升级为可多人维护的生产工程核心挑战不是写代码而是管结构循环依赖死锁user.pyimportorder.pyorder.pyimportproduct.pyproduct.pyimportuser.py——Python 解释器直接报ImportError。全局状态泄漏某开发者在config.py写了current_tenant_id None然后在中间件里改了它。多租户场景下请求 A 的租户 ID 泄漏到了请求 B。模块爆炸新人打开项目面对 50 个顶层目录不知道从哪个文件开始看——“先读哪个依赖关系是什么”发布粒度粗所有模块打成一个 Python 包改一行支付代码要重新部署整个服务含用户模块、通知模块、45 个接口。本章不写新功能——而是把第 15 章的 Demo重构为可支撑 10 人团队协作 6 个月的生产级结构。2. 项目设计场景架构评审会。大师把第 15 章的项目结构投屏。小胖的文件夹有 12 层嵌套小白的文件关系图画得像蜘蛛网。小胖指着屏幕“我任务系统就跑 3 个模块——用户、项目、任务——搞那么多目录干嘛core/、integrations/、infrastructure/……这不就是把代码从一个大文件拆成 50 个小文件吗”小白“不是的。代码量没变但职责变了——每个文件有了明确的’责任边界’。比如app/repositories/user.py只负责数据库查询不包含业务逻辑。以后要切换从 MySQL 到 MongoDB只要改这一个文件业务层代码一行不动。”大师“小胖你还记得员工食堂和米其林后厨的区别吗食堂可能一个厨师炒三个菜但米其林后厨——洗菜岗、切菜岗、调味岗、摆盘岗各司其职。当餐厅从 30 个客人变成 300 个客人时不分工就是灾难。代码也是一样——3 个人写 3 个模块基础篇10 个人写 10 个模块中级篇结构不分工就是互相踩脚。”技术映射生产级项目结构的核心原则是按领域模块划分 统一基础设施。每个领域用户、订单、支付内部有自己独立的 API/Service/Repository/Model但共享 core配置、安全、数据库和 infrastructure缓存、消息队列、日志。小胖“那多版本 API 共存呢v1 和 v2 怎么搞”大师“有三种策略”方案实现方式优点缺点URL 前缀/api/v1/orders/api/v2/orders直观Nginx 可分别路由代码最终要有两套 RouterHeader 版本Accept: application/vnd.apijson;version2URL 干净客户端难调试双服务独立部署 v1 和 v2 两个服务完全隔离运维成本翻倍“推荐初学者用 URL 前缀——简单直观FastAPI 支持最好。”小白“循环依赖怎么解user.py需要order.py的 Order 类型order.py需要user.py的 User 类型——但 Python 把它俩放不同文件就会 import 报错。”大师三种解法TYPE_CHECKING 字符串注解from typing import TYPE_CHECKING在if TYPE_CHECKING:块内 import — 只在类型检查时生效运行时跳过。抽取共享层把 User 和 Order 都依赖的’基础类型’如ID、TimestampMixin抽到app/models/base.py。解耦 relationship删除 ORM 层之间的relationship()只保留ForeignKey— 业务关联靠字段值而非 ORM 对象。推荐组合使用——TYPE_CHECKING 解决类型提示共享层解决运行时依赖。技术映射TYPE_CHECKING是 Python 3.6 的特性它只在 mypy/pyright 类型检查时为True运行时为False。这样可以在不创建真正 import 的情况下让类型检查器知道类的存在解决循环 import 的同时保持类型安全。小胖“那 alembic 版本命名呢15 个迁移文件了都叫abc1234_xxx——哪天要回滚根本不知道哪个版本对应哪个功能。”大师迁移文件命名规范——用日期前缀 功能描述alembic/versions/ ├── 20260101_init_users_and_projects.py ├── 20260105_add_task_tags_table.py ├── 20260110_add_priority_column_to_tasks.py └── 20260115_create_index_on_task_status.py“数字前缀保证执行顺序alembic 按文件名排序功能描述一目了然。团队协作时每人按当前日期生成编号永远不会冲突。”3. 项目实战——重构任务协作 API 为生产级结构分步实现步骤一设计生产级目录结构目标可达 10 人协作的模块边界ecommerce-api/ ├── app/ │ ├── main.py # FastAPI 应用工厂函数 │ ├── bootstrap.py # 应用初始化路由注册、事件绑定 │ │ │ ├── core/ # 基础设施被所有模块依赖 │ │ ├── config.py # 统一配置 │ │ ├── database.py # SQLAlchemy Engine Session │ │ ├── security.py # JWT 密码哈希 │ │ ├── exceptions.py # 全局异常类定义 │ │ ├── response.py # 统一响应模型 APIResponse │ │ └── dependencies.py # 通用依赖分页、当前用户 │ │ │ ├── models/ # ORM 模型一个文件一个表 │ │ ├── base.py # Base TimestampMixin │ │ ├── user.py │ │ ├── product.py │ │ ├── order.py │ │ └── __init__.py # 统一导出方便 import │ │ │ ├── schemas/ # Pydantic 模型按领域分文件 │ │ ├── user.py │ │ ├── product.py │ │ ├── order.py │ │ └── common.py # 公共 Schema分页、排序 │ │ │ ├── domains/ # 领域模块核心业务⭐ │ │ ├── user/ # 用户领域 │ │ │ ├── api.py # 路由router.get/post... │ │ │ ├── service.py # 业务逻辑 │ │ │ ├── repository.py # 数据访问 │ │ │ └── __init__.py │ │ ├── product/ │ │ │ ├── api.py │ │ │ ├── service.py │ │ │ ├── repository.py │ │ │ └── __init__.py │ │ ├── order/ │ │ │ ├── api.py │ │ │ ├── service.py │ │ │ ├── repository.py │ │ │ └── __init__.py │ │ └── notification/ │ │ ├── api.py │ │ ├── service.py │ │ └── __init__.py │ │ │ ├── api/ # API 版本路由组装 │ │ ├── v1/ │ │ │ └── router.py # 收集所有 v1 领域路由 │ │ └── v2/ │ │ └── router.py # v2 版本路由预留 │ │ │ └── infrastructure/ # 外部集成可选视需要拆分 │ ├── cache.py # Redis 缓存客户端 │ ├── queue.py # 消息队列客户端第20章 │ └── storage.py # 对象存储S3/MinIO第11章进阶 │ ├── alembic/ # 数据库迁移 ├── tests/ # 测试按领域镜像 src 结构 │ ├── conftest.py │ ├── domains/ │ │ ├── user/ │ │ ├── product/ │ │ └── order/ │ └── core/ ├── pyproject.toml ├── Dockerfile └── .env.example核心设计决策domains/代替services/repositories/api/按领域垂直切分而非按层水平切分。开发者改用户模块只需关注domains/user/一个目录。models/和schemas/留在顶层因为多个领域可能共享同一个 Model如 User 被订单和通知模块同时引用抽取到顶层避免循环依赖。bootstrap.py负责组装应用入口main.py只做最小初始化路由注册交给bootstrap.py便于测试时按需组装。步骤二消除循环依赖目标使用 TYPE_CHECKING 共享基类app/models/base.pyfromdatetimeimportdatetime,timezonefromsqlalchemyimportDateTime,funcfromsqlalchemy.ormimportDeclarativeBase,Mapped,mapped_columnclassBase(DeclarativeBase):passclassTimestampMixin:所有需要时间戳的表复用此 Mixincreated_at:Mapped[datetime]mapped_column(DateTime(timezoneTrue),server_defaultfunc.now(),nullableFalse)updated_at:Mapped[datetime]mapped_column(DateTime(timezoneTrue),server_defaultfunc.now(),onupdatefunc.now(),nullableFalse)app/models/user.pyfromtypingimportTYPE_CHECKINGfromsqlalchemyimportString,Booleanfromsqlalchemy.ormimportMapped,mapped_column,relationshipfromapp.models.baseimportBase,TimestampMixinifTYPE_CHECKING:fromapp.models.orderimportOrder# 仅类型检查时 importclassUser(Base,TimestampMixin):__tablename__usersid:Mapped[int]mapped_column(primary_keyTrue,autoincrementTrue)username:Mapped[str]mapped_column(String(50),uniqueTrue,indexTrue)email:Mapped[str]mapped_column(String(200),uniqueTrue)hashed_password:Mapped[str]mapped_column(String(255))is_active:Mapped[bool]mapped_column(Boolean,defaultTrue)# relationship 使用字符串引用避免运行时 importorders:Mapped[list[Order]]relationship(back_populatesuser,lazyselectin)app/models/order.pyfromtypingimportTYPE_CHECKING# 运行时只 import ForeignKey不 import User 类fromsqlalchemyimportForeignKey,Integer,String,Numericfromsqlalchemy.ormimportMapped,mapped_column,relationshipfromapp.models.baseimportBase,TimestampMixinifTYPE_CHECKING:fromapp.models.userimportUserclassOrder(Base,TimestampMixin):__tablename__ordersid:Mapped[int]mapped_column(primary_keyTrue)user_id:Mapped[int]mapped_column(ForeignKey(users.id),indexTrue)status:Mapped[str]mapped_column(String(20),defaultpending)user:Mapped[User]relationship(back_populatesorders)步骤三实现 bootstrap.py 组装应用目标解耦 main.py 与路由注册app/bootstrap.pyfromfastapiimportFastAPIfromstarlette.middleware.corsimportCORSMiddlewarefromapp.core.configimportsettingsfromapp.core.exceptionsimportAppExceptionfromapp.core.handlersimportapp_exception_handler,global_exception_handlerfromapp.api.v1.routerimportv1_routerdefcreate_app()-FastAPI:应用工厂函数——测试时也可调用appFastAPI(titlesettings.APP_NAME,versionsettings.APP_VERSION,docs_url/api/v1/docsifnotsettings.DEBUGelse/docs,redoc_url/api/v1/redoc,)# 中间件顺序重要后注册的先执行app.add_middleware(CORSMiddleware,allow_originssettings.CORS_ORIGINS,allow_credentialsTrue,allow_methods[*],allow_headers[*],)# 路由注册app.include_router(v1_router)# 异常处理app.add_exception_handler(AppException,app_exception_handler)app.add_exception_handler(Exception,global_exception_handler)returnappapp/api/v1/router.pyfromfastapiimportAPIRouterfromapp.domains.user.apiimportrouterasuser_routerfromapp.domains.product.apiimportrouterasproduct_routerfromapp.domains.order.apiimportrouterasorder_routerfromapp.domains.notification.apiimportrouterasnotification_router v1_routerAPIRouter(prefix/api/v1)v1_router.include_router(user_router)v1_router.include_router(product_router)v1_router.include_router(order_router)v1_router.include_router(notification_router)app/main.py精简为 3 行fromapp.bootstrapimportcreate_app appcreate_app()步骤四规范化 Alembic 迁移命名目标版本链可追溯# 删除旧的杂乱版本文件从统一基线重新初始化alembic init alembic# 统一命名格式YYYYMMDD_功能描述alembic revision--autogenerate-m20260101_init_core_tables# → alembic/versions/20260101_init_core_tables.pyalembic revision--autogenerate-m20260110_add_order_table# → alembic/versions/20260110_add_order_table.py步骤五验证重构结果# 1. 确保重构后所有接口仍可访问uvicorn app.main:app--reloadcurl-shttp://localhost:8000/api/v1/health# 2. 确认无循环 importpython-cfrom app.main import app; print(No circular import!)# 3. 运行全部测试确认重构没有破坏功能pytest tests/-v--tbshort# 4. 检查领域模块独立性# domains/order/ 不 import domains/user/ 的 Service# 只通过 models.User 和 schemas.UserResponse 通信# 5. 确认 v2 路由预留可用创建一个空白 router 测试完整代码清单本章完整代码见column/code/chapter16/完整目录结构已在步骤一展示。测试验证# 验证重构后的架构属性pytest tests/-v-knot integration# 只跑不依赖数据库的测试# 验证模块导入无循环依赖python-c from app.models.user import User from app.models.order import Order from app.domains.user.service import UserService from app.domains.order.service import OrderService print(All imports successful - no circular deps) 4. 项目总结优点 缺点对比维度按领域拆分本期按层拆分扁平 services/ repos/微服务拆分每领域独立服务团队协作好每人专注一个领域差改一个需求要跨多个层最优循环依赖少领域间弱耦合多扁平结构引用分散无服务间 RPC文件数量中~30 文件少~15 文件多~50 文件部署复杂度低单体部署低高CI/CD 复杂适用场景✓ 适用场景3-15 人的后端团队共享一个代码仓库业务模块需要独立开发但共享基础设施数据库、缓存需要支持多 API 版本共存的过渡期项目代码库预计维护 1 年以上需要清晰的模块边界✗ 不适用场景2 人以下的微型团队——过度设计增加认知负担业务逻辑极少、纯 CRUD 的管理后台注意事项domains/之间禁止相互 import ServiceUser 领域需要调用 Order 领域时通过事件触发或依赖注入接口通信而非直接from domains.order.service import OrderService。测试目录要镜像源码结构tests/domains/user/test_service.py— 一眼就知道测试覆盖了什么。alembic/versions/定期清理超过 30 个迁移文件时做一次 squash合并生成基线迁移减少 CI 时间。常见踩坑经验案例一TYPE_CHECKING误用导致运行时 AttributeError现象代码在 mypy 下正常但uvicorn启动时抛出AttributeError: type object Order has no attribute user。根因开发者在if TYPE_CHECKING:块外使用了Order.user的 relationship 属性但 User 类未被正确关联。解决relationship 的另一侧必须在back_populates中正确指回且双方模型的__tablename__必须已注册。案例二alembic 按数字命名后 head 定位错误现象alembic upgrade head执行了错误的版本链跳过一个版本。根因数字命名的迁移文件如果被手动修改了down_revision指向了非直接前驱链就会断裂。解决永远用alembic revision --autogenerate自动管理down_revision不要手改。案例三应用工厂函数create_app()在测试中未复用现象每次测试都创建一个新的FastAPI实例导致dependency_overrides不生效。根因测试中直接from app.main import app但app.main在 import 时就创建了单例 app——与 conftest 中的 override 对象不是同一个 app。解决conftest 中也调用create_app()创建 app 实例确保测试和业务代码使用同一个工厂。思考题初级为重构后的项目增加一个库存领域模块domains/inventory/。要求不修改 core、不 import 其他领域模块的 Service通过 models 和 schemas 完成数据交互。进阶如果团队未来要拆分为微服务用户服务独立部署当前的domains/user/目录下哪些文件需要改哪些可以直接复用提示思考共享内核shared kernel的设计——哪些代码需要在多个微服务间保持一致答案提示第 1 题遵循现有领域模块的模式——创建api.py、service.py、repository.py。第 2 题的关键models/ 和 schemas/ 中的 User 相关定义将成为各服务的共享内核用 Git submodule 或 pip package 管理domains/user/ 中的 service 和 api 可以直接拆为独立服务。第 28 章深入讲解微服务拆分。延伸阅读与资源NumPy 从入门到生产落地全链路实战指南科学计算/向量化Redis 8 实战精讲从 CRUD 到源码构建高可用缓存系统Redis 实战修炼与原理进阶Python 3实战精进从脚本到高并发订单引擎python入门Rquests从菜鸟脚本到企业级SDK的网络实战圣经Milvus向量数据库实战修炼从 0 到 1精通向量检索与生产落地MongoDB 实战进阶与内核修炼后端工程师的 AI 转型第一课Ollama 与私有化大模型实战10倍开发者的 Dify 魔法书从零构建全栈 AI 应用后端工程师转型AI第一课-Ollama 与私有化大模型实战大型语言模型(LLM) vLLM 高性能推理落地实战Agent开发之LlamaIndex 实战修炼与源码进阶大语言模型Transformers 实战修炼与源码剖析 第16章：FastAPI生产级项目结构与模块边界
1. 项目背景业务场景第 15 章交付的任务协作 API在大师眼中是合格的 Demo但在运维和架构师眼中问题重重一个main.py包含了 20 个app.include_router()调用每次新加模块都要手动在 main 里加一行忘加一次线上事故。用户模块、订单模块、支付模块、通知模块全在一个 Python 包里——某人改了User模型的email字段支付模块的序列化突然全崩了。from app.models.user import User和from app.schemas.user import UserCreate被团队三人以三种方式 importPyCharm 自动补全列出的候选多达 30 个。产品要求支付接口要同时支持 v1 和 v2 两个版本共存 6 个月——但现在的路由全部写在/api/v1/下v2 不知从哪儿下手。数据库迁移脚本alembic/versions/下已经有 15 个文件编号乱七八糟——abc123、def456、xyz789……根本不知道哪个先执行。痛点从一个能跑的 Demo 升级为可多人维护的生产工程核心挑战不是写代码而是管结构循环依赖死锁user.pyimportorder.pyorder.pyimportproduct.pyproduct.pyimportuser.py——Python 解释器直接报ImportError。全局状态泄漏某开发者在config.py写了current_tenant_id None然后在中间件里改了它。多租户场景下请求 A 的租户 ID 泄漏到了请求 B。模块爆炸新人打开项目面对 50 个顶层目录不知道从哪个文件开始看——“先读哪个依赖关系是什么”发布粒度粗所有模块打成一个 Python 包改一行支付代码要重新部署整个服务含用户模块、通知模块、45 个接口。本章不写新功能——而是把第 15 章的 Demo重构为可支撑 10 人团队协作 6 个月的生产级结构。2. 项目设计场景架构评审会。大师把第 15 章的项目结构投屏。小胖的文件夹有 12 层嵌套小白的文件关系图画得像蜘蛛网。小胖指着屏幕“我任务系统就跑 3 个模块——用户、项目、任务——搞那么多目录干嘛core/、integrations/、infrastructure/……这不就是把代码从一个大文件拆成 50 个小文件吗”小白“不是的。代码量没变但职责变了——每个文件有了明确的’责任边界’。比如app/repositories/user.py只负责数据库查询不包含业务逻辑。以后要切换从 MySQL 到 MongoDB只要改这一个文件业务层代码一行不动。”大师“小胖你还记得员工食堂和米其林后厨的区别吗食堂可能一个厨师炒三个菜但米其林后厨——洗菜岗、切菜岗、调味岗、摆盘岗各司其职。当餐厅从 30 个客人变成 300 个客人时不分工就是灾难。代码也是一样——3 个人写 3 个模块基础篇10 个人写 10 个模块中级篇结构不分工就是互相踩脚。”技术映射生产级项目结构的核心原则是按领域模块划分 统一基础设施。每个领域用户、订单、支付内部有自己独立的 API/Service/Repository/Model但共享 core配置、安全、数据库和 infrastructure缓存、消息队列、日志。小胖“那多版本 API 共存呢v1 和 v2 怎么搞”大师“有三种策略”方案实现方式优点缺点URL 前缀/api/v1/orders/api/v2/orders直观Nginx 可分别路由代码最终要有两套 RouterHeader 版本Accept: application/vnd.apijson;version2URL 干净客户端难调试双服务独立部署 v1 和 v2 两个服务完全隔离运维成本翻倍“推荐初学者用 URL 前缀——简单直观FastAPI 支持最好。”小白“循环依赖怎么解user.py需要order.py的 Order 类型order.py需要user.py的 User 类型——但 Python 把它俩放不同文件就会 import 报错。”大师三种解法TYPE_CHECKING 字符串注解from typing import TYPE_CHECKING在if TYPE_CHECKING:块内 import — 只在类型检查时生效运行时跳过。抽取共享层把 User 和 Order 都依赖的’基础类型’如ID、TimestampMixin抽到app/models/base.py。解耦 relationship删除 ORM 层之间的relationship()只保留ForeignKey— 业务关联靠字段值而非 ORM 对象。推荐组合使用——TYPE_CHECKING 解决类型提示共享层解决运行时依赖。技术映射TYPE_CHECKING是 Python 3.6 的特性它只在 mypy/pyright 类型检查时为True运行时为False。这样可以在不创建真正 import 的情况下让类型检查器知道类的存在解决循环 import 的同时保持类型安全。小胖“那 alembic 版本命名呢15 个迁移文件了都叫abc1234_xxx——哪天要回滚根本不知道哪个版本对应哪个功能。”大师迁移文件命名规范——用日期前缀 功能描述alembic/versions/ ├── 20260101_init_users_and_projects.py ├── 20260105_add_task_tags_table.py ├── 20260110_add_priority_column_to_tasks.py └── 20260115_create_index_on_task_status.py“数字前缀保证执行顺序alembic 按文件名排序功能描述一目了然。团队协作时每人按当前日期生成编号永远不会冲突。”3. 项目实战——重构任务协作 API 为生产级结构分步实现步骤一设计生产级目录结构目标可达 10 人协作的模块边界ecommerce-api/ ├── app/ │ ├── main.py # FastAPI 应用工厂函数 │ ├── bootstrap.py # 应用初始化路由注册、事件绑定 │ │ │ ├── core/ # 基础设施被所有模块依赖 │ │ ├── config.py # 统一配置 │ │ ├── database.py # SQLAlchemy Engine Session │ │ ├── security.py # JWT 密码哈希 │ │ ├── exceptions.py # 全局异常类定义 │ │ ├── response.py # 统一响应模型 APIResponse │ │ └── dependencies.py # 通用依赖分页、当前用户 │ │ │ ├── models/ # ORM 模型一个文件一个表 │ │ ├── base.py # Base TimestampMixin │ │ ├── user.py │ │ ├── product.py │ │ ├── order.py │ │ └── __init__.py # 统一导出方便 import │ │ │ ├── schemas/ # Pydantic 模型按领域分文件 │ │ ├── user.py │ │ ├── product.py │ │ ├── order.py │ │ └── common.py # 公共 Schema分页、排序 │ │ │ ├── domains/ # 领域模块核心业务⭐ │ │ ├── user/ # 用户领域 │ │ │ ├── api.py # 路由router.get/post... │ │ │ ├── service.py # 业务逻辑 │ │ │ ├── repository.py # 数据访问 │ │ │ └── __init__.py │ │ ├── product/ │ │ │ ├── api.py │ │ │ ├── service.py │ │ │ ├── repository.py │ │ │ └── __init__.py │ │ ├── order/ │ │ │ ├── api.py │ │ │ ├── service.py │ │ │ ├── repository.py │ │ │ └── __init__.py │ │ └── notification/ │ │ ├── api.py │ │ ├── service.py │ │ └── __init__.py │ │ │ ├── api/ # API 版本路由组装 │ │ ├── v1/ │ │ │ └── router.py # 收集所有 v1 领域路由 │ │ └── v2/ │ │ └── router.py # v2 版本路由预留 │ │ │ └── infrastructure/ # 外部集成可选视需要拆分 │ ├── cache.py # Redis 缓存客户端 │ ├── queue.py # 消息队列客户端第20章 │ └── storage.py # 对象存储S3/MinIO第11章进阶 │ ├── alembic/ # 数据库迁移 ├── tests/ # 测试按领域镜像 src 结构 │ ├── conftest.py │ ├── domains/ │ │ ├── user/ │ │ ├── product/ │ │ └── order/ │ └── core/ ├── pyproject.toml ├── Dockerfile └── .env.example核心设计决策domains/代替services/repositories/api/按领域垂直切分而非按层水平切分。开发者改用户模块只需关注domains/user/一个目录。models/和schemas/留在顶层因为多个领域可能共享同一个 Model如 User 被订单和通知模块同时引用抽取到顶层避免循环依赖。bootstrap.py负责组装应用入口main.py只做最小初始化路由注册交给bootstrap.py便于测试时按需组装。步骤二消除循环依赖目标使用 TYPE_CHECKING 共享基类app/models/base.pyfromdatetimeimportdatetime,timezonefromsqlalchemyimportDateTime,funcfromsqlalchemy.ormimportDeclarativeBase,Mapped,mapped_columnclassBase(DeclarativeBase):passclassTimestampMixin:所有需要时间戳的表复用此 Mixincreated_at:Mapped[datetime]mapped_column(DateTime(timezoneTrue),server_defaultfunc.now(),nullableFalse)updated_at:Mapped[datetime]mapped_column(DateTime(timezoneTrue),server_defaultfunc.now(),onupdatefunc.now(),nullableFalse)app/models/user.pyfromtypingimportTYPE_CHECKINGfromsqlalchemyimportString,Booleanfromsqlalchemy.ormimportMapped,mapped_column,relationshipfromapp.models.baseimportBase,TimestampMixinifTYPE_CHECKING:fromapp.models.orderimportOrder# 仅类型检查时 importclassUser(Base,TimestampMixin):__tablename__usersid:Mapped[int]mapped_column(primary_keyTrue,autoincrementTrue)username:Mapped[str]mapped_column(String(50),uniqueTrue,indexTrue)email:Mapped[str]mapped_column(String(200),uniqueTrue)hashed_password:Mapped[str]mapped_column(String(255))is_active:Mapped[bool]mapped_column(Boolean,defaultTrue)# relationship 使用字符串引用避免运行时 importorders:Mapped[list[Order]]relationship(back_populatesuser,lazyselectin)app/models/order.pyfromtypingimportTYPE_CHECKING# 运行时只 import ForeignKey不 import User 类fromsqlalchemyimportForeignKey,Integer,String,Numericfromsqlalchemy.ormimportMapped,mapped_column,relationshipfromapp.models.baseimportBase,TimestampMixinifTYPE_CHECKING:fromapp.models.userimportUserclassOrder(Base,TimestampMixin):__tablename__ordersid:Mapped[int]mapped_column(primary_keyTrue)user_id:Mapped[int]mapped_column(ForeignKey(users.id),indexTrue)status:Mapped[str]mapped_column(String(20),defaultpending)user:Mapped[User]relationship(back_populatesorders)步骤三实现 bootstrap.py 组装应用目标解耦 main.py 与路由注册app/bootstrap.pyfromfastapiimportFastAPIfromstarlette.middleware.corsimportCORSMiddlewarefromapp.core.configimportsettingsfromapp.core.exceptionsimportAppExceptionfromapp.core.handlersimportapp_exception_handler,global_exception_handlerfromapp.api.v1.routerimportv1_routerdefcreate_app()-FastAPI:应用工厂函数——测试时也可调用appFastAPI(titlesettings.APP_NAME,versionsettings.APP_VERSION,docs_url/api/v1/docsifnotsettings.DEBUGelse/docs,redoc_url/api/v1/redoc,)# 中间件顺序重要后注册的先执行app.add_middleware(CORSMiddleware,allow_originssettings.CORS_ORIGINS,allow_credentialsTrue,allow_methods[*],allow_headers[*],)# 路由注册app.include_router(v1_router)# 异常处理app.add_exception_handler(AppException,app_exception_handler)app.add_exception_handler(Exception,global_exception_handler)returnappapp/api/v1/router.pyfromfastapiimportAPIRouterfromapp.domains.user.apiimportrouterasuser_routerfromapp.domains.product.apiimportrouterasproduct_routerfromapp.domains.order.apiimportrouterasorder_routerfromapp.domains.notification.apiimportrouterasnotification_router v1_routerAPIRouter(prefix/api/v1)v1_router.include_router(user_router)v1_router.include_router(product_router)v1_router.include_router(order_router)v1_router.include_router(notification_router)app/main.py精简为 3 行fromapp.bootstrapimportcreate_app appcreate_app()步骤四规范化 Alembic 迁移命名目标版本链可追溯# 删除旧的杂乱版本文件从统一基线重新初始化alembic init alembic# 统一命名格式YYYYMMDD_功能描述alembic revision--autogenerate-m20260101_init_core_tables# → alembic/versions/20260101_init_core_tables.pyalembic revision--autogenerate-m20260110_add_order_table# → alembic/versions/20260110_add_order_table.py步骤五验证重构结果# 1. 确保重构后所有接口仍可访问uvicorn app.main:app--reloadcurl-shttp://localhost:8000/api/v1/health# 2. 确认无循环 importpython-cfrom app.main import app; print(No circular import!)# 3. 运行全部测试确认重构没有破坏功能pytest tests/-v--tbshort# 4. 检查领域模块独立性# domains/order/ 不 import domains/user/ 的 Service# 只通过 models.User 和 schemas.UserResponse 通信# 5. 确认 v2 路由预留可用创建一个空白 router 测试完整代码清单本章完整代码见column/code/chapter16/完整目录结构已在步骤一展示。测试验证# 验证重构后的架构属性pytest tests/-v-knot integration# 只跑不依赖数据库的测试# 验证模块导入无循环依赖python-c from app.models.user import User from app.models.order import Order from app.domains.user.service import UserService from app.domains.order.service import OrderService print(All imports successful - no circular deps) 4. 项目总结优点 缺点对比维度按领域拆分本期按层拆分扁平 services/ repos/微服务拆分每领域独立服务团队协作好每人专注一个领域差改一个需求要跨多个层最优循环依赖少领域间弱耦合多扁平结构引用分散无服务间 RPC文件数量中~30 文件少~15 文件多~50 文件部署复杂度低单体部署低高CI/CD 复杂适用场景✓ 适用场景3-15 人的后端团队共享一个代码仓库业务模块需要独立开发但共享基础设施数据库、缓存需要支持多 API 版本共存的过渡期项目代码库预计维护 1 年以上需要清晰的模块边界✗ 不适用场景2 人以下的微型团队——过度设计增加认知负担业务逻辑极少、纯 CRUD 的管理后台注意事项domains/之间禁止相互 import ServiceUser 领域需要调用 Order 领域时通过事件触发或依赖注入接口通信而非直接from domains.order.service import OrderService。测试目录要镜像源码结构tests/domains/user/test_service.py— 一眼就知道测试覆盖了什么。alembic/versions/定期清理超过 30 个迁移文件时做一次 squash合并生成基线迁移减少 CI 时间。常见踩坑经验案例一TYPE_CHECKING误用导致运行时 AttributeError现象代码在 mypy 下正常但uvicorn启动时抛出AttributeError: type object Order has no attribute user。根因开发者在if TYPE_CHECKING:块外使用了Order.user的 relationship 属性但 User 类未被正确关联。解决relationship 的另一侧必须在back_populates中正确指回且双方模型的__tablename__必须已注册。案例二alembic 按数字命名后 head 定位错误现象alembic upgrade head执行了错误的版本链跳过一个版本。根因数字命名的迁移文件如果被手动修改了down_revision指向了非直接前驱链就会断裂。解决永远用alembic revision --autogenerate自动管理down_revision不要手改。案例三应用工厂函数create_app()在测试中未复用现象每次测试都创建一个新的FastAPI实例导致dependency_overrides不生效。根因测试中直接from app.main import app但app.main在 import 时就创建了单例 app——与 conftest 中的 override 对象不是同一个 app。解决conftest 中也调用create_app()创建 app 实例确保测试和业务代码使用同一个工厂。思考题初级为重构后的项目增加一个库存领域模块domains/inventory/。要求不修改 core、不 import 其他领域模块的 Service通过 models 和 schemas 完成数据交互。进阶如果团队未来要拆分为微服务用户服务独立部署当前的domains/user/目录下哪些文件需要改哪些可以直接复用提示思考共享内核shared kernel的设计——哪些代码需要在多个微服务间保持一致答案提示第 1 题遵循现有领域模块的模式——创建api.py、service.py、repository.py。第 2 题的关键models/ 和 schemas/ 中的 User 相关定义将成为各服务的共享内核用 Git submodule 或 pip package 管理domains/user/ 中的 service 和 api 可以直接拆为独立服务。第 28 章深入讲解微服务拆分。延伸阅读与资源NumPy 从入门到生产落地全链路实战指南科学计算/向量化Redis 8 实战精讲从 CRUD 到源码构建高可用缓存系统Redis 实战修炼与原理进阶Python 3实战精进从脚本到高并发订单引擎python入门Rquests从菜鸟脚本到企业级SDK的网络实战圣经Milvus向量数据库实战修炼从 0 到 1精通向量检索与生产落地MongoDB 实战进阶与内核修炼后端工程师的 AI 转型第一课Ollama 与私有化大模型实战10倍开发者的 Dify 魔法书从零构建全栈 AI 应用后端工程师转型AI第一课-Ollama 与私有化大模型实战大型语言模型(LLM) vLLM 高性能推理落地实战Agent开发之LlamaIndex 实战修炼与源码进阶大语言模型Transformers 实战修炼与源码剖析