第5.1章:学习Python实际项目中的项目结构与代码规范

《Python AI 应用开发入门》第 5.1 节。

使用 src 布局、pyproject.toml、清晰模块边界和一致代码规范整理可安装的 Python 项目。

本节目标

学完本节后，你应当能够：

1. 1. 说明开发环境、运行环境和生产环境的区别。
2. 2. 创建采用 src/ 布局的 Python 项目。
3. 3. 使用 pyproject.toml 描述项目和依赖。
4. 4. 说明可编辑安装解决了什么问题。
5. 5. 按职责拆分模块，并保持单向依赖。
6. 6. 区分格式化、Lint、类型检查和测试。
7. 7. 编写可执行的项目 README。

1. 项目结构要解决什么

几个 Python 文件能运行，不代表它们已经组成了一个可靠的项目。工程化的目录需要让开发者知道源码、测试和配置放在哪里，也要保证代码换到另一台电脑后仍能正确安装和导入。

编写代码的地方和代码最终运行的地方通常不同：

正式承载真实业务、面向真实用户的运行环境称为生产环境。理想情况下，代码在开发环境通过测试后，换到干净的运行环境，仍能按照同一份项目声明完成安装和启动：

开发目录中的源码        │ 按照 pyproject.toml 安装        ↓可以正常导入的应用包        │ 带上明确声明的依赖和配置        ↓在其他电脑或服务器上运行

2. 使用 src/ 布局

本章统一使用下面这套结构：

stage4/├── .gitignore├── README.md├── pyproject.toml├── src/│   └── chat_core/│       ├── __init__.py│       ├── main.py│       ├── config.py│       ├── models.py│       ├── clients.py│       ├── service.py│       └── storage.py└── tests/    ├── test_config.py    ├── test_models.py    ├── test_service.py    └── test_storage.py

stage4/ 是项目根目录，安装、测试、Git 操作和运行命令都从这里开始：

src/ 不是 Python 的强制要求，也不会提高运行速度。它的作用是让项目必须经过正确安装后才能导入，避免当前目录掩盖安装配置问题。

如果包直接放在项目根目录：

stage4/├── chat_core/└── tests/

Python 会优先从当前目录找到 chat_core/，即使项目从未安装，下面的导入也可能成功：

python -c "import chat_core"

采用 src/ 布局后，包不再直接位于项目根目录：

stage4/├── pyproject.toml├── src/│   └── chat_core/└── tests/

此时需要先根据 pyproject.toml 安装项目：

python -m pip install -e .

安装成功后，才可以正常导入：

from chat_core.models import Message

这样，测试使用的是安装后的包，错误的包发现配置和遗漏文件会更早暴露。src 只是源码容器，不是包名，因此导入时仍然写 chat_core，不能写 src.chat_core。

3. 用 pyproject.toml 描述并安装项目

pyproject.toml 是项目的安装说明书。下面这份最小配置声明了构建方式、项目元数据、Python 版本、依赖分组和源码位置：

[build-system]requires = ["setuptools>=68"]build-backend = "setuptools.build_meta"[project]name = "chat-core-study"version = "0.1.0"description = "A testable chat core for learning Python engineering"requires-python = ">=3.11"dependencies = [][dependency-groups]dev = [  "pytest>=8",][tool.setuptools.packages.find]where = ["src"]

其中，dependencies 保存程序运行时必需的包；dependency-groups.dev 保存 pytest、格式化和类型检查等开发工具。运行环境通常不需要安装开发依赖。

开发时可以在项目根目录执行可编辑安装：

python -m pip install -e .python -m pip install --group dev

-e 表示可编辑安装：环境中的包指向当前源码，修改后不必重新安装。--group dev 安装开发依赖组，需要 pip 25.1 或更高版本。安装后可以确认实际导入位置：

python -c "import chat_core; print(chat_core.__file__)"

输出应指向当前项目的 src/chat_core/。可编辑安装服务于开发环境；运行环境通常使用普通安装或部署产物。下一节会用 uv 把环境创建、安装和依赖同步统一起来。

4. 按职责拆分模块

拆分依据是职责，而不是文件行数。模块之间还应保持清楚的单向依赖：

推荐的依赖方向是这样的：

main.py  ├─ config.py  ├─ clients.py  ├─ service.py  └─ storage.pyservice.py  ├─ models.py  └─ clients.pystorage.py  └─ models.py

底层的数据模型不应该反过来导入入口模块：

models.py  ✗→ main.py

