用途
本技能面向 Python 项目的组织与模块架构设计,帮助建立结构清晰、模块边界明确、公共接口显式、易于维护的目录结构。好的组织方式能让代码更易被发现,也让变更结果更可预期。
适用场景包括:
- 从零开始创建一个新的 Python 项目
- 为提升清晰度而重新组织既有代码库
- 使用 all 定义模块的公共 API
- 在扁平目录结构与嵌套目录结构之间做选择
- 决定测试文件的放置策略
- 创建可复用的库包
核心概念
- 模块内聚:把会一起变化的相关代码放在一起,一个模块应只有一个清晰的目的。
- 显式接口:用 all 定义哪些内容是公开的,未列出的都属于内部实现细节。
- 扁平层级:优先使用浅层目录结构,只有存在真实子领域时才增加深度。
- 一致的约定:在整个项目中统一应用命名与组织模式。
快速开始
myproject/
├── src/
│ └── myproject/
│ ├── __init__.py
│ ├── services/
│ ├── models/
│ └── api/
├── tests/
├── pyproject.toml
└── README.md
基本模式
模式 1:一个文件一个概念
每个文件应聚焦于单一概念或一组紧密相关的函数。当文件出现以下情况时可考虑拆分:
- 承担多个不相关的职责
- 超过 300–500 行(具体阈值视复杂度而定)
- 包含因不同原因而发生变化的类
# Good: Focused files
# user_service.py - User business logic
# user_repository.py - User data access
# user_models.py - User data structures
# Avoid: Kitchen sink files
# user.py - Contains service, repository, models, utilities...
模式 2:用 all 定义显式公共 API
为每个模块定义公共接口。未列出的成员属于内部实现细节。
# mypackage/services/__init__.py
from .user_service import UserService
from .order_service import OrderService
from .exceptions import ServiceError, ValidationError
__all__ = [
"UserService",
"OrderService",
"ServiceError",
"ValidationError",
]
# Internal helpers remain private by omission
# from .internal_helpers import _validate_input # Not exported
模式 3:扁平目录结构
优先使用最小嵌套。过深的层级会让导入变得冗长、导航变得困难。
# Preferred: Flat structure
project/
├── api/
│ ├── routes.py
│ └── middleware.py
├── services/
│ ├── user_service.py
│ └── order_service.py
├── models/
│ ├── user.py
│ └── order.py
└── utils/
└── validation.py
# Avoid: Deep nesting
project/core/internal/services/impl/user/
仅当存在需要隔离的真实子领域时,才添加子包。
模式 4:测试文件组织
选择一种方式,并在整个项目中保持一致。
方式 A:测试与代码同置
src/
├── user_service.py
├── test_user_service.py
├── order_service.py
└── test_order_service.py
好处:测试与被验证的代码放在一起,便于发现覆盖缺口。
方式 B:并行的测试目录
src/
├── services/
│ ├── user_service.py
│ └── order_service.py
tests/
├── services/
│ ├── test_user_service.py
│ └── test_order_service.py
好处:生产代码与测试代码干净分离,是较大型项目的常见做法。
进阶模式
模式 5:包初始化
用 init.py 为包的使用者提供干净的公共接口。
# mypackage/__init__.py
"""MyPackage - A library for doing useful things."""
from .core import MainClass, HelperClass
from .exceptions import PackageError, ConfigError
from .config import Settings
__all__ = [
"MainClass",
"HelperClass",
"PackageError",
"ConfigError",
"Settings",
]
__version__ = "1.0.0"
使用方随后可以直接从包导入:
from mypackage import MainClass, Settings
模式 6:分层架构
按架构层次组织代码,实现清晰的关注点分离。
myapp/
├── api/ # HTTP handlers, request/response
│ ├── routes/
│ └── middleware/
├── services/ # Business logic
├── repositories/ # Data access
├── models/ # Domain entities
├── schemas/ # API schemas (Pydantic)
└── config/ # Configuration
每一层只应依赖其下方的层,绝不依赖其上方的层。
模式 7:领域驱动结构
对于复杂应用,按业务领域而非技术层次组织代码。
ecommerce/
├── users/
│ ├── models.py
│ ├── services.py
│ ├── repository.py
│ └── api.py
├── orders/
│ ├── models.py
│ ├── services.py
│ ├── repository.py
│ └── api.py
└── shared/
├── database.py
└── exceptions.py
文件与模块命名
约定
- 所有文件与模块名使用 snake_case:
user_repository.py - 避免使用会模糊含义的缩写:用
user_repository.py而非usr_repo.py - 类名与文件名对应:
user_service.py中的UserService
导入风格
使用绝对导入以获得清晰性与可靠性:
# Preferred: Absolute imports
from myproject.services import UserService
from myproject.models import User
# Avoid: Relative imports
from ..services import UserService
from . import models
当模块被移动或重新组织时,相对导入可能会失效。
最佳实践汇总
- 保持文件聚焦:一个文件一个概念,在 300–500 行左右可考虑拆分(视复杂度而定)
- 显式定义 all:让公共接口清晰明确
- 优先使用扁平结构:仅在存在真实子领域时增加深度
- 使用绝对导入:更可靠也更清晰
- 保持一致:在整个项目中统一应用这些模式
- 名称匹配内容:文件名应描述其用途
- 分离关注点:保持各层独立,依赖单向流动
- 记录你的结构:包含一份说明组织方式的 README
限制
资料未提供该技能所支持的具体工具链、命令行接口、安装方式、收费信息或与其他工具的集成方式,这些内容暂未提供。