1. 从"t3code"说起：一个被低估的代码分层思路

先说结论：t3code不是某个框架的名字，也不是什么新语言的代号。我第一次看到这个词是在一个开源项目的目录结构里，项目作者用 t3code 作为工程命名，拆开看就是 Tier 3 Code——三级代码。那个项目的服务端代码被分成了三层，每层职责极其单一，调用规则非常明确，整个仓库的代码量不到两万行，但业务迭代了三年多，几乎没有出现过"改一处崩一片"的情况。

我当时盯着目录结构看了很久，意识到这个命名背后其实藏的是一套非常实用的代码组织方法论。很多团队在项目初期不重视分层，所有逻辑堆在 Controller 或者 Service 里，等业务复杂起来再想拆分，成本已经很高了。t3code 的思路正好反着来：在写第一行业务代码之前，先定好三层的边界和依赖方向，后面所有开发都在这个框架里填内容。

这篇文章我打算把 t3code 这套思路完整拆开，讲清楚每一层到底该放什么、不该放什么，层与层之间的依赖规则怎么定，以及落地时最常见的坑是什么。无论你是在维护老项目想重构，还是新项目刚起步需要定规范，这套东西都能直接参考。适用面很广，Java、Go、TypeScript 甚至 Python 项目都能套用。

我自己的实践结论是：t3code 最大的价值不是它分了几层，而是它把"哪些代码能活多久"这件事提前想清楚了。什么意思？就是你要在设计阶段就分清哪些代码是长期稳定的、哪些代码是随业务频繁变动的，然后用分层把这两类代码隔离开。下面我从设计思路开始拆。

2. 为什么是三层：t3code 的设计逻辑与核心概念

2.1 三层到底分的是什么

先不急着给三层命名，我们先想一个问题：一个业务的代码，本质上在做几件事？

第一件事是跟外部世界打交道，接收 HTTP 请求、解析参数、做基础校验、把结果转成响应格式。第二件事是处理业务规则，比如下单要算总价、要扣库存、要检查优惠券是否过期。第三件事是跟基础设施打交道，读写数据库、调用第三方接口、发消息队列。t3code 就是把这三种完全不同性质的工作拆到三个独立的层里。

我习惯把这三层叫做接入层、业务层、数据层。有的团队也叫 Controller / Service / Repository，有的叫 Interface / Application / Infrastructure，名字无所谓，核心是职责边界。如果你见过那种两三万行代码全堆在一起的老项目，你一定会理解这种拆分的必要性——所有代码挤在一起，意味着每次改动都要把整段逻辑从头到尾看一遍，而且完全没办法独立测试。

三层划分还有一个隐藏的好处：它天然对应了团队分工。接入层关心协议和参数，适合偏前端的后端同学维护；业务层关心规则和流程，适合核心业务开发；数据层关心存储和查询效率，适合对数据库更熟悉的同学。当然小团队可能一个人全包，但分层的代码至少能让你在不同阶段切换上下文时脑子里有个清晰的地图。

2.2 依赖方向的铁律：只能从上往下

t3code 里面最重要的一条规则不是"要分三层"，而是"依赖方向只能从上往下"。什么意思？就是接入层可以依赖业务层，业务层可以依赖数据层，但反过来不行。这一条规则比所有命名规范和代码风格都重要，我甚至觉得它是 t3code 的灵魂。

为什么这么强调方向？因为一旦数据层反过来依赖业务层，你的项目就会出现循环依赖，编译期报错或者运行期死循环都是小事，真正可怕的是逻辑混乱到没人能改。你想想看，如果 Repository 里写了一行代码去调用 Service 里的某个方法，那 Service 也调 Repository，这两层就完全耦合在一起了，分层就名存实亡。

我自己在上一个项目就吃过这个亏。当时为了省事，在数据层直接调了业务层的某个工具方法，结果三个月后那个工具方法改了签名，数据层所有调用点跟着崩，排查了一个下午。从那以后我就立了一个规矩：如果数据层需要某个逻辑，这个逻辑就必须下沉到数据层自己实现，或者抽到独立的公共模块，绝不允许跨层向上调用。这个规矩写进团队的代码规范，后来再没出过类似问题。

