Requests源码分析：通用项目结构规范-CSDN博客

本文链接：https://blog.csdn.net/wzx77/article/details/148707868

项目结构规范

项目命名：requests-main

标准化目录布局

project/
├── src/                        # 源代码目录
│   └── package/                # 包目录
│       ├── __init__.py
│       ├── core.py
│       └── utils/
├── tests/                      # 测试目录
│   ├── __init__.py
│   ├── test_core.py
│   └── integration/
├── docs/                       # 文档目录
├── examples/                   # 示例代码
├── pyproject.toml              # 构建配置 (PEP 518)
├── setup.cfg                   # 包元数据
├── LICENSE                     # 许可证文件
├── README.md                   # 项目说明
└── .github/                    # CI/CD 配置
    └── workflows/
        └── ci.yml

必须包含的文件：
- pyproject.toml：构建系统要求（现代 Python 项目的标准）
- setup.cfg 或 setup.py：包元数据和安装配置
- LICENSE：明确的法律授权（推荐 MIT/Apache-2.0）
- README.md：项目入口文档

精确依赖声明：

# pyproject.toml
[project]
dependencies = [
    "numpy>=1.21,<2.0",  # 兼容范围
    "pandas==1.5.3"       # 精确锁定
]

依赖分层：

# setup.cfg
[options.extras_require]
test = 
    pytest>=7.0
    coverage[toml]
docs = 
    sphinx>=5.0
    furo

init.py

文档入口

""" 
包文档字符串（显示在 help(package)）
==============================
这是核心功能包，提供:
- xxx功能
- xxx组件
"""

精简的顶层接口
只暴露核心功能（如 get, post, Session），隐藏底层实现。
```
from .api import request, get, head, post, patch, put, delete, options
```

声明版本元数据
当前文件写入，或者，创建 __version__.py 文件写入再导入，统一维护版本信息。

__title__ = "requests"
__description__ = "Python HTTP for Humans."
__url__ = "https://requests.readthedocs.io"
__version__ = "2.32.3"

环境版本检查
日志初始化

暴露异常类

from .exceptions import (
    ConnectionError,
    ConnectTimeout,
    HTTPError,
    JSONDecodeError,
    RequestException,
    Timeout,
    TooManyRedirects,
    ...
)

version.py

集中定义版本号
使用 __version__ 统一维护版本信息，便于引用和检查。

# __version__.py文件中编辑
__version__ = "2.32.3"

# __init__.py文件中导入
from .__version__ import (
    __version__,
    ...
)

编码规范细节

命名规范
- 变量/函数：snake_case (Python, Ruby) 或 camelCase (Java, JavaScript)
- 类/类型：PascalCase
- 常量：ALL_CAPS
- 原则：名称应自解释（如 user_list 而非 data）
格式统一
- 缩进：空格（推荐 4 空格）或制表符（团队统一）
- 行长度：80~120 字符（避免水平滚动）
- 操作符空格：x = y + 1（非 x=y+1）
注释原则
- 避免注释代码行为（代码应自解释）
- 解释复杂逻辑/设计意图
- 文档注释：描述函数作用、参数、返回值
单一职责原则
- 函数/类只做一件事，命名间接体现
- 函数长度限制：通常 ≤ 30 行
低耦合高内聚
- 模块间依赖最小化（如通过接口交互）
- 相关功能集中组织
错误处理
- 避免静默失败：不忽略异常
- 精准捕获
防御性编程
- 验证输入（如 API 参数、用户输入）
- 处理边界条件
静态类型检查：必须使用类型注解

相对导入
包内模块使用相对导入（.api 而非 requests.api）：

from . import packages, utils
from .sessions import Session, session

导入控制：__all__定义公共API名单
资源管理 ：及时释放资源（文件/网络连接）
不可变性优先 ：使用常量/不可变对象（如 Python 的 tuple）
高效数据结构
- 频繁查找 → HashMap / Dict
- 顺序访问 → Array / List
减少全局状态 ：避免全局变量（导致难以追踪的副作用）
测试金字塔 ：单元测试 >> 集成测试 >> 端到端测试
测试可读性
- 命名体现场景：test_login_fails_on_invalid_password()
- 精准断言信息
防御性编程：确保在完成环境检查后清理临时变量，保持代码的健壮性和可读性。