企业官网建设流程全解析

1. 写在前面：t3code 到底解决什么问题

如果你在团队里写过一阵子代码，大概率经历过这种场景：代码能跑，但没人敢动；新人接手要花两周摸清业务逻辑；每次 Code Review 都在争论缩进和命名；线上出问题，靠打印日志一点点猜。这些现象背后其实是一个共同的问题——代码缺少一套稳定、可解释、可传承的规范体系。t3code 这个名字，我第一次听到时还以为是某个框架的代号，后来才明白，它更像是一种工程化治理的思路：把代码质量从“靠自觉”推向“靠机制”。

t3code 的全称可以理解为 Tier 3 Code，也就是第三层代码。如果说第一层是“能运行”，第二层是“可维护”，那么第三层就是“可演进”——代码不仅要满足当前需求，还要能支撑团队在未来半年、一年甚至更长的时间周期里持续迭代。这个定位听起来玄，但落地起来非常具体，它包含命名规范、模块边界、状态管理、错误处理、测试策略、代码评审标准等多个维度。适合谁看？如果你是前端或后端工程师，正在带团队，或者被混乱的代码库折磨过，这篇内容值得花十分钟读完。我会把 t3code 的拆解思路、落地步骤、踩过的坑一次讲清楚。

2. 整体设计思路：从命名到架构的分层治理

2.1 为什么叫“第三层代码”

我习惯把代码质量分成三个层次来理解。第一层是功能层，代码能实现需求，跑通流程，这是底线；第二层是质量层，代码有清晰的命名、合理的拆分、基本的测试覆盖，团队协作不痛苦；第三层是演进层，代码具备应对需求变化的能力，新功能可以在既有结构上自然生长，而不是推翻重来。t3code 关注的就是第三层。

这层目标靠什么达成？靠的不是某一次重构，而是一套贯穿开发全流程的约束。我把 t3code 的设计原则总结为三条：显式优于隐式，组合优于继承，约定优于配置。显式优于隐式，意思是函数参数、组件 props、模块导出都明确定义，不靠上下文猜；组合优于继承，是说复用逻辑优先用函数组合、组件嵌套，而不是层层继承；约定优于配置，则是团队内部形成统一约定，减少不必要的配置项和分支逻辑。

这三条原则不是拍脑袋定的。我见过太多项目死在“灵活”上：配置项多到没人敢改，继承链深到查 bug 要翻五个文件，全局状态到处挂，改一处崩三处。t3code 的思路是先把规则定死，把自由度控制在规则之内，这样团队才能真正跑起来。

2.2 t3code 的整体架构拆解

如果把 t3code 当作一个项目来看，它的核心模块大致可以分为五层：入口层、领域层、应用层、基础设施层和共享层。入口层负责接收外部输入，比如 HTTP 请求、消息队列消息、定时任务触发；领域层承载核心业务逻辑，不依赖具体框架；应用层编排领域层的服务，处理事务、权限、接口协议；基础设施层封装数据库、缓存、第三方 SDK；共享层放通用工具、常量、类型定义。

这个分层和常见的 MVC 分层的区别在于，它把业务逻辑和框架解耦了。比如用 Node.js 写后端，Express 的 router 只做参数解析和响应封装，真正的业务逻辑放到领域层；用 React 写前端，组件只负责渲染和交互，数据获取和状态更新放到应用层的 hooks 或 store 里。这样做的好处是，框架升级、换技术栈时，核心业务代码可以原样保留，改动集中在基础设施层。

我见过太多项目把业务逻辑写进 Controller 里，接口一多，Controller 膨胀成几千行的怪兽文件。t3code 的分层思路就是避免这种情况，让每一层各司其职，依赖方向从入口层指向领域层，领域层不依赖任何上层模块。

3. 核心细节解析：命名、模块与状态管理

3.1 命名规范：让代码自己会说话

