搞定 repo 结构，3步搭出规范项目，这份保姆级教程请收好

学会语法却不知怎么搭项目，这是很多转行开发者最大的噩梦。背了无数 API，打开空文件夹却大脑一片空白，不知道文件该放哪，依赖怎么管。

今天这篇保姆级教程，不玩虚的。我们直接上手，从零搭建一个符合工业标准的 Python 项目。

目标很明确：让你不仅知道代码怎么写，更知道代码该住在哪。

项目目标与思维转变

很多新手写代码是“脚本思维”，一个 main.py 跑通所有逻辑。这在练手时没问题，但在工作中是灾难。

我们要建立的是“工程思维”。一个标准的 repo（代码仓库）应该具备三个核心能力：可配置、可测试、可部署。

想象一下，如果同事接手你的代码，他不需要问你“这个变量在哪定义的”，“这个配置改哪里”，而是直接看 README.md 和目录结构就能跑起来。这就是规范的价值。

本次实战项目是一个简单的“用户管理系统”。功能不复杂，包含用户的增删改查，但结构完全按照中大型项目来设计。我们要解决的问题不是算法难题，而是结构混乱。

为什么选 Python？因为它在数据分析和后端开发中极其通用，且生态丰富，适合演示标准的工程化结构。

目录结构拆解

在写第一行代码前，先规划骨架。一个标准的 Python 项目目录结构通常长这样：

user-manager/
├── README.md          # 项目说明，怎么安装，怎么运行
├── requirements.txt   # 依赖包列表
├── .gitignore         # Git 忽略文件配置
├── main.py            # 程序入口
└── src/               # 源代码目录├── __init__.py    # 标识包├── config.py      # 配置文件├── models/        # 数据模型│   ├── __init__.py│   └── user.py    # User 类定义├── services/      # 业务逻辑│   ├── __init__.py│   └── user_service.py  # 用户操作逻辑└── utils/         # 工具函数├── __init__.py└── validator.py     # 数据校验工具
└── tests/             # 测试目录├── __init__.py└── test_user_service.py

为什么要这么分？

src 目录：这是你的核心代码。不要把所有 .py 文件扔在根目录，那样随着项目变大，你会疯掉。src 是 Source 的缩写，专门放业务逻辑。
models vs services：这是 MVC 或类似架构的简化版。models 只负责数据长什么样（比如 User 有 name, age 字段），services 负责数据怎么变（比如创建用户、修改密码）。数据定义和业务逻辑分离，这是避免“大泥球”代码的关键。
tests：很多人忽略测试。但记住，没有测试的代码是裸奔。我们将在这里编写单元测试，确保每次改动都不会破坏原有功能。
config.py：不要把数据库密码、API Key 硬编码在业务代码里。统一放在配置文件里，方便不同环境（开发、测试、生产）切换。

避坑指南：千万不要在 src 下建一个 main.py。入口文件 main.py 应该放在项目根目录，或者单独的 app.py。src 是被导入的模块，不是执行入口。混淆这两者，会导致导入路径地狱。

核心代码实现

现在，我们开始填充血肉。

1. 数据模型定义

打开 src/models/user.py。

from dataclasses import dataclass
from datetime import datetime@dataclass
class User:"""用户数据模型使用 dataclass 简化样板代码"""id: intname: stremail: strcreated_at: datetime = Nonedef __post_init__(self):# 初始化时设置默认创建时间if self.created_at is None:self.created_at = datetime.now()

这里我们使用了 Python 3.7+ 引入的 @dataclass 装饰器。 逐行解析：

@dataclass：自动帮你生成 __init__、__repr__、__eq__ 等方法。你只需要定义字段，不需要写构造函数。
id: int：类型注解。虽然 Python 是动态类型，但加上类型注解可以让 IDE（如 PyCharm, VS Code）提供更强的代码补全和错误检查。
created_at: datetime = None：带有默认值的字段。
__post_init__：这是 dataclass 的特殊方法，在 __init__ 执行完后调用。我们在这里处理一些简单的逻辑，比如如果创建时间为空，就填充当前时间。

2. 业务逻辑封装

打开 src/services/user_service.py。

from typing import List, Optional
from src.models.user import User
import uuidclass UserService:"""用户服务类处理所有与用户相关的业务逻辑"""def __init__(self):# 模拟数据库，实际项目中这里会连接 DBself._users: List[User] = []def create_user(self, name: str, email: str) -> User:"""创建新用户:param name: 用户名:param email: 邮箱:return: 新创建的 User 对象"""# 1. 校验邮箱唯一性for user in self._users:if user.email == email:raise ValueError(f"Email {email} already exists")# 2. 生成唯一 IDuser_id = int(uuid.uuid4().hex[:8], 16)# 3. 实例化 User 对象new_user = User(id=user_id, name=name, email=email)# 4. 存储self._users.append(new_user)return new_userdef get_user_by_email(self, email: str) -> Optional[User]:"""根据邮箱查找用户:param email: 邮箱:return: User 对象，如果不存在返回 None"""for user in self._users:if user.email == email:return userreturn None

关键点讲解：

