1. 从"t3code"这个关键词说起：它到底是什么

第一次看到"t3code"这个词，很多人会一头雾水。它不像"Vue"、"Docker"那样有明确的官方定义，也不像"Python"那样自带生态标签。我在几个技术社区翻了一圈，发现这个词的用法相当分散：有人拿它当某个内部工具链的代号，有人用它指代一套轻量级的编码规范，还有人把它当成一个临时项目的命名前缀。这种"一词多义"的状态，恰恰说明它还没被大范围标准化，属于那种在小圈子里口口相传、靠实践沉淀下来的东西。

我个人的判断是，t3code 本质上是一套围绕"轻量、快速、可复用"三个原则组织起来的编码实践集合。它不是一个具体的框架，也不是某个语言的专属规范，更像是一种"做事的方式"——当你面对一个中小型项目，不想引入过重的工程化体系，又希望代码保持可读、可维护、可交接时，t3code 这套思路就能派上用场。它解决的核心问题是：在资源有限、时间紧张的情况下，如何用最小的认知成本写出不容易烂尾的代码。

这篇文章适合几类人看：一是刚入行不久、还没形成自己编码习惯的新人，你需要一套能直接抄的模板；二是带小团队的技术负责人，你想统一大家的代码风格但又不想搞得太复杂；三是独立开发者或接私活的朋友，你需要在"快"和"稳"之间找平衡。不管你用的是什么语言，t3code 的思路都能迁移过去，因为它的底层逻辑是通用的。

接下来我会从设计思路、核心细节、实操过程、问题排查四个维度，把 t3code 这套东西拆开讲透。每一部分都会给出具体的做法和背后的理由，你能直接拿去用，也能根据自己的场景做调整。

2. t3code 的整体设计思路与方案选型

2.1 为什么是"轻量优先"而不是"大而全"

很多人在开始一个项目时，第一反应是"把能装的都装上"——linter、formatter、测试框架、CI/CD、监控告警，一套组合拳打下来，光配置文件就十几个。这种做法在大型团队里没问题，但对于中小项目来说，过度工程化本身就是最大的技术债。我见过太多项目，前期花了两周搭架子，结果业务代码写了三天就没人维护了。

t3code 的设计哲学正好相反：先跑起来，再按需加东西。它的核心假设是——大部分项目活不到需要复杂工程化的那一天，所以前期应该把精力花在业务逻辑上，而不是基础设施上。具体来说，t3code 建议只保留三样东西：一个统一的代码格式化工具、一套命名约定、一个最小化的目录结构。其他的，等真正遇到问题了再加。

这个选择背后的逻辑是"延迟决策"。你不确定未来会不会需要单元测试，那就先不写；你不确定团队会不会扩大到十个人，那就先不搞代码评审流程。等到问题真实出现时，你已经有足够的上下文来做判断，而不是凭想象提前挖坑。

2.2 三个核心原则的取舍逻辑

t3code 的三个原则——轻量、快速、可复用——不是随便排的，它们之间有明确的优先级关系。

轻量是第一优先级。当"轻量"和"快速"冲突时，选轻量。比如，引入一个重型 ORM 能让写查询快很多，但它增加了依赖体积和学习成本，那就应该用原生 SQL 或者轻量查询构造器。快速是第二优先级，当"快速"和"可复用"冲突时，选快速。比如，你写了一个通用工具函数，但它只在一个地方用到，那就不要抽出来，直接内联，等第二个地方用到时再抽。可复用是第三优先级，它是前两者的自然结果，而不是刻意追求的目标。

这个优先级排序解决了一个常见困惑：什么时候该抽象，什么时候不该抽象。很多新人容易犯的错是过早抽象，看到一个模式就想着封装成通用组件，结果抽象出来的东西比直接写还复杂。t3code 的答案是：重复三次以上再抽象，这个规则简单粗暴但极其有效。

2.3 与主流方案的对比

为了让你更清楚 t3code 的定位，我把它和几种常见方案做个对比。

从表里能看出来，t3code 走的是中间路线。它不像重型工程化那样一上来就压死你，也不像裸写那样完全没章法。它的核心价值在于给了一个"够用就好"的默认值，你可以在上面加东西，但不会因为没加东西而心虚。

注意：t3code 这套思路的前提是"你对自己的项目有基本判断力"。如果你完全不知道项目会发展成什么样，那还是老老实实按标准工程化流程走，别拿 t3code 当偷懒的借口。

3. 核心细节解析与实操要点

3.1 命名约定：让代码自己说话

t3code 对命名的要求只有三条，但每条都直击要害。

