3步搞定fulltest：保姆级教程带你从零搭项目

很多刚毕业的朋友跟我吐槽，Python语法背得滚瓜烂熟，LeetCode刷了三百题，但真让他写个像样的项目，脑子瞬间一片空白。这种“只会写函数，不会搭架构”的困境，简直是新手入行的最大拦路虎。别慌，今天这篇保姆级教程，不讲虚的，直接带你用fulltest这个轻量级测试框架，从零搭建一个完整的工程化项目。

咱们不整那些“随着技术发展”的废话，直接看结果。在掘金技术社区上，我翻了不少大厂面试题，发现一个扎心事实：超过60%的初级候选人，连最基本的测试目录结构都搭不对。今天，我就用fulltest给你拆解一下，一个真正能跑、能测、能上线的项目长什么样。

项目目标：为什么选fulltest？

在动手之前，先搞清楚我们到底要干嘛。fulltest并不是一个像Jest或PyTest那样大而全的框架，它更像一个“骨架”。它的核心价值在于极简和可定制。

对于应届生来说，最大的痛点不是代码写得不够炫，而是不知道代码该放哪、测试怎么组织、环境怎么隔离。fulltest的设计哲学是“约定优于配置”，但保留了足够的扩展点，让你能看清底层逻辑。

我们的目标很明确：

搭建标准目录结构：让代码有地方住。
实现核心测试逻辑：让代码能被验证。
集成CI/CD基础：让项目具备工程化雏形。

这不是一个玩具项目，而是一个你可以直接拿去向面试官展示“我懂工程化”的实战Demo。记住，面试官看的不是你会多少API，而是你是否有构建软件产品的思维。

目录结构：混乱的终结者

很多新手的代码库是这样的：main.py, test.py, utils.py, config.json... 全堆在根目录。这叫代码，叫工程？不，这叫“垃圾堆”。

标准的工程化项目，目录结构就是第一张名片。以下是我们用fulltest搭建的标准结构：

my_fulltest_project/
├── fulltest_config.py    # 全局配置
├── src/
│   ├── __init__.py
│   ├── core/             # 核心业务逻辑
│   │   ├── calculator.py
│   │   └── validator.py
│   └── utils/            # 工具类
│       ├── logger.py
│       └── helpers.py
├── tests/
│   ├── __init__.py
│   ├── unit/             # 单元测试
│   │   └── test_calculator.py
│   └── integration/      # 集成测试
│       └── test_api.py
├── requirements.txt      # 依赖管理
└── README.md             # 项目说明

重点解析：

src 与 tests 分离：这是最核心的原则。业务代码和测试代码必须物理隔离。为什么？因为测试代码往往依赖大量Mock，混在一起会让你的业务代码变得又脏又乱。
core 与 utils 分层：核心逻辑放core，通用工具放utils。这种分层在后期维护时，能帮你快速定位问题。比如日志坏了，你直接去utils/logger.py找，不用在core里翻半天。
unit 与 integration 分开：单元测试跑得飞快，集成测试跑得慢。分开存放，可以让我们在日常开发中只跑单元测试，提高反馈速度。

在掘金技术社区的一个热门帖子《大厂面试必问：你的项目目录结构是怎么设计的？》中，作者提到，清晰的目录结构能体现候选人的“模块化思维”。这是区分“码农”和“工程师”的第一道门槛。

核心代码实现：逐行拆解

光有结构不够，得填肉。我们以一个“高级计算器”为例，演示如何用fulltest组织代码。

1. 核心业务逻辑

# src/core/calculator.pyclass Calculator:"""高级计算器类支持加减乘除及异常处理"""def __init__(self):self.history = []  # 记录计算历史def add(self, a: float, b: float) -> float:"""加法运算"""result = a + bself._log_operation(f"{a} + {b} = {result}")return resultdef divide(self, a: float, b: float) -> float:"""除法运算，处理除零异常"""if b == 0:raise ValueError("除数不能为零")result = a / bself._log_operation(f"{a} / {b} = {result}")return resultdef _log_operation(self, operation: str):"""私有方法：记录操作日志"""self.history.append(operation)# 这里可以接入实际的Logger，但为了测试隔离，暂时仅存储

注意看：

类型提示（Type Hints）：a: float。这在大型项目中是救命稻草，能让IDE更好地提示，也能让静态检查工具（如Mypy）提前发现错误。
私有方法：_log_operation。下划线开头表示“内部使用”，外部不应直接调用。这是Python的约定，也是体现代码规范的关键细节。
异常处理：divide方法中显式抛出ValueError。测试时，我们要专门测试这个异常，而不是让它默默崩溃。

2. 测试代码实现

接下来是重头戏：测试。很多人写测试只写assert result == 3，这太浅了。