命名是代码规范里最不起眼、但影响最大的部分。t3code 对命名的要求很简单：名字要准确描述“是什么”或“做什么”，禁止用含义模糊的词。比如变量名用userList而不是data1，函数名用getUserById而不是getStuff，组件名用UserProfileCard而不是Card。

这里有个容易忽略的细节：布尔变量和函数的命名方式。布尔变量用is、has、can开头，比如isLoading、hasPermission、canEdit，这样在条件判断里读起来非常顺；函数名用动词开头，fetch、create、update、delete、validate，一眼就知道这个函数的动作是什么。这个习惯养成之后，代码的可读性会提升一大截，Review 的时候也少了很多无谓的争论。

另一个细节是文件命名。t3code 约定文件命名与导出内容一致，useUser.ts导出useUserhook，userService.ts导出userService对象或类。这样当你在代码里看到一个 import 语句，不需要打开文件就知道里面是什么，定位问题的时间大幅缩短。

3.2 模块边界：防止代码腐化的第一道防线

模块边界是 t3code 最核心的治理点。很多项目前期跑得快，后期改不动，根因就是模块之间互相引用，形成了一张剪不断理还乱的依赖网。t3code 的做法是让模块的依赖关系呈现为有向无环图，禁止循环依赖。

落地时主要靠两个手段：一是目录结构的强制性约定，二是脚手架的自动校验。目录结构上，每个业务模块是一个独立目录，内部再按照api、components、hooks、utils、types分子目录；模块之间不能跨层引用，比如api层不能引用components层的东西。自动校验则通过 lint 规则或脚本实现，检测到循环依赖或跨层引用时直接报错。

有人会觉得这样太死板，但我的经验是：自由是混乱的根源。你给团队一百个自由度，他们就能创造出一百种写法。边界定死了，代码结构反而稳定，维护成本也低。后续想加功能、抽公共组件、拆服务，都变得非常轻松。

3.3 状态管理：区分服务端状态与客户端状态

状态管理是前端项目最容易被搞乱的地方。t3code 里的核心原则是：区分服务端状态和客户端状态。服务端状态是从接口获取的数据，比如用户列表、订单详情，这类状态的特点是会被多个页面共享，需要缓存、同步、失效处理；客户端状态是 UI 层面的临时数据，比如弹窗开合、表单输入值、当前选中 tab，这类状态只影响当前页面或组件，不需要全局共享。

对应的方案是：服务端状态用专门的请求缓存库管理，比如 React 生态里的 TanStack Query、Vue 生态里的 Vue Query；客户端状态用轻量级的 store 或组件状态管理。不要所有数据都往全局 store 里塞，那会让 store 变成垃圾场，改一个字段触发十几个组件重新渲染。

实际项目中我见过最典型的问题：团队把所有接口数据都放进 Redux，然后到处 dispatch action，调试的时候根本不知道数据从哪里来、在哪里被修改、为什么触发渲染。按 t3code 的思路调整之后，请求缓存库负责数据获取和缓存，store 只放跨页面共享的客户端状态，代码清晰度和性能同时提升了。

4. 实操过程：一步步把 t3code 落地到项目

4.1 第一步：建立项目骨架与目录规范

要落地 t3code，首先要从项目骨架开始。我以 TypeScript + React + Node.js 的全栈项目为例说明，但这个流程同样适用于 Vue、Python、Go 等其他技术栈。

先建立目录结构。前端部分按照src/app、src/features、src/components、src/hooks、src/lib、src/types来组织。src/app放应用入口、路由配置、全局样式；src/features按业务模块划分，每个模块内部再分api、components、hooks、utils；src/components放跨模块复用的通用组件；src/hooks放通用自定义 hooks；src/lib放第三方封装和工具函数；src/types放全局类型定义。

后端部分按照src/routes、src/controllers、src/services、src/repositories、src/models、src/middlewares来组织。routes只定义路由映射；controllers处理请求参数、调用服务、返回响应；services承载业务逻辑；repositories封装数据访问；models定义数据模型和数据库交互；middlewares放鉴权、日志、错误处理等中间件。