第一条：变量名必须能读出用途。data、info、temp这类词是禁止的，除非它的作用域不超过三行。比如你从接口拿到用户列表，变量名应该是userList而不是list；你计算出来的总价，应该是totalPrice而不是result。这条规则看起来简单，但能过滤掉 80% 的烂代码。

第二条：函数名必须是动词开头。getUserById、calculateTotal、validateEmail，这些名字读起来就知道在干什么。反过来，userData、totalPrice这种名词做函数名的，一律改掉。这条规则的好处是，当你看到调用处时，不用跳转到定义就能猜到行为。

第三条：常量必须全大写加下划线。MAX_RETRY_COUNT、DEFAULT_TIMEOUT_MS，这种写法在几乎所有语言里都是通用的，不需要额外解释。它的作用是在视觉上把常量和变量区分开，让你扫一眼就知道哪些值是可以改的，哪些是固定的。

这三条规则加起来不到五十个字，但执行下去，代码的可读性会有质的提升。我自己的经验是，命名规范是投入产出比最高的编码约定，没有之一。

3.2 目录结构：三个文件夹走天下

t3code 建议的目录结构极其简单，只有三个顶层文件夹：

project/ ├── src/ # 所有源代码 ├── tests/ # 所有测试代码 └── scripts/ # 构建、部署、工具脚本

就这三个，没有utils/、没有common/、没有helpers/。为什么？因为这些"万能文件夹"最终都会变成垃圾堆。你放一个函数进去，别人也放一个，半年后没人知道里面有什么，也没人敢删。

那工具函数放哪？t3code 的答案是：放在使用它的地方。如果src/user/service.js需要一个格式化日期的函数，就写在service.js里。如果第二个文件也需要，再考虑抽到src/shared/下。注意，是shared/不是utils/，因为shared/暗示了"被多处共享"，而utils/暗示了"什么都可以放"。

这个结构的好处是降低认知负担。新人进来，打开项目，一眼就能看到所有代码在哪。不需要问"这个模块属于哪个层"，也不需要理解复杂的架构分层。对于中小项目来说，扁平比分层更重要。

3.3 错误处理：统一出口，不吞异常

t3code 对错误处理的要求是：每个可能出错的地方都要有明确的处理，不允许静默失败。具体做法是，在src/下建一个errors.js（或对应语言的错误定义文件），把所有自定义错误类型集中定义。

// src/errors.js class AppError extends Error { constructor(code, message) { super(message); this.code = code; this.name = 'AppError'; } } class ValidationError extends AppError { constructor(message) { super('VALIDATION_FAILED', message); } } class NotFoundError extends AppError { constructor(message) { super('NOT_FOUND', message); } } module.exports = { AppError, ValidationError, NotFoundError };

然后在业务代码里，只抛出这些预定义的错误类型，不抛裸的Error。这样做的好处是，上层捕获时可以根据code做统一处理，而不是靠解析错误信息字符串。我见过太多项目用error.message.includes('not found')来判断错误类型，这种写法极其脆弱，改个文案就崩了。

提示：错误处理的核心不是"捕获所有异常"，而是"让异常在正确的地方被处理"。底层只管抛，中间层只管传，最外层统一兜底。不要在每一层都写 try-catch，那样只会让调用栈变得混乱。

3.4 配置管理：环境变量优先

t3code 建议所有配置都通过环境变量注入，代码里不出现硬编码的配置值。具体做法是，在项目根目录放一个.env.example文件，列出所有需要的环境变量，但不包含真实值。真实值放在.env里，并且.env必须加入.gitignore。

# .env.example DATABASE_URL=postgres://localhost:5432/mydb API_KEY=your_api_key_here LOG_LEVEL=info PORT=3000

然后在代码里统一读取：

// src/config.js const config = { databaseUrl: process.env.DATABASE_URL, apiKey: process.env.API_KEY, logLevel: process.env.LOG_LEVEL || 'info', port: parseInt(process.env.PORT, 10) || 3000, }; // 启动时校验必填项 const required = ['databaseUrl', 'apiKey']; for (const key of required) { if (!config[key]) { throw new Error(`Missing required config: ${key}`); } } module.exports = config;

这个做法的关键点是启动时校验。不要等到用到某个配置时才发现没设置，那样错误会出现在很深的地方，排查起来很痛苦。在应用启动的第一时间就把所有必填配置检查一遍，有问题立刻报错退出。

4. 实操过程与核心环节实现

4.1 从零搭建一个 t3code 风格的项目

假设你要用 Node.js 写一个简单的 API 服务，我带你走一遍完整流程。

第一步：初始化项目。不要用脚手架，手动建目录和文件。脚手架会塞一堆你不需要的东西，清理起来比新建还麻烦。

