Python 项目代码结构规范

Python 没有强制目录结构，那我该怎么组织代码？其实 Python 有一套行业通用、大厂标准的代码组织规范，今天一次性讲透：模块、包、类、目录分层到底怎么写才规范、优雅、好维护。

一、先搞懂模块、包、类这3 个核心概念

1. 模块（Module）

就是 一个 .py 文件

• 存放函数、类、变量
• 用于功能拆分，避免代码全写在一个文件里

2. 包（Package）

就是 一个文件夹 + init.py

• 包含多个模块
• 用于分类管理模块

3. 类（Class）

就是 对数据和行为的封装

• 对应 Java 的 class
• Python 中更轻量，但封装、继承、多态完全一致

1. 单一职责

一个模块只做一件事一个包只管理一类功能

2. 分层架构（和 Java 一模一样！）

Python 后端 / AI 项目通用分层：

• 接口层
• 业务逻辑层
• 数据层
• 工具层
• 配置层

3. 包名小写，模块名小写，类名大驼峰

规范如下：

• 包名：utils、service、config
• 模块名：common.py、agent.py
• 类名：UserService、BaseAgent
• 函数 / 变量：get_user()、llm_model

4. 避免循环导入

A 导入 B，B 又导入 A → 直接报错Python 最常见坑，分层可避免。

5. 项目结构扁平化

不要建 7~8 层嵌套目录Python 追求简洁，3 层以内最舒服。

6. 配置与代码分离

配置文件（yaml、json、.env）不写死在代码里便于环境切换。

三、标准 Python 项目结构（直接照抄）

这是 AI 智能体 / Python 后端通用标准结构，企业级规范：

my_project/├── main.py              # 项目入口├── .env                 # 环境变量├── config.yaml          # 配置├── requirements.txt     # 依赖├── config/              # 配置包│   ├── __init__.py│   └── settings.py├── core/                # 核心逻辑│   ├── __init__.py│   └── agent.py├── service/             # 业务服务│   ├── __init__.py│   ├── user_service.py│   └── rag_service.py├── utils/               # 工具类│   ├── __init__.py│   ├── log_util.py│   └── time_util.py├── models/              # 实体类│   ├── __init__.py│   └── schema.py└── tests/               # 测试

你有 Java 经验，一眼就能对应：

• config → 配置类
• service → service 层
• utils → 工具类
• models → entity/dto
• core → 核心流程
• main.py → 启动类

1. 工具函数 → utils 包

如：时间、日志、加密、文件处理

2. 业务逻辑 → service 包

一个业务一个模块如：user_service.py、order_service.py

3. 配置 → config 包

全局配置、模型配置、密钥

4. 实体 / 结构 → models 包

Pydantic 模型、状态结构（LangGraph 大量用）

5. 核心流程 → core 包

Agent 主逻辑、Graph 流程、LLM 调用

6. 入口 → main.py

项目启动、构建 Graph、运行服务

from utils.time_util import cost_timefrom service.agent_service import run_agent

规范总结

一律使用绝对导入，从项目根目录开始导入清晰、不迷路、不循环导入。

六、类的设计规范

• 一个类一个职责
• 类名使用大驼峰：BaseAgent、RagService
• 私有方法用下划线开头：_run_step()
• 公共方法直接写：invoke()
• 用 Pydantic 做数据模型（替代 Java Bean）

Python 项目结构没有魔法，只有规范：

• 一个 py 文件 = 一个模块
• 一个文件夹 = 一个包
• 包按功能分层
• 类按职责拆分
• 导入一律绝对路径
• 结构对标 Java 分层，你会秒上手

真正的高质量 Python 项目，干净、清晰、统一、易维护。