python-project-structure

来源声明：本技能内容源自 wshobson/agents （MIT License, Copyright (c) 2024 Seth Hobson；完整许可文本见同目录 LICENSE.txt）。 使用、修改与再分发须遵守该 MIT 许可条款并保留版权声明。

中文描述

本技能提供全栈开发相关的最佳实践和模式指导。

---

name: python-project-structure description: Python project organization, module architecture, and public API design. Use when setting up new projects, organizing modules, defining public interfaces with all, or planning directory layouts.

Python 项目结构与模块架构

设计组织良好的 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

模块移动或重新组织时，相对导入可能会失效。

Best Practices Summary

1. Keep files focused - One concept per file, consider splitting at 300-500 lines (varies by complexity)
2. Define __all__ explicitly - Make public interfaces clear
3. Prefer flat structures - Add depth only for genuine sub-domains
4. Use absolute imports - More reliable and clearer
5. Be consistent - Apply patterns uniformly across the project
6. Match names to content - File names should describe their purpose
7. Separate concerns - Keep layers distinct and dependencies flowing one direction
8. Document your structure - Include a README explaining the organization

能力边界

✅ 擅长处理

• 全栈开发相关的最佳实践
• 代码架构设计指导
• 性能优化建议

⚠️ 需要素材

• 具体的项目上下文
• 技术栈信息

❌ 超出范围

• 非技术领域的业务决策
• 具体的代码实现（仅提供指导）

工作流程

Step 1: 需求分析

理解项目需求和技术约束

Step 2: 架构设计

设计系统架构和组件划分

Step 3: 实现指导

提供具体的实现建议和代码模式

Step 4: 代码审查

审查代码质量和最佳实践遵循情况

Step 5: 优化建议

提供性能优化和改进建议

Gotchas

1. 过度设计

避免在简单场景中使用复杂的设计模式

2. 性能忽视

不要忽视性能优化，特别是在生产环境中

3. 安全考虑

始终考虑安全性和数据保护

4. 测试覆盖

确保有足够的测试覆盖，特别是边界情况

5. 文档维护

保持文档与代码同步更新