mkdir my-project && cd my-project npm init -y mkdir src tests scripts touch src/index.js src/config.js src/errors.js touch .env.example .gitignore

第二步：配置格式化工具。t3code 只推荐一个工具——Prettier。不装 ESLint，因为 ESLint 的规则配置是无底洞，而 Prettier 只管格式，不管逻辑，够用了。

npm install --save-dev prettier

创建.prettierrc：

{ "semi": true, "singleQuote": true, "tabWidth": 2, "printWidth": 100, "trailingComma": "es5" }

这五个配置项是我用了三年后沉淀下来的，基本覆盖所有场景。printWidth: 100比默认的 80 宽一点，因为现代显示器普遍较宽，80 会导致过多换行。

第三步：写入口文件。src/index.js只做三件事：加载配置、启动服务、注册错误处理。

// src/index.js const config = require('./config'); const { AppError } = require('./errors'); async function main() { // 启动逻辑 console.log(`Server starting on port ${config.port}`); } main().catch((err) => { if (err instanceof AppError) { console.error(`[${err.code}] ${err.message}`); } else { console.error('Unexpected error:', err); } process.exit(1); });

这个入口文件的结构是 t3code 的典型写法：一个 async main 函数 + 一个 catch 兜底。所有业务逻辑都在 main 里面调用，错误统一在最外层处理。

第四步：写第一个业务模块。假设你要做一个用户查询接口，在src/user.js里写：

// src/user.js const { NotFoundError, ValidationError } = require('./errors'); const users = [ { id: 1, name: 'Alice', email: 'alice@example.com' }, { id: 2, name: 'Bob', email: 'bob@example.com' }, ]; function getUserById(id) { if (!id || typeof id !== 'number') { throw new ValidationError('id must be a positive number'); } const user = users.find((u) => u.id === id); if (!user) { throw new NotFoundError(`User ${id} not found`); } return user; } module.exports = { getUserById };

注意这里的错误处理：参数校验抛 ValidationError，找不到抛 NotFoundError，两种错误类型分开，上层可以根据类型返回不同的 HTTP 状态码。

4.2 参数选择与计算过程

t3code 在参数选择上有一个原则：能用常量就不用变量，能用默认值就不传参。举个例子，假设你要设置一个 HTTP 请求的超时时间。

不推荐的做法是每个请求都传超时参数：

// 不推荐 fetch(url1, { timeout: 5000 }); fetch(url2, { timeout: 5000 }); fetch(url3, { timeout: 5000 });

推荐的做法是定义一个常量，统一使用：

// 推荐 const DEFAULT_TIMEOUT_MS = 5000; function request(url, options = {}) { const timeout = options.timeout || DEFAULT_TIMEOUT_MS; // ... }

为什么？因为超时时间是一个全局策略，不是每次调用都需要关心的细节。把它抽成常量后，改的时候只需要改一个地方。如果某个请求确实需要不同的超时，再单独传参覆盖。

再比如分页参数。t3code 建议默认每页 20 条，最大 100 条。这个数字不是拍脑袋定的，而是基于经验：20 条是大多数屏幕一屏能展示的数量，100 条是单次查询不拖垮数据库的上限。超过 100 条，就应该考虑用游标分页或者异步导出，而不是继续加大 limit。

const DEFAULT_PAGE_SIZE = 20; const MAX_PAGE_SIZE = 100; function normalizePageSize(size) { const parsed = parseInt(size, 10); if (isNaN(parsed) || parsed < 1) return DEFAULT_PAGE_SIZE; return Math.min(parsed, MAX_PAGE_SIZE); }

这个normalizePageSize函数就是 t3code 风格的典型代表：输入不可信，输出有边界，逻辑不超过十行。

4.3 实操现场记录：一次真实的重构

我拿自己半年前写的一个小工具做例子。那个工具是批量处理 CSV 文件的，最初写得很随意，所有逻辑塞在一个 500 行的文件里。后来要加功能，改起来很痛苦，我就用 t3code 的思路重构了一遍。

重构前的结构：

process.js (500 行，包含读取、解析、转换、写入、日志)

重构后的结构：

src/ ├── index.js (入口，30 行) ├── config.js (配置，20 行) ├── errors.js (错误定义，15 行) ├── reader.js (读取 CSV，60 行) ├── parser.js (解析行，80 行) ├── transformer.js (数据转换，100 行) └── writer.js (写入结果，70 行)

重构的关键动作是按数据流向拆分：读取 → 解析 → 转换 → 写入，每个环节一个文件，每个文件只暴露一个主函数。文件之间的依赖是单向的，index.js调用reader，reader调用parser，以此类推，不允许反向依赖。