依赖方向的检查其实很简单，代码评审的时候多看一眼 import 语句就行。如果你用 Go，可以用 go list 做依赖分析；Java 可以用 ArchUnit 写单元测试来守护边界；TypeScript 可以用 ESLint 的 import 规则限制目录之间的引用。工具一堆，关键是要把规则定下来并坚持执行，比用什么工具更重要。

2.3 三个核心概念：职责单一、依赖倒置、边界守护

t3code 的整个方法论浓缩下来就是三个词：职责单一、依赖倒置、边界守护。

职责单一说的是每一层只干自己那一类事。接入层不写 SQL，业务层不拼 HTML，数据层不解析 HTTP 参数。这个原则听起来简单，实际执行起来很容易被破坏，因为总有一些代码你觉得"放哪都行"。比如一个把时间戳转成日期字符串的工具方法，你可能随手就放在 Controller 里了，然后 Service 也要用，又复制了一份。这种代码就应该抽到独立工具类里，或者放在数据层的基础能力里，让上层按需调用。

依赖倒置在 t3code 里的体现，主要是通过接口把层与层之间的耦合降到最低。举个例子，业务层需要的"订单存储"能力，不直接依赖 MongoDB 或者 MySQL 的具体实现类，而是依赖一个 OrderRepository 接口，然后数据层去实现这个接口。这样一来，业务层根本不关心底层是 MySQL 还是 NoSQL，只要接口不变，底层随便换。这对后面做读写分离、分库分表、单元测试打桩都极其重要。

边界守护是自动化层面的保障。前面说了，人的记忆和自觉都不可靠，真正可靠的是把规则写进代码库里自动执行。我第一次在项目里引入 ArchUnit 写依赖规则测试的时候，同事还觉得是小题大做，结果这个测试在两个月内拦下了十几次违反依赖方向的提交。从那以后，边界守护测试成了我们所有后端项目的标配。你要问我 t3code 和普通分层最大的区别是什么，我的回答就是：普通分层靠自觉，t3code 靠机制。

3. 逐层拆解：接入层、业务层、数据层各自的核心职责

3.1 接入层：只做翻译，不做决策

接入层在 Web 项目里通常对应 Controller，在命令行工具里对应 Command，在消息消费者里对应 Listener。它的核心职责是"翻译"：把外部输入翻译成内部结构，再把内部结果翻译成外部响应。

具体来说，接入层要做的事情包括：解析 HTTP 请求参数、做基础的格式校验（比如邮箱格式、手机号位数）、鉴权注解的声明、调用业务层方法、把返回结果包装成统一的响应体。除了这些，什么都不要多干。不要在 Controller 里写业务判断，比如 if (user.getBalance() > price) 这种代码，应该出现在业务层，而不是接入层。

这里我踩过一个特别典型的坑。有一次做订单接口，我图省事在 Controller 里直接判断了库存是否充足，不充足就返回错误信息。后来新增了一个渠道，这个渠道允许超卖预下单，我需要在 Service 里跳过库存检查，但 Controller 里的判断拦在前面，怎么都绕不过去。最后只能改 Controller 代码，连带影响了其他渠道的调用。从那以后我彻底明白了，Controller 里只该做跟 HTTP 协议相关的事情，任何业务判断都必须下沉到 Service。

接入层怎么判断自己是否"干净"？有一个很简单的自测方法：你把 HTTP 相关的注解全部去掉，改成命令行直接调用，核心逻辑是否还能跑？如果业务代码仍然能顺畅执行，说明接入层的逻辑确实没有侵入业务；如果发现业务逻辑依赖了请求对象，说明职责混了。我在重构老项目时经常用这个方法来检测每段代码的归属。

3.2 业务层：核心规则的唯一住所

业务层是整个 t3code 里最重要的一层，因为它承载了项目最核心的价值——业务规则。业务层的代码应该做到完全不感知 HTTP 的存在，也不关心数据存储用的什么数据库。它只接收领域对象或者简单参数，处理规则，然后返回结果。

业务层的典型内容包括：订单金额计算、库存扣减与回滚、优惠策略匹配、状态流转判断、聚合根的操作等等。这些代码的特点是"变化频率高"，因为业务规则总在变，今天满减规则调整，明天运费策略修改。正因为变化频繁，它必须被隔离在单独的层里，不能跟稳定的数据层代码混在一起。

