SuperAPI AI 工具集

python-project-structure

编程与开发

查看项目

更新于 10-16 07:31

技能介绍

用途

本技能面向 Python 项目的组织与模块架构设计,帮助建立结构清晰、模块边界明确、公共接口显式、易于维护的目录结构。好的组织方式能让代码更易被发现,也让变更结果更可预期。

适用场景包括:

  • 从零开始创建一个新的 Python 项目
  • 为提升清晰度而重新组织既有代码库
  • 使用 all 定义模块的公共 API
  • 在扁平目录结构与嵌套目录结构之间做选择
  • 决定测试文件的放置策略
  • 创建可复用的库包

核心概念

  1. 模块内聚:把会一起变化的相关代码放在一起,一个模块应只有一个清晰的目的。
  2. 显式接口:用 all 定义哪些内容是公开的,未列出的都属于内部实现细节。
  3. 扁平层级:优先使用浅层目录结构,只有存在真实子领域时才增加深度。
  4. 一致的约定:在整个项目中统一应用命名与组织模式。

快速开始

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

限制

资料未提供该技能所支持的具体工具链、命令行接口、安装方式、收费信息或与其他工具的集成方式,这些内容暂未提供。