从第一次写下t3code这五个字符到现在已经过去了将近一年。最初它只是我草稿纸角落里的一个代号用来标记第三次推倒重来的个人代码工程规范。如今回头看这个代号恰好概括了我摸索出的一套方法论用 Tidy整洁、Testable可测、Traceable可溯覆盖代码从书写到维护的全过程。如果你也在为项目越改越乱、团队协作难对齐、代码上线后不敢动而头疼这篇文章应该能给你一些超出常规文档的参考。我只讲个人项目和中小团队场景下真实跑过的路径不聊大规模平台的宏观体系。包括为什么最终选择这套方案、核心环节怎么拆怎么落地、踩过的具体问题和排查过程以及一些普通文档不会写清楚的细节。有些经验是付费都不一定有人跟你说的这里一并摊开。1. 项目缘起与整体设计思路1.1 为什么是“第三次”从两次失败重构说起多数开发者都经历过这样的循环项目初期代码写得飞快越往后越举步维艰最后在某个凌晨下定决心重写。我也不例外。第一次失败是因为过度设计。当时年轻气盛拿到需求就开始抽象基类、搭建插件体系甚至为了可能的分布式扩展提前引入了消息队列。结果核心功能还没写完光是对接各种抽象层就花了大半个月。第二次失败则走向另一个极端不做任何规划Controller 里塞业务逻辑SQL 直接散落在页面模板中半个月后连自己写的函数都不敢改。这两次经历让我意识到问题的核心不是写代码的能力而是缺少一整套贯穿开发全过程的决策框架。t3code正是在这种背景下诞生的。它不是某个框架也不是某个工具而是一份结合了目录结构、编码约定、提交规范、测试策略和复盘流程的开发工作流。三个 T 分别对应三个决策维度Tidy代码结构是否整洁可控命名、分层、依赖方向是否清晰。Testable核心逻辑是否容易被测试依赖是否容易被替换测试金字塔是否合理。Traceable从需求到代码再到线上行为每一步是否可追溯Bug 能否快速定位。这个框架听起来简单真正落地却需要很多细节支撑。下面这几节我按实际操作顺序展开你可以把它当作一份可以直接抄作业的配置单。1.2 三个 T 的权重分配与选择理由有人可能会问这三个 T 听起来都泛泛而谈落在具体项目里应该怎么权衡我个人的经验是不同阶段权重不同。个人项目或原型阶段Tidy 权重最高因为快速验证想法时需要随时调整方向杂乱代码会让每次改动都像走雷区。Testable 在核心模块稳定后开始凸显此时要把接口设计、依赖注入方式固定下来。进入多人协作或长期维护阶段Traceable 变成第一优先级没有可追溯性任何优化和重构都是裸奔。举个具体例子。我负责的某个内部工具初期只有我一个人写Tidy占 80%模块划分清楚就够了不需要完整的文档和变更记录。后来团队扩展到 5 人频繁出现“这个接口谁改的”“这个需求为什么删除这个参数”的追问于是补上了 Traceable 对应的规范问题立刻少了一大半。这三个 T 不是并列关系而是有先后顺序的。我的建议是先保证 Tidy 再谈 Testable最后补 Traceable。倒过来推进每一步都会异常痛苦。2. 核心细节解析与实操要点2.1 目录结构设计边界比约定更重要多数团队有代码规范文档但很少有团队把目录结构当作一种规范来设计。实际上目录结构是项目最基础、也是改动成本最高的一种约定一旦定下来后续调整代价极大。以我维护的一个 Python 服务为例最终定型的目录结构长这样project_name/ ├── src/ │ ├── __init__.py │ ├── main.py # 入口只做启动和组装 │ ├── config.py # 配置读取与校验 │ ├── domain/ # 领域层业务实体与规则 │ ├── application/ # 应用层用例编排不依赖框架 │ ├── infrastructure/ # 基础设施层数据库、外部API、缓存 │ └── interfaces/ # 接口层HTTP路由、消息队列消费 ├── tests/ │ ├── unit/ # 单元测试不访问外部依赖 │ ├── integration/ # 集成测试连接真实数据库或第三方 │ └── conftest.py # 测试夹具统一管理 ├── scripts/ │ ├── init_db.py │ └── seed_data.py ├── docs/ │ ├── decisions/ # 架构决策记录ADR │ └── operations/ # 运维相关的说明 ├── .pre-commit-config.yaml ├── pyproject.toml └── README.md这套结构最大的特点是把依赖方向固定了下来domain不依赖任何外部框架application依赖domaininfrastructure和interfaces都依赖application层。也就是说核心业务逻辑处于最内层数据库、HTTP 框架、消息队列全部作为可替换的插件存在。这样做的一个直观好处是未来想从 Django 迁到 FastAPI甚至换成纯异步框架只需要动infrastructure和interfaces核心代码几乎不受影响。针对小项目这套结构可能显得重量级。我的建议是至少保留domain和application的分离哪怕其它层先用单文件顶替也别把业务规则和框架代码混在一起。这算是我踩过的最深的坑之一。2.2 命名规范与代码风格机器能查的不要靠人记风格问题其实是最不值得争论的问题直接用工具固化就好。我在t3code里选用了ruff做 Python 代码检查和格式化eslintprettier处理前端配合pre-commit在提交前自动执行。pre-commit配置是我强烈推荐的第一步工程化改造它能让所有规则在代码进入版本库之前就被强制校验。一个最小可用的配置文件repos: - repo: https://github.com/astral-sh/ruff-pre-commit rev: v0.9.4 hooks: - id: ruff args: [--fix] - id: ruff-format - repo: https://github.com/pre-commit/pre-commit-hooks rev: v5.0.0 hooks: - id: check-merge-conflict - id: debug-statements - id: trailing-whitespace - id: end-of-file-fixer - id: check-yaml args: [--unsafe]这里有一个细节值得展开ruff的--fix参数会自动修复可修复的问题但不可修复的问题比如未使用的导入在特定场景下还是会直接报错。有些同学第一次跑 pre-commit 发现大量报错第一反应是“这工具太严格”实际上更明智的做法是进入ruff check --statistics看看高频问题再针对性调整规则。命名规范我没有做特别复杂的约定只有三条硬规则布尔变量一律以is_、has_、should_开头读代码时语义直接自解释。私有函数统一前缀下划线外部模块禁止导入下划线开头的名字。函数名必须包含动词data()这种词不允许出现。这三条规则配合代码审查可以消灭大多数“读代码靠猜”的问题。2.3 Git 提交规范让历史记录成为可读文档代码写得好不好单看当前文件是不够的提交历史才是项目真正的“日记”。我采用 Conventional Commits 规范并配合commitizen做提交信息检查。一个标准的提交信息长这样feat(auth): 支持基于 JWT 的登录会话刷新 - 新增 refresh_token 接口过期时间 24 小时 - 引入 redis 存储 refresh token 的 hash - 调整 logout 逻辑需要同时清理两份 token Closes #42规范看起来简单实际推行时最大的阻力是“嫌麻烦”。我用了两个技巧降低阻力一是给常用的小团队做一个.gitmessage模版二是把cz commit命令写入项目文档开发者只需要运行这个命令交互式引导会一步步提示输入类型、作用域和描述。相比让所有人记规则提供一个顺手的工具才是真正解决问题的办法。提交规范的价值在三个月后才显现。当你需要回溯“某个功能是哪个提交引入的”规范的type(scope): summary格式可以让git log --oneline的输出变成一本可浏览的目录。2.4 分支管理与 Code Review小型团队也能有的质量防线很多小型团队觉得 Code Review 是大型公司才需要做的事这是一个严重的误判。Code Review 第一价值不是抓 Bug而是同步上下文。哪怕只有两个人协作也必须走合并请求Merge Request流程。我建议的分支策略非常简单称为 trunk-based 的轻量版main分支始终保持可发布状态任何合并后的代码必须通过 CI。功能分支命名格式feat/xxx、fix/xxx、chore/xxx对应提交信息里的 type。合并回main前必须通过 CI 至少一位 reviewer 的批准。Code Review 的检查清单我做了精简只保留五个必须审查的点依赖方向是否正确domain 层是否引用框架代码。是否有死代码或注释掉的代码被顺手提交。核心逻辑是否配有测试。错误处理是否合理是否吞异常、是否缺少日志上下文。数据库迁移脚本是否可回滚。这条清单经历过几次事故后压缩成了现在的版本。最初清单有十几项执行率反而不如现在这个精简版人面对太长的清单会本能地敷衍。3. 实操过程与核心环节实现3.1 测试策略落地用测试金字塔决定优先级谈到 Testable很多人第一反应是“给所有代码写测试”。这个理解完全错了代价高昂且维护困难。正确做法是先明确测试金字塔的结构。我实际操作中采用的测试层级和比例大致如下层级定位典型数量比执行速度关键原则单元测试验证纯函数、领域规则70%毫秒级不访问网络/数据库集成测试验证接口与真实依赖交互20%秒级使用真实的测试数据库端到端测试验证关键用户流程10%分钟级只覆盖核心链路这里有一个非常反直觉的经验单元测试越多维护成本反而越低。因为单元测试定位精准失败时一眼就能看出哪个函数出了问题而端到端测试一失败经常需要排查半小时才能定位到具体原因。以我最近重构的一个用户注册模块为例单元测试覆盖了验证码校验、密码哈希、用户唯一性检查这些纯逻辑集成测试只测了调用真实 Redis 和 PostgreSQL 的环节端到端测试只保留两条核心用例注册后可以登录、重置密码后旧密码失效。跑一次完整测试套件的时间控制在三分钟以内超过三分钟就要反思是不是单元测试用到了外部依赖或者集成测试量过大。3.2 自动化检查流水线把把关交给机器配置 CI 的目标不只是“跑一下测试”而是把测试、静态检查、构建产物验证串成一个完整的流水线。下面是一个针对 Python 后端服务的 GitHub Actions 配置示例实际使用的是通用 CI 平台逻辑一致name: ci on: pull_request: types: [opened, synchronize, reopened] jobs: lint: runs-on: ubuntu-latest steps: - uses: actions/checkoutv4 - uses: actions/setup-pythonv5 with: python-version: 3.12 - run: pip install ruff - run: ruff check . test: runs-on: ubuntu-latest services: postgres: image: postgres:16 env: POSTGRES_PASSWORD: test ports: - 5432:5432 steps: - uses: actions/checkoutv4 - uses: actions/setup-pythonv5 with: python-version: 3.12 - run: pip install -e .[dev] - run: pytest tests/unit -q - run: pytest tests/integration -q这套 CI 在我看来有几个关键点值得说lint 和 test 分两个 joblint 失败时不需要等测试跑完反馈更快。集成测试使用服务容器PostgreSQL保证环境一致性避免“在我电脑上是好的”这种经典扯皮。pytest tests/unit和pytest tests/integration分开执行这样能明确看到是哪一层出了问题。在实际执行中我遇到过一个 CI 特有的坑本地跑测试全通过CI 却挂了原因是本地连接的 PostgreSQL 是旧数据CI 里用的是空数据库某条 SQL 依赖已知数据存在。解决方式是把测试夹具fixture改成显式创建数据而不是依赖数据库已有内容。这一点也呼应了前面说的“测试必须自包含”。3.3 性能优化清单别凭感觉先量化再改提到性能优化最常见的错误是凭感觉猜测瓶颈。我在t3code的工作流里加入了一个“量化优先”的检查清单每次性能问题进行优化时按顺序执行找到链路中最慢的三个接口用日志中记录的分位数P95/P99确认优化目标。使用 profile 工具Python 用 py-spyGo 用 pprof定位热点函数。先检查有没有明显低效的代码路径如循环内做 SQL 查询再考虑缓存。每完成一项优化重新对比优化前后的指标记录在优化文档中。这里有一个经典案例某个列表接口被反馈“很慢”初步看代码发现是内存中排序一个一万行的列表。直觉上会觉得是算法问题但用 py-spy 一抓热点其实是循环里逐条查询数据库补全用户名的 N1 问题。改成一次批量查询后接口耗时从 800ms 降到 90ms。优化记录模板我放在docs/operations/下每一条记录包含现象、定位方式、改动内容、优化前后数据。这样做让性能优化不再是一个“黑历史”而是可以回溯的技术积累。3.4 文档与知识沉淀写给人看的还是写给未来看的测试和 CI 解决的是代码正确性的问题Traceable 还要解决认知一致性的问题。我采用的文档策略很简单不写操作手册写决策记录和运行手册。决策记录ADR长这样## 决策用户会话使用 Redis 存储 状态已接受 背景多实例部署需要共享会话状态 选项JWT 无状态 / Redis 存储 / 数据库存储 决策Redis 存储理由支持主动失效可控性强 后果需要额外维护 Redis增加部署组件每篇决策记录必须包含“选项对比”和“后果说明”而不是只写结论。这样两个月后团队新成员问“为什么不用 JWT”时可以直接丢一篇 ADR 给他不需要反复口头解释。运行手册则相反它写给值班和排查问题的人内容包括环境变量清单、依赖服务列表、日志查看入口、常见报警处理步骤。这个手册平时不更新只在事故后根据复盘补增。4. 常见问题与排查技巧实录4.1 常见问题速查表这一节直接整理成表格全部来自真实场景问题典型原因排查方式解决办法pre-commit 改了文件导致提交失败格式化规则与本地编辑器不一致查看 pre-commit 输出中的变更文件统一编辑器配置对接 format-on-saveCI 跑测试通过部署后接口失败配置文件在 CI 与生产环境不一致对比 CI 和生产的 env 差异将配置结构校验写入启动流程单元测试数量很多但 Bug 率没下降测试只覆盖了实现细节没覆盖业务行为检查测试是否在断言“怎么实现”而非“什么结果”重构测试面向行为编写断言代码审查长期流于形式合并请求过大没人愿意细看检查 MR 平均改动行数限制单次 MR 改动范围控制在 400 行内日志缺失导致线上问题无法定位异常吞掉日志无上下文搜索代码中的except: pass增加结构化日志补充 trace_id排查问题的思维方式比具体工具更重要。遇到线上异常我的习惯是先看日志链路再复现最后看代码。直接读代码猜原因经常会被表面逻辑带到沟里日志里的实际堆栈和参数才是最诚实的真相。4.2 踩坑实录三次典型事故复盘挑三个印象最深的事故讲透。第一起是规则误伤问题。ruff开启--fix后自动把单引号改成双引号我本地编辑器用的是单引号风格结果每次提交十几个文件被顺手修改git diff里混入大量无关改动。这个问题的深层原因是配置文件与本地工具链没对齐最终通过统一 pyproject.toml 中的line-length和引用风格参数解决。第二起是集成测试数据污染。测试数据库用了统一的邮件域名导致并发跑测试时出现唯一键冲突。当时第一反应是加大随机后缀问题依旧随机出现。后来才意识到是测试并发导致的共享资源竞争解决方式是引入 pytest-xdist 并给每个 worker 分配独立的 schema。这个问题的教训是测试并行化不是免费的收敛共享状态是前提。第三起是提交规范推行的反弹。开始要求所有人用 Conventional Commits 时部分成员觉得增加负担提交信息依然随便写。处理方式不是强调纪律而是把commitizen集成到 pre-commit 钩子和 IDE 工具里让“正确的方式”成为路径依赖。两周后任何人想不规范提交反而更难。4.3 复盘模板让每一次事故都变成资产没有复盘的事故只是浪费了一次犯错的机会。我用一个极简的模板做复盘不搞仪式感背景什么功能、什么时间点出现什么问题 影响面哪些用户、哪些接口受影响 根因直接原因 深层原因流程盲区/工具缺失/认知不足 处理过程时间线从发现到恢复的关键动作 改进项必须具体可执行每一项排到负责人复盘会只开十五分钟超过十五分钟就该散会了。全部事项记录在 issue 里并关联到对应的合并请求下次有人踩到同一类问题时可以直接用链接回复无需重新解释一遍。这个模板我用过很多次最大的收获是改进项不能只写“加强测试”“注意规范”这种废话必须写成“为 register 接口补充重复用户名冲突测试用例”“在 CI 中增加未使用变量的 lint 规则”可执行可验证才有意义。复盘不是追责而是修改系统让同类问题从机制上更难发生。写到这里我不打算做“总结全文”这种事了。分享几个我现在仍在坚持的习惯每天早上打开代码库先看一条昨天新合并的 diff不合眼就直接问作者每周花半小时整理一下测试套件的执行时间超时了就拆每个季度强制自己用手写一遍项目的核心流程文档写不出来说明代码把复杂藏住了。t3code这套东西不是标准答案它只是我用三次失败换来的一个可行解。如果你在实际落地中踩到不一样的坑或者有更好的办法欢迎随时顺着这些思路继续展开。技术文章最怕的不是写得不对而是没有人踩出下一步。