很多刚开始学习FastAPI的同学都会遇到一个问题项目目录到底应该怎么组织是像Java Spring一样按照Controller、Service、Repository分层还是按照User、Order、Post这样的业务模块划分本文结合实际项目经验聊聊这两种常见的项目组织方式以及为什么越来越多的 FastAPI 项目都推荐采用按业务模块组织代码。方案一按技术层划分Layer-based项目目录大致如下app/ ├── api/ │ ├── user.py │ ├── post.py │ └── comment.py │ ├── service/ │ ├── user_service.py │ ├── post_service.py │ └── comment_service.py │ ├── repository/ │ ├── user_repository.py │ ├── post_repository.py │ └── comment_repository.py │ ├── models/ ├── schemas/ └── utils/熟悉 Java 开发的同学应该对这种结构非常熟悉。它来源于传统的三层架构Controller → Service → Repository也是很多 Spring Boot 项目的默认组织方式。因此不少刚接触 FastAPI 的开发者也会沿用这种目录结构。优点结构简单容易理解新手上手快小型项目开发效率较高缺点对于小项目来说这种方式完全没有问题。但随着业务不断增加同一种类型的代码都会集中到一个目录中一个目录下可能出现几十甚至上百个文件维护成本也会逐渐提高。例如修改一个用户功能你可能需要在多个目录之间来回切换api/user.py service/user_service.py repository/user_repository.py models/user.py schemas/user.py如果项目继续扩展user role permission organization department tenant那么目录可能会变成service/ ├── user_service.py ├── role_service.py ├── permission_service.py ├── organization_service.py ├── department_service.py └── tenant_service.py随着业务越来越多一个目录里堆满各种 Service、Repository查找和维护都会变得越来越困难。方案二按业务模块划分Feature-based另一种越来越流行的组织方式就是按照业务模块划分目录。例如app/ ├── modules/ │ ├── user/ │ ├── router.py │ ├── service.py │ ├── repository.py │ ├── model.py │ └── schema.py │ ├── post/ │ ├── router.py │ ├── service.py │ ├── repository.py │ ├── model.py │ └── schema.py │ ├── comment/ │ ├── router.py │ ├── service.py │ ├── repository.py │ ├── model.py │ └── schema.py │ ├── core/ ├── db/ └── main.py每一个业务模块都是一个相对独立的功能单元它包含路由Router业务逻辑Service数据访问Repository数据模型Model请求响应对象Schema所有与 User 有关的代码都放在同一个目录下。例如修改用户功能只需要进入user/ ├── router.py ├── service.py ├── repository.py ├── model.py └── schema.py基本不用再跨多个目录寻找文件。为什么这样更合理因为现实开发过程中代码的变化通常都是围绕业务发生的而不是围绕技术层发生的。例如我们几乎不会说今天我要修改所有 Service。更多时候我们会说今天新增用户注册功能。 今天修改订单支付流程。 今天增加角色权限管理。也就是说代码的修改通常集中在某一个业务模块内。因此把同一个业务相关的代码放在一起更符合日常开发习惯也能降低维护成本。推荐的 FastAPI 项目结构目前很多 FastAPI 开源项目以及中大型 Python Web 项目都采用按业务模块组织代码。例如app/ ├── core/ │ ├── config.py │ ├── security.py │ └── exception.py │ ├── db/ │ ├── session.py │ └── base.py │ ├── modules/ │ │ ├── user/ │ │ ├── router.py │ │ ├── service.py │ │ ├── repository.py │ │ ├── model.py │ │ └── schema.py │ │ ├── post/ │ │ ├── router.py │ │ ├── service.py │ │ ├── repository.py │ │ ├── model.py │ │ └── schema.py │ │ └── auth/ │ ├── router.py │ ├── service.py │ └── schema.py │ └── main.py其中core存放项目公共配置、安全认证、异常处理等基础设施db数据库连接、Session 管理等modules所有业务模块main.py项目启动入口这种组织方式既方便维护也便于后续扩展。如果项目继续变大怎么办当项目越来越复杂时还可以进一步演进成 DDD领域驱动设计或者 Clean Architecture。例如user/ ├── api/ │ └── router.py │ ├── application/ │ └── service.py │ ├── domain/ │ ├── entity.py │ └── repository.py │ └── infrastructure/ └── repository_impl.py不过对于绝大多数 FastAPI 项目来说直接引入完整的 DDD 分层往往会增加不少复杂度。通常只有当项目规模足够大、业务领域非常复杂时再逐步演进会更加合适。总结如果现在准备新建一个 FastAPI 项目我更推荐采用按业务模块划分目录例如app/ ├── core/ ├── db/ ├── modules/ │ ├── user/ │ ├── auth/ │ ├── post/ │ └── order/ └── main.py这样即使后续业务不断增加也可以继续在模块内部拆分子目录而不需要推倒整个项目结构重新设计。对于小项目来说按技术层划分完全没有问题但如果希望项目具有更好的可维护性和扩展性那么从一开始采用按业务模块组织代码通常会是一个更好的选择。最佳实践这里推荐大家阅读一下FastAPI Best Practices这个开源项目https://github.com/zhanymkanov/fastapi-best-practices该项目总结了大量 FastAPI 的工程实践包括项目目录组织路由拆分依赖注入异常处理数据库管理异步开发测试规范如果准备开发一个生产环境可用的 FastAPI 项目非常值得阅读。示例项目我也基于本文介绍的架构整理并实现了一个FastAPI 种子项目可以直接运行帮助大家快速搭建属于自己的 FastAPI 项目。项目地址https://github.com/byone421/fastapi-seed既适合作为学习示例也可以作为新项目初始化的脚手架。结语好的架构并不是为了炫技而是为了让未来的自己和团队成员能够更轻松地理解、维护和扩展项目。希望本文能帮助你在设计 FastAPI 项目时少走一些弯路也欢迎结合自己的实际项目不断总结出最适合团队的架构方案。