这套结构刚建立的时候会觉得繁琐，但坚持两周之后，你会发现自己找文件的效率明显提高，新人也更容易上手。

4.2 第二步：接入 lint 与格式化工具

目录结构搭好了，接下来要保证代码风格一致。这里的核心工具是 ESLint 和 Prettier。ESLint 负责代码质量规则，比如不允许未使用的变量、不允许隐式 any、不允许循环依赖；Prettier 负责代码格式，比如字符串用单引号还是双引号、缩进用几个空格、换行规则。

接入的时候有几个关键配置：eslint-config-airbnb或eslint-config-standard作为基础规则，再加 TypeScript 插件支持类型检查，加eslint-plugin-import校验导入顺序和循环依赖，加eslint-plugin-react-hooks校验 hooks 使用规范。Prettier 和 ESLint 的规则要处理好，避免冲突，做法是关闭 ESLint 中与格式相关的规则，格式问题统一交给 Prettier。

这里要重点说 hook 的 lint 规则。React 的 hook 有个铁律：只能在组件顶层调用，不能在循环、条件、嵌套函数里调用。这条规则靠人记很容易出错，但接入 eslint-plugin-react-hooks 之后，代码写错了直接报错，从源头杜绝了此类问题。

另外在 CI 流程里把 lint 和测试设为必须通过的检查项。代码提交之前，本地先跑 pre-commit hook 自动 format 和 lint，不合格的代码根本进不了代码库。这会带来一点额外工作，但省下来的 Review 争论时间远超投入。

4.3 第三步：制定并推行代码评审标准

代码评审是 t3code 落地的关键环节。很多团队的 Code Review 流于形式，Reviewer 只看有没有语法错误，不看架构、不看边界、不看测试。t3code 的思路是把评审标准显式化，让每个人都按同一套标准来审。

我建议把评审标准分成三个等级。阻断级，包括逻辑错误、安全问题、性能隐患、明显 bug，这类问题必须修改后才能合并；建议级，包括命名不够清晰、模块拆分不合理、缺少必要注释，这类问题可以讨论后决定是否修改；偏好级，包括个人风格差异、非功能性重构，这类问题不作为合并门槛。

评审的时候，Reviewer 重点看这几个点：改动是否符合现有的模块边界、是否有循环依赖、是否有重复代码、有没有充分的测试覆盖、错误处理是否完善、类型定义是否严格、是否有不必要的破坏性变更。把这些点列在评审模板里，每次评审按模板走，效率会高很多。

我自己的经验是，Code Review 最忌讳的一句话是“我觉得这样写不好”。这句话没有信息量，对方也不知道怎么改。更好的表达方式是“这里如果改成 XXX，可以避免 XXX 问题”。给出具体的修改建议，而不是泛泛的评价，Review 才能真正帮助团队进步。

4.4 第四步：测试策略与覆盖率要求

t3code 对测试的要求是有取舍的，不是追求 100% 覆盖率，而是把重点放在核心业务逻辑和关键链路上。我常用的分层是：单元测试覆盖领域层和服务层的纯逻辑，比如价格计算、状态流转、权限判断；集成测试覆盖接口层和数据库交互，确保路由、控制器、服务、仓储能正常串联；端到端测试覆盖关键用户流程，比如登录、下单、支付，这类测试数量不用多，但必须跑得稳。

前端测试方面，组件测试用 Testing Library，重点测交互行为而不是实现细节；hooks 测试用 renderHook，验证状态更新逻辑；工具函数测试直接单测。后端测试方面，服务层的纯函数单测，数据库相关的用真实测试库或内存数据库，避免 mock 太深导致测试失真。

覆盖率不是一个绝对指标，但我建议核心模块的语句覆盖率维持在 80% 以上，分支覆盖率 70% 以上。这个数据不是用来应付检查，而是让你在重构的时候有底气——覆盖率够了，改代码才不会心虚。

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

5.1 团队阻力：成员嫌规范麻烦怎么办