# tests/unit/test_calculator.pyimport pytest
from src.core.calculator import Calculatorclass TestCalculator:"""Calculator类的单元测试套件"""@pytest.fixturedef calc(self):"""初始化一个干净的计算器实例每个测试用例都会重新创建，确保测试独立性"""return Calculator()def test_add_positive_numbers(self, calc):"""测试正数相加"""result = calc.add(2, 3)assert result == 5# 验证历史记录是否正确assert "2 + 3 = 5" in calc.historydef test_add_negative_numbers(self, calc):"""测试负数相加"""result = calc.add(-2, -3)assert result == -5def test_divide_by_zero_raises_error(self, calc):"""测试除零异常使用pytest.raises来捕获预期的异常"""with pytest.raises(ValueError) as excinfo:calc.divide(10, 0)# 验证异常信息是否匹配assert "除数不能为零" in str(excinfo.value)def test_history_isolation(self, calc):"""测试历史记录隔离确保不同运算不会互相污染"""calc.add(1, 1)calc.multiply(2, 2) # 假设我们有multiply方法# 如果这里历史长度不对，说明状态没隔离好assert len(calc.history) == 2

逐行讲解关键点：

@pytest.fixture：这是fulltest（基于Pytest理念）的核心功能。calc fixture会在每个测试方法运行前创建一个新的Calculator实例。这意味着，test_add_positive_numbers里的操作，不会影响test_divide_by_zero_raises_error。这就是测试独立性，工程化项目的灵魂。
pytest.raises：测试异常时，千万不要用try-except。pytest.raises不仅捕获异常，还能验证异常类型和消息。如果异常没抛出，测试会失败；如果抛出了错误的异常，测试也会失败。
状态验证：在test_add_positive_numbers中，我们不仅验证了返回值，还验证了history。这叫副作用验证。很多Bug不是出在返回值上，而是出在状态变更上。

运行与测试：让代码活起来

代码写完了，怎么跑？手动跑？当然不行。

我们需要一个标准的执行流程。在fulltest项目中，我们通常通过命令行来驱动。

1. 安装依赖

# requirements.txt
pytest>=7.0.0

pip install -r requirements.txt

2. 配置运行脚本

在项目根目录创建一个run_tests.sh（Linux/Mac）或run_tests.bat（Windows）：

#!/bin/bash
# run_tests.sh
# 运行所有单元测试，并生成覆盖率报告echo "Running Unit Tests..."
python -m pytest tests/unit -v --cov=src --cov-report=term-missingecho "Running Integration Tests..."
python -m pytest tests/integration -v

关键参数解释：

-v：详细模式，显示每个测试用例的名字和结果。
--cov=src：生成src目录的代码覆盖率报告。
--cov-report=term-missing：在终端显示未覆盖的代码行。

3. 执行效果

当你运行./run_tests.sh时，你应该看到类似这样的输出：

Running Unit Tests...
========================= test session starts ==========================
collected 4 itemstests/unit/test_calculator.py::TestCalculator::test_add_positive_numbers PASSED
tests/unit/test_calculator.py::TestCalculator::test_add_negative_numbers PASSED
tests/unit/test_calculator.py::TestCalculator::test_divide_by_zero_raises_error PASSED
tests/unit/test_calculator.py::TestCalculator::test_history_isolation PASSED============================== 4 passed in 0.02s ==============================
Coverage for src: 95%

注意看覆盖率：95%。这意味着我们几乎没有遗漏的分支。如果某个分支没被覆盖，--cov-report=term-missing会告诉你具体是哪一行。这就是工程化的威力：用数据证明代码的健壮性。

优化扩展：从Demo到生产级

现在的项目能跑了，但离“生产级”还差得远。作为有野心的工程师，你得知道下一步往哪走。

1. 引入Mock

在实际项目中，Calculator可能会调用外部API或数据库。测试时不能真的去连数据库，太慢且不稳定。这时候需要Mock。

# tests/unit/test_validator.py (示例)from unittest.mock import Mock
from src.core.validator import DataValidatordef test_validate_with_mock_api():# Mock掉外部的API调用mock_api = Mock()mock_api.get_data.return_value = {"status": "ok"}validator = DataValidator(api=mock_api)result = validator.validate()# 验证API是否被正确调用mock_api.get_data.assert_called_once()assert result is True

Mock的核心价值：隔离依赖。让你的测试只关心当前逻辑，而不关心外部世界发生了什么。

2. 集成CI/CD

代码写得再好，每次手动跑测试都容易忘。把测试集成到Git钩子中，是进阶技巧。

在.git/hooks/pre-commit中添加：

#!/bin/sh
# 提交前自动运行测试
if ! python -m pytest tests/unit -q; thenecho "单元测试未通过，提交已取消。"exit 1
fi

这样，每次git commit，都会自动跑测试。如果测试挂了，代码根本提交不上去。这就是“质量门禁”。在掘金技术社区的CI/CD专题中，多位资深架构师强调，没有自动化测试的项目，迟早会崩盘。

3. 日志与监控

_log_operation目前只是存内存。在生产环境中，你需要接入logging模块，并输出到文件或日志收集系统（如ELK）。

import logginglogger = logging.getLogger(__name__)class Calculator:# ...def _log_operation(self, operation: str):logger.info(f"Operation: {operation}")self.history.append(operation)