Python 5种要知道的常见项目结构

用户11081884

发布于 2026-07-20 19:03:00

360

文章被收录于专栏：用户11081884的专栏用户11081884的专栏

在Python开发中，合理的项目结构对代码的可维护性、可扩展性和团队协作至关重要。本文介绍5种常见的Python项目布局，每种结构都配有使用说明和原创代码示例。

1. 单文件应用程序

适用场景: 简单脚本、一次性任务、小型工具。

结构示例:

calculator.py
requirements.txt
README.md

使用说明:

所有代码写在一个文件中
适合不超过200行代码的小项目
便于快速开发和部署

代码示例:

# calculator.py
"""简易计算器应用"""

def add(a, b):
    """加法运算"""
    return a + b

def subtract(a, b):
    """减法运算"""
    return a - b

def main():
    print("简易计算器")
    num1 = float(input("输入第一个数字: "))
    num2 = float(input("输入第二个数字: "))
    
    result = add(num1, num2)
    print(f"{num1} + {num2} = {result}")

if __name__ == "__main__":
    main()

2. 模块化布局

适用场景: 中等复杂度应用，需要功能分离。

结构示例:

data_processor/
├── main.py
├── data_loader.py
├── data_cleaner.py
├── analyzer.py
├── config.py
├── requirements.txt
└── README.md

使用说明:

按功能划分不同模块
每个模块负责特定功能
便于代码复用和维护

代码示例:

# data_loader.py
def load_csv(filepath):
    """加载CSV文件"""
    import pandas as pd
    return pd.read_csv(filepath)

# data_cleaner.py  
def remove_duplicates(df):
    """去除重复数据"""
    return df.drop_duplicates()

# analyzer.py
def calculate_statistics(df):
    """计算基本统计量"""
    return df.describe()

# main.py
from data_loader import load_csv
from data_cleaner import remove_duplicates
from analyzer import calculate_statistics

def process_data(filepath):
    data = load_csv(filepath)
    clean_data = remove_duplicates(data)
    stats = calculate_statistics(clean_data)
    return stats

3. 包布局结构

适用场景: 大型项目，需要层次化组织。

结构示例:

ml_project/
├── __init__.py
├── main.py
├── data/
│   ├── __init__.py
│   ├── preprocessing.py
│   └── validation.py
├── models/
│   ├── __init__.py
│   ├── trainer.py
│   └── predictor.py
├── utils/
│   ├── __init__.py
│   └── helpers.py
├── tests/
│   ├── test_data.py
│   └── test_models.py
├── requirements.txt
└── README.md

使用说明:

使用包目录组织相关模块
每个目录需要 init.py 文件
支持相对导入和命名空间管理

代码示例:

# ml_project/data/preprocessing.py
def normalize_data(data):
    """数据标准化"""
    return (data - data.mean()) / data.std()

# ml_project/models/trainer.py
from ..data.preprocessing import normalize_data

class ModelTrainer:
    def __init__(self, model):
        self.model = model
    
    def train(self, X, y):
        X_normalized = normalize_data(X)
        self.model.fit(X_normalized, y)

4. MVC模式结构

适用场景: 需要清晰分离关注点的应用。

结构示例:

task_manager/
├── models/
│   ├── __init__.py
│   └── task.py
├── views/
│   ├── __init__.py
│   └── cli.py
├── controllers/
│   ├── __init__.py
│   └── task_controller.py
├── utils/
│   └── __init__.py
└── main.py

使用说明:

Model: 数据处理和业务逻辑
View: 用户界面展示
Controller: 协调Model和View

代码示例:

# models/task.py
class Task:
    def __init__(self, title, description):
        self.title = title
        self.description = description
        self.completed = False

# views/cli.py
class TaskView:
    def show_tasks(self, tasks):
        for i, task in enumerate(tasks, 1):
            status = "✓" if task.completed else "✗"
            print(f"{i}. [{status}] {task.title}")

# controllers/task_controller.py
from models.task import Task
from views.cli import TaskView

class TaskController:
    def __init__(self):
        self.tasks = []
        self.view = TaskView()
    
    def add_task(self, title, description):
        task = Task(title, description)
        self.tasks.append(task)

5. Web应用结构

适用场景: Flask、Django等Web框架项目。

结构示例:

blog_app/
├── app/
│   ├── __init__.py
│   ├── routes.py
│   ├── models/
│   │   └── post.py
│   ├── templates/
│   │   └── index.html
│   └── static/
│       ├── css/
│       └── js/
├── tests/
├── config.py
├── run.py
└── requirements.txt

使用说明:

遵循框架约定结构
分离静态文件和模板
配置环境特定的设置

代码示例:

# app/__init__.py
from flask import Flask

def create_app():
    app = Flask(__name__)
    
    from .routes import main
    app.register_blueprint(main)
    
    return app

# app/routes.py
from flask import Blueprint, render_template

main = Blueprint('main', __name__)

@main.route('/')
def index():
    return render_template('index.html')

# run.py
from app import create_app

app = create_app()

if __name__ == '__main__':
    app.run(debug=True)

选择合适的项目结构能够显著提升开发效率和代码质量。根据项目规模和发展需求，灵活选择最适合的结构方案。

1、文档完整性: 每个项目都应包含详细的README文档；

2、依赖管理: 使用requirements.txt或pyproject.toml明确依赖；

3、测试覆盖: 建立完整的测试目录和测试用例；

4、配置分离: 区分开发、测试、生产环境配置；

5、版本控制: 合理配置.gitignore文件；

“无他，惟手熟尔”！有需要的用起来！

如果你觉得这篇文章有用，欢迎点赞、转发、收藏、留言、推荐❤！

本文参与腾讯云自媒体同步曝光计划，分享自微信公众号。

原始发表：2025-11-28，如有侵权请联系 cloudcommunity@tencent.com 删除

布局