出现循环导入时，应先重新检查职责，而不是把 import 移进函数来遮住问题。src/chat_core/__init__.py 可以留空，也可以只公开少数稳定接口：

from .models import Message, ModelResponsefrom .service import ChatService__all__ = [    "ChatService",    "Message",    "ModelResponse",]

这样调用方就能直接写：

from chat_core import ChatService, Message

不要在 __init__.py 中启动程序、读取配置或建立网络连接。导入包不应产生难以预料的副作用。

5. 让代码保持一致

整个项目最好统一遵守下面这套习惯：

名字要说明代码的职责：

load_history()validate_message()build_model_client()

避免含糊的名字：

do_work()process_data()manager = object()

同时遵守几条基本规则：

• • 缩进统一用 4 个空格，不要和 Tab 混用。
• • 运算符、逗号和冒号周围的空格保持一致。
• • 函数调用太长时，借助括号换行。
• • 一个函数尽量只做一件事。
• • 少写多层嵌套，遇到无效情况尽早返回。
• • 及时删除过期注释和调试用的 print()。

例如：

def create_service(    session: ChatSession,    model_client: ModelClient,) -> ChatService:    if session.message_count() < 0:        raise ValueError("消息数量不能为负数")    return ChatService(        session=session,        model_client=model_client,    )

自动格式化工具可以统一样式，却不能替你划分职责。对外公开的函数和方法还应补上类型注解；文档字符串只说明类型无法表达的业务约束和副作用：

from pathlib import Pathdef load_history(path: Path) -> list[Message]:    """从 JSON 文件加载并验证消息历史。"""    ...

类型注解不会校验运行时数据，JSON 和环境变量进入系统时仍要检查。常用质量工具的分工如下：

格式正确 ≠ 逻辑正确类型通过 ≠ 外部数据有效测试通过 ≠ 覆盖所有风险

这些工具互相补充，主要在开发环境和持续集成中帮助我们提前发现问题。

6. 动手实践：迁移上一章的项目

按下面的顺序迁移，先只搬文件，不要同时重写业务逻辑：

1. 1. 创建 src/chat_core/、tests/、pyproject.toml、README 和 .gitignore。
2. 2. 把 models.py、clients.py、service.py 和 storage.py 搬进源码目录。
3. 3. 完成可编辑安装，并确认 chat_core.__file__ 指向 src/chat_core/。
4. 4. 从项目根目录运行 python -m chat_core.main。
5. 5. 检查依赖方向，解决循环导入。
6. 6. 最后再整理命名、类型注解和测试。

README 至少要写清环境要求、安装、运行、测试和配置方式：

# Chat Core Study## 环境要求- Python 3.11+## 开发环境安装python -m pip install -e .python -m pip install --group dev## 普通运行环境安装python -m pip install .## 运行python -m chat_core.main## 测试python -m pytest## 配置- CHAT_MODEL：模拟模型名称- MAX_HISTORY：最大历史条数

README 只能放变量名和安全示例，不能放真实密钥。完成迁移后，换到项目根目录之外仍应能通过安装后的包正常导入和运行。

随堂小测

1. 1. 什么样的运行环境才叫生产环境？
2. 2. src/ 布局主要解决什么问题？
3. 3. 为什么导入时不写 src.chat_core？
4. 4. pyproject.toml 里可以写哪些项目配置？
5. 5. 可编辑安装中的 -e 表示什么？为什么通常不用于生产环境？
6. 6. 运行依赖和开发依赖有什么区别？
7. 7. 为什么模块依赖要保持单向？
8. 8. 格式化、Lint、类型检查和测试分别解决什么问题？

参考答案

1. 1. 正式承载真实业务、面向真实用户的运行环境称为生产环境。
2. 2. 让测试和运行都基于正确安装后的包，避免“恰好在源码目录里就能导入”掩盖问题。
3. 3. src 只是存放源码的容器，对外的包名始终是 chat_core。
4. 4. 构建后端、项目元数据、Python 版本、依赖，以及各类工具的配置。
5. 5. -e 表示可编辑安装，让环境中的包直接指向正在修改的源码；生产环境需要运行明确且稳定的版本，通常不应跟随开发源码变化。
6. 6. 运行依赖是程序跑起来就必须装的包；开发依赖只服务于测试、代码检查等开发环节。
7. 7. 单向依赖更容易理解和测试，也能减少循环导入。
8. 8. 格式化统一样式，Lint 发现可疑写法，类型检查分析类型是否匹配，测试则真正执行代码验证行为。