重构后最明显的变化是改 bug 变快了。以前改一个解析逻辑，要在 500 行里找半天；现在直接打开parser.js，一目了然。另一个变化是测试变容易了，每个模块可以单独测，不需要构造完整的 CSV 文件。

提示：重构的时机很重要。不要一开始就追求完美结构，那样会拖慢开发速度。等到你发现"改一个地方要动三个文件"或者"找代码要翻半天"时，再重构。t3code 的核心是按需演进，不是一步到位。

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

5.1 常见问题速查表

5.2 独家避坑技巧

第一个坑：不要过早引入 TypeScript。我知道现在 TS 很火，但对于中小项目来说，TS 的类型定义成本可能比收益还高。t3code 的建议是：先用 JavaScript 写，等类型问题真的困扰你了再迁移。我自己的经验是，一个项目如果活不过三个月，用 TS 就是纯浪费；如果活过三个月，迁移到 TS 也就一两天的事。

第二个坑：日志不要用 console.log。console.log 的问题不是性能，而是没有级别、没有时间戳、没有上下文。t3code 建议用一个极简的日志封装：

// src/logger.js const LEVELS = { debug: 0, info: 1, warn: 2, error: 3 }; const currentLevel = LEVELS[process.env.LOG_LEVEL] || LEVELS.info; function log(level, message, meta = {}) { if (LEVELS[level] < currentLevel) return; const timestamp = new Date().toISOString(); console.log(JSON.stringify({ timestamp, level, message, ...meta })); } module.exports = { debug: (msg, meta) => log('debug', msg, meta), info: (msg, meta) => log('info', msg, meta), warn: (msg, meta) => log('warn', msg, meta), error: (msg, meta) => log('error', msg, meta), };

这个封装不到 20 行，但解决了三个问题：级别过滤、结构化输出、统一格式。JSON 格式的日志可以直接被日志系统采集，不需要额外解析。

第三个坑：不要用index.js做桶文件。很多项目喜欢在src/utils/index.js里 re-export 所有工具函数，然后其他地方import { foo } from './utils'。这种做法在 t3code 里是禁止的，因为它隐藏了真实的依赖关系。你看到from './utils'根本不知道具体用了哪个函数，改的时候也不敢删。正确做法是直接import { foo } from './utils/foo'，路径长一点，但依赖清晰。

第四个坑：测试不要追求覆盖率。t3code 对测试的态度是：只测核心逻辑和边界条件。不要为了覆盖率数字去写无意义的测试。一个 80% 覆盖率的项目，如果那 80% 都是 getter/setter，还不如一个 30% 覆盖率但覆盖了所有关键分支的项目。我自己的做法是，每个模块只写三个测试：正常输入、边界输入、异常输入。三个测试能过，基本就稳了。

5.3 排查思路的通用框架

遇到问题时，t3code 建议按这个顺序排查：

1. 看错误信息。不要跳过错误信息直接猜，90% 的问题错误信息里已经写清楚了。
2. 缩小范围。把问题隔离到最小的可复现单元，不要在一个大系统里瞎找。
3. 对比正常情况。找一个能正常工作的类似场景，对比差异点。
4. 二分法定位。如果范围太大，就注释掉一半代码，看问题是否还在，逐步缩小。
5. 查文档和源码。不要只搜博客，直接看官方文档和源码，信息最准确。

这个框架看起来简单，但能解决 95% 的日常问题。剩下的 5%，才需要靠经验和直觉。

6. 我对 t3code 这套思路的个人体会

用了大半年 t3code 这套东西，最大的感受是它帮我省下了大量做决策的时间。以前每写一个新项目，都要纠结"要不要加 lint"、"目录怎么分"、"错误怎么处理"，现在直接套模板，五分钟搞定。省下来的时间可以花在真正重要的业务逻辑上。

另一个体会是，t3code 的规则不是死的，而是有明确边界的。比如"重复三次再抽象"这条，不是说第三次一定要抽象，而是说第三次是一个信号，提醒你该考虑抽象了。具体抽不抽，还要看场景。如果三次重复的代码未来可能朝不同方向演化，那就不抽；如果三次重复的代码逻辑完全一致，那就抽。这种"有原则但不教条"的风格，是我最喜欢的地方。

最后分享一个小技巧：把 t3code 的规则写进项目的 README 里。不用写太长，三五条就行。这样新人进来第一眼就能看到，不用你口头交代。而且写下来之后，你自己也会更自觉地遵守。我试过几个项目，写了规则的项目，代码质量明显比没写的高一截。