做业务层设计的时候，有个重要的思维方式叫"用例驱动"。就是不要按照"用户管理""订单管理"这种资源维度去组织 Service 类，而要按照业务用例来组织。比如下单是一个用例、取消订单是一个用例、售后发起是一个用例。每个用例对应一个独立的业务方法，方法内部清晰地表达核心业务逻辑。这种组织方式对于需求频繁变更的场景特别友好，新需求来了只需要新增一个用例方法，或者修改对应的方法，不会牵连到其他无关逻辑。

我在业务层还特别强调一个纪律：事务边界放在这一层。也就是说，@Transactional 注解应该加在业务层方法上，而不是数据层。因为一个业务用例往往要操作多个数据实体，只有在业务方法这一级别开启事务，才能保证所有数据变更的一致性。如果你把事务加在数据层方法上，事务的粒度太细，两个数据操作之间发生异常就没办法整体回滚。

3.3 数据层：屏蔽存储差异，稳定压倒一切

数据层在 t3code 里的角色是"稳定的底座"。它负责跟数据库、缓存、搜索引擎、第三方系统打交道，向上层提供持久化能力。这一层的代码变化频率最低，但基础重要性最高，一旦出错就是线上事故级别的。

数据层的核心设计目标是"屏蔽存储差异"。业务层调用 OrderRepository.FindByID，它不应该关心这个 ID 是从 MySQL 查出来的还是从 Redis 缓存里读的。数据层内部自己处理缓存与数据库的一致性、读写分离的路由、分表的逻辑等等。所有这些存储相关的技术细节，都被封装在数据层内部，上层完全不需要感知。

有些团队把 ORM 实体和数据库表结构完全暴露给上层，业务代码里到处能看到数据表字段名，这其实已经破坏了封装。数据层应该向上层返回领域对象，而不是底层数据表结构。举个例子，订单表里有 status 字段，值是 0/1/2，数据层应该把 0/1/2 翻译成订单状态的枚举对象再返回给上层，而不是让 Service 去猜 0 是什么意思。这样后续数据库结构调整、字段值语义变化，影响范围都能控制在数据层内部。

另外我强烈建议数据层要做"读写分离的预留设计"。哪怕现在项目流量不大，单库就够用，也应该把读操作和写操作的接口分开定义，将来做读写分离时就只改数据层内部实现即可，业务层一行代码都不用动。这就是依赖倒置原则在存储层面带来的红利。

4. 实操落地：从零搭一个 t3code 工程

4.1 目录结构与命名规范

下面直接给一个可以抄作业的目录结构示例，这里用 Go 语言展示，但思路完全适配其他语言。

project-root/ ├── internal/ │ ├── handler/ # 接入层：HTTP Handler │ │ ├── order.go │ │ └── user.go │ ├── service/ # 业务层：用例编排 │ │ ├── order_service.go │ │ └── user_service.go │ └── repository/ # 数据层：持久化实现 │ ├── order_repo.go │ └── user_repo.go ├── pkg/ │ ├── domain/ # 领域对象与枚举 │ └── kit/ # 公共工具库 └── cmd/ └── server/ └── main.go # 启动入口

这个结构里，handler、service、repository 三个目录分别对应三层。domain 放领域对象和业务枚举，它不属于任何一层，而是被各层共同依赖的基础模型。kit 放工具方法，比如时间处理、字符串转换、加密算法。cmd 是启动入口，负责初始化依赖关系和启动 HTTP 服务。

层与层之间的调用规则很简单：handler 调 service，service 调 repository。domain 和 kit 可以被任何层引用，但不允许反过来引用。在代码评审时，重点检查这三个目录之间的 import 是否符合规则，发现违规直接打回修改。

我这里选的目录命名是行业里最流行的，因为大部分开发者看到 handler/service/repository 就能秒懂代码位置。有的团队叫 controller/service/mapper，意思一样，看你团队的既有习惯。命名不统一是小事，职责边界混乱才是大事。

4.2 接口先行：每层的通信契约怎么定