依赖注入的雏形：UserService 目前是一个单例或者普通实例。在更高级的项目中，你可能会通过构造函数传入 DatabaseConnection，以便测试时传入 Mock 对象。
异常处理：create_user 中，如果邮箱重复，我们抛出 ValueError。不要在服务层吞掉异常，要把错误抛给调用者（比如 API 层），由它决定如何返回 HTTP 400 状态码。
类型提示：返回值标注为 Optional[User]，意味着可能返回 User 也可能返回 None。这对阅读代码的人非常友好，他们知道需要做空值检查。

3. 程序入口

打开根目录下的 main.py。

from src.services.user_service import UserService
from src.utils.validator import validate_emaildef main():# 初始化服务user_service = UserService()# 模拟创建一个用户try:new_user = user_service.create_user("Alice", "alice@example.com")print(f"Created user: {new_user.name}, ID: {new_user.id}")# 模拟查询found_user = user_service.get_user_by_email("alice@example.com")if found_user:print(f"Found user: {found_user.name}")else:print("User not found")except ValueError as e:print(f"Error: {e}")if __name__ == "__main__":main()

注意 if __name__ == "__main__": 这一行。这是 Python 脚本的标准入口判断。它确保只有在直接运行这个文件时，main() 才会执行。如果这个文件被其他模块 import，代码不会自动运行。这是防止副作用的关键。

运行与测试验证

代码写完了，必须跑起来才能叫项目。

1. 环境准备

在根目录创建虚拟环境，这是 Python 开发的铁律。永远不要污染全局 Python 环境。

# 创建虚拟环境
python -m venv venv# 激活环境 (Linux/Mac)
source venv/bin/activate# 激活环境 (Windows)
venv\Scripts\activate

2. 安装依赖

虽然我们目前只用了标准库，但为了规范，我们建立 requirements.txt。假设我们引入了 pytest 用于测试，和 flake8 用于代码风格检查。

pip install pytest flake8
pip freeze > requirements.txt

3. 编写单元测试

打开 tests/test_user_service.py。

import pytest
from src.services.user_service import UserService@pytest.fixture
def user_service():# 每个测试用例使用一个干净的服务实例return UserService()def test_create_user_success(user_service):# Arrangename = "Bob"email = "bob@test.com"# Actuser = user_service.create_user(name, email)# Assertassert user.name == nameassert user.email == emailassert user.id is not Nonedef test_create_user_duplicate_email(user_service):# Arrangeemail = "dup@test.com"user_service.create_user("First", email)# Act & Assertwith pytest.raises(ValueError) as excinfo:user_service.create_user("Second", email)assert "already exists" in str(excinfo.value)

测试逻辑解析：

@pytest.fixture：定义了一个夹具，每次测试前都会创建一个新的 UserService 实例。这保证了测试之间的隔离性。上一个测试创建的用户，不会影响下一个测试。
Arrange-Act-Assert 模式：这是单元测试的黄金法则。准备数据 -> 执行动作 -> 断言结果。

运行测试：

pytest -v

你应该看到绿色的 2 passed。这给了你修改代码的信心。

4. 运行主程序

python main.py

如果看到 Created user: Alice...，恭喜，你的项目骨架搭建成功。

优化扩展与避坑指南

项目能跑只是及格线。要变得“专业”，还需要考虑以下几点。

1. 配置管理升级

目前 config.py 是空的。如果未来引入数据库，你肯定不想把 DB_PASSWORD 写死在代码里。推荐做法：使用 .env 文件 + python-dotenv 库。

# src/config.py
import os
from dotenv import load_dotenv# 加载 .env 文件
load_dotenv()class Config:DATABASE_URL = os.getenv("DATABASE_URL", "sqlite:///app.db")DEBUG = os.getenv("DEBUG", "True") == "True"

并在根目录创建 .env 文件：

DATABASE_URL=postgresql://user:pass@localhost/db
DEBUG=True

切记：.env 文件必须加入 .gitignore，严禁提交到 Git 仓库！泄露密钥是初学者最常见的安全事故。

2. 代码规范自动化

手动检查代码风格太累。配置 pre-commit 钩子。在 .pre-commit-config.yaml 中配置 flake8 或 black。这样每次 git commit 前，工具会自动格式化代码，不符合规范的提交会被拦截。这是团队协作中保持代码整洁的最强手段。

3. 日志替代 Print

在 main.py 和 services 中，我们用了 print。在生产环境中，严禁使用 print。应该使用 Python 标准库 logging 模块。

import logginglogger = logging.getLogger(__name__)# 在 service 中
logger.info("User created successfully with ID %s", user.id)

日志可以配置级别（DEBUG, INFO, ERROR），可以输出到文件，可以对接 ELK 等日志系统。print 做不到这些。

4. 文档字符串 (Docstrings)

我们已经在 User 类和 UserService 方法中加了简单的文档字符串。建议遵循 Google Style 或 NumPy Style 规范。很多工具（如 Sphinx, Pdoc）可以直接根据这些注释生成漂亮的 HTML 文档。 代码是写给人看的，顺便给机器执行。好的文档字符串能大幅降低沟通成本。

5. 常见避坑清单

循环导入：models 不要导入 services，services 可以导入 models。保持依赖方向单一。
硬编码路径：不要写 C:\Users\...\data.csv。使用 os.path 或 pathlib 相对路径，或基于项目根目录的绝对路径。
忽略 __init__.py：在 src, models, services 等目录下，__init__.py 文件必须存在（即使是空的）。它告诉 Python 这是一个包，允许 from src.models.user import User 这样的导入。