推行 t3code 这类规范时，最大的阻力往往不是技术问题，而是团队成员的习惯和心态。有经验的老手会觉得“我写代码这么多年了，不需要这些条条框框”；刚入门的新人会觉得“规范太多了，记不住”。

我自己的做法是分三步走。第一步，先用工具强制约束，不靠人盯，脚手架自动检查命名、格式、依赖方向，不符合规范就报错；第二步，做一次规范宣讲，把每条规范背后的原因讲清楚，比如“为什么不能用 any，因为 any 会让类型检查失效，重构的时候会漏掉错误”；第三步，树立正向反馈，把规范执行到位的代码作为示例展示，让大家看到整洁代码和混乱代码的维护成本差异。

还有一个技巧：不要一次性推行全部规范。第一周只推目录结构和命名规范，第二周加 lint 和格式化，第三周推模块边界和状态管理规范。小步快跑，团队接受度会高很多。

5.2 循环依赖：查不完的报错怎么破

循环依赖是模块边界治理中最常见的问题。比如 A 模块引用了 B 模块的工具函数，B 模块又引用了 A 模块的类型定义，看起来没问题，但随着代码增长，这种互相引用会越来越多，最后导致初始化顺序错误、运行时 undefined、打包体积膨胀。

排查方法我推荐两个。一是用依赖分析工具，比如madge，在 Node.js 项目里运行npx madge --circular src/，它会直接列出所有循环依赖的文件路径；二是人工审查关键路径，从入口文件开始，沿着 import 方向走一遍，看看哪些模块是互相指向的。

根治方法是在架构层面处理，把公共依赖抽到更底层的模块。比如 A 和 B 都依赖的常量、类型、工具函数，放到共享层目录里，A 和 B 都只引用共享层，不再互相引用。这听起来简单，但需要大家统一认知，否则过两周又会被“图方便”的写法破坏。

5.3 状态管理失控：store 怎么越写越乱

关于状态管理，我见过的最经典失控模式是这样：团队引入 Redux，然后为了“方便”，把接口请求、表单状态、弹窗开关全部放进了全局 store。结果就是 store 里几百个字段，组件 rerender 频繁，调试工具里 action 刷屏，改一处数据要追查十几个 reducer。

排查思路是先做分类梳理。打开 store，把每个字段按“服务端状态”和“客户端状态”分类：接口返回值、缓存数据归入服务端状态，改用请求缓存库管理；UI 临时状态、表单值、弹窗开关归入客户端状态，改用组件状态或轻量 store。划分清楚之后，原来的全局 store 会瘦身一大半，剩下的就是真正需要跨模块共享的数据，比如用户登录信息、主题设置、权限配置。

这里有个我踩过坑的细节：迁移过程中，服务端状态不要一下子全抽走，按模块逐步迁移，每迁移一个模块就跑一遍相关测试，确保数据流没有断裂。这个过程中你会对项目的状态流有更清晰的理解，未来的改动也会更自信。

5.4 命名与注释：代码到底要不要写注释

t3code 的立场是：优先通过命名和代码结构表达意图，注释只负责解释“为什么”，不负责解释“是什么”。换句话说，代码本身应该足够自解释，命名准确、函数短小、模块清晰，读者光看代码就能理解它在做什么；注释则用来补充代码表达不了的信息，比如某个计算背后的业务约束、某个处理分支的历史原因、某个刁钻 bug 的规避逻辑。

实际操作中，一种值得提倡的做法是写提交消息和变更记录。代码是不断演进的，每个提交的说明文字记录了“这次改动做了什么、为什么这样做、影响了什么”，这些信息对后来人非常重要。很多团队不重视提交消息，结果 Git 历史变成了一堆update、fix、优化，半年后想追溯某个需求变更的原因，只能对着代码发呆。