t3code 在实操层面的一个重要做法是"接口先行"。上一层对下一层的依赖，不是直接依赖具体实现类，而是依赖接口。具体来说，service 层依赖 repository 接口，handler 层也尽量依赖 service 接口。

接口先行的直接好处是测试变得异常容易。比如你要单测 service 层的下单逻辑，如果 service 直接依赖一个具体的 repository 实现，那测试就必须连数据库；但如果 service 依赖的是 OrderRepository 接口，测试时就可以用一个内存版的 mock 实现传入，跑完断言结果即可。我在项目里特别喜欢这种模式——因为测试跑得快了，大家才愿意多写测试；如果每个单测都要连数据库，没人会坚持下去。

下面用一个伪代码示例说明接口定义方式：

// 数据层接口定义 type OrderRepository interface { Create(ctx context.Context, order *Order) error FindByID(ctx context.Context, orderID string) (*Order, error) UpdateStatus(ctx context.Context, orderID string, status OrderStatus) error } // 业务层接口定义 type OrderService interface { CreateOrder(ctx context.Context, req CreateOrderReq) (*CreateOrderResp, error) CancelOrder(ctx context.Context, orderID string) error }

注意一个细节：接口方法的参数和返回值，尽量使用领域对象，不要直接透传底层数据结构和高层 HTTP 结构。比如 CreateOrder 方法，它接收的参数是 CreateOrderReq 这个业务请求对象，而不是绑定了 JSON 标签的 HTTP Request DTO。这样业务层的服务就能被多种接入方式复用——HTTP 可以用，GRPC 可以用，命令行也可以用。

4.3 依赖注入与启动装配

有了接口定义，接下来要做依赖注入。所谓依赖注入，简单理解就是在程序启动时把各层的具体实现装配起来，然后传给需要它们的上层。

我用一个最朴素的"手写依赖装配"来说明，不引入任何框架：

