如何为httptap做贡献:uv + pytest + ruff本地开发环境搭建与首个PR提交完整指南
如何为httptap做贡献:uv + pytest + ruff本地开发环境搭建与首个PR提交完整指南
httptap 是一款基于 Rich 的 HTTP 请求性能分析命令行工具,它能把每个 HTTP 请求拆解为 DNS、Connect、TLS、Wait、Transfer 五个阶段,并以瀑布图时间线直观呈现。想给 httptap 贡献代码?本文是一份面向新手的完整贡献指南:从安装 uv 搭建本地开发环境,到用 pytest 跑测试、用 ruff 做代码检查,最后完成你的第一个 Pull Request。
认识 httptap:先看它输出什么
在贡献代码前,先花 30 秒理解这个工具。对任意 URL 运行 httptap,你会看到类似上图的水fall时间线:DNS 解析 16.1ms、TCP 连接 98.0ms、TLS 握手 202.4ms……每一段耗时都清晰可辨。这正好对应源码里各阶段的分析模块:
- 分析器:analyzer.py
- CLI 入口:cli.py
- 阶段实现(DNS / TLS / 计时):httptap/implementations/
官方贡献文档:docs/development/contributing.zh.md
准备工作:安装 uv 与 Python 3.11+
httptap 使用 uv 作为包管理器,通过 pyproject.toml 声明依赖与开发组。只需准备三样东西:
- Python 3.11 或更高版本(CPython)
- uv —— 在终端运行官方安装命令即可,uv 会自动管理 Python 版本
- Git
uv sync 会读取 pyproject.toml 和锁文件 uv.lock,一次性装好 httptap 本体及 dev 依赖组(pytest、ruff、mypy、hypothesis 等)。
克隆仓库并一键搭建本地开发环境
📌 三步完成环境初始化:
# 1. 克隆仓库
git clone https://gitcode.com/gh_mirrors/htt/httptap
cd httptap
# 2. 安装全部开发依赖(含可编辑安装 httptap 本身)
uv sync
# 3. 验证安装成功
uv run httptap --version
看到版本号输出,说明本地开发环境已经就绪。所有命令都建议通过 uv run 执行,它会保证你在项目锁定版本的虚拟环境中运行工具。
💡 建议再装一次提交前钩子:
uv run pre-commit install。之后每次git commit会自动跑 ruff 和 mypy,把问题拦截在提交之前。
跑测试:用 pytest 验证你的改动
httptap 要求 100% 分支覆盖率(见 pyproject.toml 中 fail_under = 100),测试套件位于 tests/ 目录。
运行完整测试套件:
uv run pytest
查看覆盖率报告:
uv run pytest --cov --cov-report=html
运行针对某个模块的测试(更快):
uv run pytest tests/test_analyzer.py
几个实用场景:
| 场景 | 命令 |
|---|---|
| 只跑单元测试 | uv run pytest tests/test_models.py |
| 本地基准测试 | uv run pytest tests/test_benchmarks.py |
| 端到端测试(本地起 HTTP/TLS/代理服务器) | uv run --extra otel pytest tests/e2e --no-cov -n auto |
端到端测试套件 tests/e2e/ 会以子进程方式驱动 httptap CLI,默认不会被 uv run pytest 收集,需要显式传入目录。详细说明见 tests/e2e/README.md。
代码质量:ruff 检查 + 格式化 + mypy 类型检查
httptap 启用了 ruff 的 ALL 规则集,是规则相当严格的项目。提交前务必跑通这三条命令:
# 1. Lint 检查(可自动修复的部分加 --fix)
uv run ruff check
# 2. 格式化检查与自动格式化
uv run ruff format --check
uv run ruff format .
# 3. 严格模式类型检查(mypy strict = true)
uv run mypy httptap
项目代码风格要点(同样约束你的新代码):
- 所有函数签名写 类型注解
- 公共 API 写 Google 风格 docstring
- 行宽不超过 120 字符
- 字符串使用 双引号
这些规则都定义在 pyproject.toml 的 [tool.ruff] 与 [tool.mypy] 小节中。
动手实践:运行你本地的 httptap
修改完 analyzer.py 或 formatters.py 后,直接用本地版本验证效果:
uv run httptap https://httpbin.io
想看它处理重定向链的完整输出(含 Redirect Chain Summary 表格):
提交第一个 PR:从分支命名到 Checklist
规范地命名分支与提交
- 分支名要能说明意图:
feature/add-http3-support、fix/tls-timeout-issue、docs/update-api-reference - 提交信息遵循 Conventional Commits 格式:
feat(cli): add --timeout flag for request timeout
Add command-line option to specify custom timeout.
Closes #123
常用类型:feat、fix、docs、refactor、test、chore、perf。
提 PR 前的最终 Checklist
uv run pytest # ✅ 测试全部通过
uv run ruff format . # ✅ 代码已格式化
uv run ruff check # ✅ Lint 无告警
uv run mypy httptap # ✅ 类型检查通过
再确认:
- [ ] 新功能有测试,且覆盖率不下降
- [ ] 需要的话更新了
docs/下文档 - ] 不要手动编辑 [CHANGELOG.md —— 它由提交信息在发版时自动生成
新手从哪里切入?
优先认领带 good first issue 标签的 Issue。项目 Roadmap(ROADMAP.md)列出的方向也很适合练习:时间精度优化、更多导出格式(Prometheus / OpenTelemetry 已有参考实现)、SLO 扩展、TLS 细节(OCSP、证书链)等。
祝你的第一个 PR 顺利通过!🎉