我定的提交消息格式是：类型(影响模块): 简要描述，比如feat(user): 新增用户注销接口、fix(order): 修复订单金额精度问题、refactor(auth): 抽离 token 校验中间件。类型用feat、fix、refactor、docs、style、test、chore这一套约定，一眼就能看出本次改动的性质。

6. 工具链选型解析

6.1 核心工具清单

t3code 的落地离不开一套趁手的工具链。我整理了一份自己常用的清单，按功能分类列在下面，供你参考：

这里多说一句 TypeScript 的strict模式。很多人刚上手 TS 时会关掉strict来降低报错率，但 t3code 要求从一开始就开启严格模式。strict: true会启用noImplicitAny、strictNullChecks、strictFunctionTypes等一系列检查，刚开始确实会增加不少工作量，但等到项目变大之后，这些检查会避免无数个运行时的类型错误。长痛不如短痛，这个开关值得开。

6.2 为什么选定这一套工具

选工具的一个核心原则是：不过度设计，够用就好。有些团队一上来就上一套重量级质量平台，各种面板、报告、看板，看起来很专业，但实际使用率极低，最后沦为摆设。t3code 的工具链尽量选轻量、贴近代码库的工具，让每个工具直接作用于开发流程，而不是独立于流程之外。

ESLint 和 Prettier 是事实标准，社区插件丰富，和编辑器、CI 集成简单；madge 是轻量命令行工具，运行一次就知道项目依赖有没有问题；Vitest 比 Jest 更快，原生支持 ESM 和 TypeScript，体验好不少；Playwright 在 E2E 测试里稳定性很好，能跑 Chromium、Firefox、WebKit 三个内核，覆盖主流浏览器场景。

工具选定之后要写进项目文档，并且在 README 里说明为什么选这些工具、各自的职责边界是什么。很多项目工具一堆，但没有说明文档，新人有疑问只能瞎猜，反而降低效率。

6.3 冷门但好用的配置细节

工具链里有些小配置，看起来不起眼，但实际用起来非常香。比如 ESLint 的import/no-restricted-paths规则，可以限制模块之间的跨层引用，从工具层面强制约束模块边界。比如禁止src/features/user下的文件引用src/features/order下的文件，除非通过共享层。这个规则配置好之后，架构设计才能真正落地，而不是依赖大家的自觉。

另一个常用的配置是路径别名。TypeScript 的paths配置可以给不同层级的目录设置别名，比如@features/user、@components、@lib，这样 import 语句里就不会出现一长串../../../，代码可读性和可维护性都大幅提升。配好了路径别名，记得把别名同步到 ESLint 和 Vitest 的配置里，让整个工具链认识同一套路径。

还有一个容易忽略的点：Github Actions 或 GitLab CI 里把 lint、类型检查、单测、集成测试全部串起来，每个 pull request 自动跑一遍。质量门禁不放水，规范才能长久维持。

7. 一些个人经验和体会

t3code 这套思路我在不同规模的项目里实践过，从几个人的创业项目到三四十人的中大型团队，效果都不错。但我也要说实话，它不是什么灵丹妙药，解决不了管理混乱和需求频繁变化的问题，它能解决的是让代码库在混乱的外部环境下保持内在秩序，让每一次改动都有迹可循。

实际操作中，我最有感触的一点是：规范不是越多越好，而是越少越好。每一条规范都应该有明确的理由，能够解决一个具体的问题。没有理由的规范，比如盲目追求函数必须不超过十行，只会让人反感，也不会真正提升质量。我在团队里推 t3code 的原则是：先列问题清单，再针对问题制定规范，不为了规范而规范。

最后再分享一个小技巧：代码库的治理是一个持续演进的过程，不要指望一次重构解决所有问题。每接到一个新需求，顺手优化一下相关代码；每次 Code Review，顺手调整一下命名和结构；每次踩坑，顺手补充一条 lint 规则。点点滴滴积累下来，半年后回头看，你会发现代码库已经脱胎换骨。这就是 t3code 想达到的效果——不是靠一次大手术，而是靠每一天的小改善，让代码进入一个正向循环。