func main() { // 实例化数据层 db := mysql.NewConnection() orderRepo := repository.NewOrderRepo(db) userRepo := repository.NewUserRepo(db) // 实例化业务层 orderService := service.NewOrderService(orderRepo, userRepo) userService := service.NewUserService(userRepo) // 实例化接入层并注册路由 orderHandler := handler.NewOrderHandler(orderService) userHandler := handler.NewUserHandler(userService) // 启动 HTTP 服务 router := setupRouter(orderHandler, userHandler) router.Run(":8080") }

这段代码的装配逻辑非常清晰：先实例化依赖最底层的数据层，再向上装配业务层，最后装配接入层。每个构造函数都明确声明了自己需要哪些依赖，没人能偷偷跳过一层去直接操作底层组件。

有的团队用 Spring 或类似框架做自动装配，这也可以，但我建议即使有框架，也要保持构造函数注入的习惯，不要用字段注入或全局单例。字段注入最大的问题是你要运行到那段代码才能发现依赖没注入成功，而构造函数注入在启动瞬间就能暴露问题。

4.4 事务控制与并发安全：业务层的两大责任

事务控制前面说过要放在业务层，这里展开讲一下具体怎么落地。在 Go 项目里我常用的方案是定义一个事务管理器接口：

type TransactionManager interface { WithinTransaction(ctx context.Context, fn func(ctx context.Context) error) error }

调用方式是在业务层方法里这样写：

func (s *OrderService) CreateOrder(ctx context.Context, req CreateOrderReq) error { return s.txManager.WithinTransaction(ctx, func(ctx context.Context) error { if err := s.orderRepo.Create(ctx, order); err != nil { return err } if err := s.stockRepo.Deduct(ctx, productID, quantity); err != nil { return err } return nil }) }

这样写的好处是事务的开启与提交完全由 WithinTransaction 统一管理，业务方法只需关注自己的核心逻辑。任何一步返回 error，整个事务自动回滚，不需要在每个方法里手动写 begin/commit/rollback。

并发安全方面，业务层要做的是"关键资源的并发控制"。典型场景是库存扣减。最稳妥的做法是在数据层用原子的条件更新操作，比如 SQL 里直接写UPDATE stock SET quantity = quantity - ? WHERE product_id = ? AND quantity >= ?，用数据库的原子性和行锁来保证并发安全。尽量避免在业务层先查出来再算一遍再更新回去，这种"读改写"在三步之间极易发生并发覆盖问题。

5. 常见问题与排查技巧实录

5.1 循环依赖：最先炸的雷

循环依赖是 t3code 落地时最典型的问题。A 层调 B 层，B 层又调 A 层，代码编译期可能过（比如 Go 包级循环引用会在编译期直接报错），但逻辑上的循环依赖往往非常隐蔽。

我遇到过的真实案例：Service 层需要读取当前登录用户的信息，直接调用了一个 UserHandler 的方法；而 UserHandler 的正常调用链是 handler 调 service，这就形成了 cycle 的印象。实际上正确做法是：handler 在入口处解析登录用户信息，传给 service 作为参数；或者 service 依赖一个 SessionContext 的抽象来获取用户信息，而不是直接调用另一个 handler。

排查循环依赖，最快的工具是看包依赖图。Go 语言编译时遇到循环导入会直接报 import cycle not allowed，Java 的 ArchUnit 会在测试时给出完整的依赖环路径。如果你用的是 Python，可以写一段脚本扫描 import 关系来检测环。实践中最有效的还是从设计上杜绝：每写一层代码之前，先问自己一句"这行代码放在这层真的合适吗"，能把大部分循环依赖掐死在源头。

5.2 事务失效：为什么回滚没生效

事务失效是业务层最容易踩的坑，而且排查起来特别折磨人，因为它不报错，只是悄悄写入了脏数据。总结了我在实战中踩过的三类情况：

第一类：同类方法互相调用导致事务绕过。Spring 的 @Transactional 默认走代理，同类内部方法调用 this.cancelOrder() 时，代理不生效，事务注解就成了摆设。解决方案是把需要事务的方法拆到独立的 Service Bean 里，或者自己注入代理对象再做调用。

第二类：异常被吞掉。有的同学在业务方法里写了 try-catch，把异常捕获后只记录日志不抛出，事务管理器根本感知不到异常发生，自然无法回滚。正确做法是：事务管理器捕获到任何 error 都要向外抛，至少抛到外层统一处理。

第三类：事务管理器没有真正开启事务。比如配置了错误的数据库连接池，把连接设置为 autocommit，或者事务管理器管理的数据库连接和真正执行 SQL 的连接不是同一个数据源。这种情况最隐蔽，要通过打印 SQL 日志确认是否真的出现了 BEGIN / COMMIT 语句。

5.3 命名混乱：分层被"伪分层"架空

还有一种我特别想提醒的情况：目录结构按三层建了，但代码实际写的还是"伪分层"。怎么判断？最简单的指标是看 Service 层是否有大量的 SQL 拼接，看 handler 层是否长了超过 50 行，看 repository 层是否有 HTTP 请求逻辑。如果出现这些情况，说明分层的框架只是摆设，本质还是一个大泥球。

我曾接手过一个项目，Repository 类里居然有调用第三方支付接口的代码，Service 类里有解析 Excel 的逻辑，Handler 类里有发短信的代码。整个项目在结构上分了层，但实际每个类都是一个大杂烩。当时我做了两个月的重构，才把混乱的职责一点点归位。

要避免这个局面，除了在评审时从严把关，我还推荐一个"代码体检"做法：每季度随机抽几个关键类，统计类的方法数量、每个方法的代码行数、方法内部依赖的组件类型。如果发现某个类方法数超过 15 个或者平均方法长度超过 80 行，就列为重点重构对象。这个方法不花多少时间，但对防止代码腐化非常有用。

以下是排查速查表，我整理在下面方便你直接参考

5.4 过度分层：不要为了分层而分层

最后一类问题是过度分层。有些团队把三层又细分成了五层七层，每层之间只做简单的透传，代码绕了一圈最后什么都没做。这种设计不仅不会提升代码质量，还会显著增加维护成本——改一个字段要穿透四五层函数签名。

我个人的判断标准是：如果某一层的方法只是无脑调用下一层同名方法，没有任何逻辑编排或规则处理，那这层就是多余的。t3code 的模型是三层，不是因为它只能分三层，而是因为大多数业务场景下，三类职责的划分已经足够。你的项目如果真出现了四层、五层的诉求，请先确认每层是否真的有独立的职责在支撑，而不是为了让架构图好看。

简单业务起步时，我甚至建议从"两层半"开始：handler 一层、repository 一层，service 层暂时可做可不做。等业务规则真的开始复杂了，再把 service 层独立出来。这比我一开始就硬套三层更务实，也更能让团队理解每一层存在的理由。

6. 工具选型与团队落地的经验补充

6.1 常用工具推荐

做 t3code 落地，有四个维度的工具值得关注：接口文档工具、依赖检查工具、单元测试框架、代码规范检查工具。

接口文档方面，如果你用 Go 可以用 swag 自动从 handler 注释生成 Swagger 文档，Java 可以用 springdoc，TypeScript 可以用 @nestjs/swagger。文档的作用不只是给前端看，更重要的是反向约束 handler 层的参数定义——参数必须清晰、必须可校验、必须面向调用方。

依赖检查方面，前面提过 ArchUnit 是 JVM 生态的王者，Go 可以用 go list 配合自定义脚本，Python 可以用 pip-audit 或者简单的 AST 扫描。这类检查一定要接入 CI，让规则自动跑，而不是依赖人工评审记忆。

单测框架按语言选成熟方案即可。为了推进单测，我建议在业务层优先写核心用例的测试，数据处理层连一个测试库做集成测试，handler 层用轻量的 HTTP mock 测试。三层各有各的测试策略，不必强求统一。

代码规范方面，Go 直接用 gofmt + golangci-lint，Java 用 Checkstyle + SpotBugs，前端用 ESLint + Prettier。这些工具最重要的意义不在于它的规则本身，而是让团队在格式层面减少争议，把精力留给真正重要的逻辑讨论。

6.2 团队推行时的三个要点

在团队里推行 t3code，光靠发规范文档是不够的。我有三点实操经验可以分享。

第一，小步试点，不要全量切换。选一个中等复杂度的业务模块做样板，整个团队看着这个模块一步步从零到落地，比看十页文档都有效。样板模块做完后，后续需求按同样模式开发，新人也容易照着抄。

第二，把规则写进代码评审清单。我团队现在的评审清单里有一条固定问题："这个改动涉及的层是否清晰？有没有跨层调用？"每次评审必问，形成肌肉记忆。

第三，定期做依赖方向审计。每季度用工具扫一遍依赖关系，把违规点列出来修复。这个审计的结果要公开，让团队看到趋势。是违规在变少，还是在悄悄变多，数据比感觉可靠。

6.3 哪些项目不适合 t3code

最后说实话，不是所有项目都适合 t3code。以下几种情况，强行套三层反而添乱。

极小的原型项目或者一次性脚本，没必要分层，代码全部放一个文件更快更直接。数据密集型的批处理任务，逻辑主要在 SQL 和数据处理流程上，分层带来的收益有限。完全没有后续迭代的临时工具，写了能用就行。还有，如果团队人数只有一两个人且没有扩展计划，分层的维护成本也可能超过收益。

判断标准很简单：这个项目是否会持续迭代半年以上？是否有多人协作的可能？是否有清晰的业务规则需要长期维护？三个问题里有两个"是"，t3code 就值得上；否则，怎么简单怎么来。

7. 最后分享一点个人体会

t3code 这套架构方法，我使用了三年多，从最初的手动检查依赖方向，到后来靠自动化工具守护边界，过程里踩过的坑比这里写到的要多得多。但它带给团队的最大改变不是代码结构变清晰了，而是人的思维方式变了——每个人在写代码之前，都会先想一句："这行代码放到哪一层，半年后我去改它的时候，找起来方不方便？"

这个问题的答案往往比任何架构原则都好用。你不需要背熟每一层的定义，只需要在落笔之前多花三秒钟想一下职责归属，三分之二的架构问题其实都能被消灭在编写阶段。等到项目到了几百个文件、几十万行代码的规模，你会感谢当初那个愿意多思考三秒钟的自己。

我给新人的建议也很简单：不要急着在你的第一个项目里就追求完美的三层拆分，先把功能写出来，再在第二个版本里做一次"职责归位"的重构。重构的过程会让你真正理解每一层存在的理由。有了那次亲身体验，你再回头看 t3code 的规则，根本不需要背，自然就懂了。