1. 从“t3code”这个代号说起：它到底指什么
第一次看到“t3code”这个词，很多人会一头雾水。它不像“Python入门”或者“React教程”那样一眼就能看出领域归属，更像是一个内部代号、项目昵称，或者某个小圈子里的黑话。我在几个技术社区翻了一圈，发现围绕这个词的讨论其实指向一个很具体的场景：用极简的代码结构去驱动一套可复用的模板化输出。换句话说，t3code 不是某个官方框架的名字，而更像是一种“约定俗成”的写法——用三行核心代码（或者三个核心模块）撑起一个完整的、可配置的生成逻辑。
这个理解听起来有点抽象，我换个说法。你可能见过那种“一行代码生成海报”“三行代码搞定数据看板”的分享，t3code 的气质跟它们很像，但它更强调“结构上的克制”。它不追求功能大而全，而是把注意力放在最小可用单元上：一个入口、一个配置、一个输出。三个部分各司其职，彼此之间通过清晰的约定来通信，而不是靠复杂的依赖注入或者层层继承。
为什么这种思路会被人反复提起？因为在实际项目里，我们太容易把简单的事情做复杂了。一个本来只需要读取配置、渲染模板、写出文件的小工具，写着写着就变成了十几个文件、五层目录、一堆抽象接口。t3code 的价值就在于它提醒你：能不能用三个核心块把这件事说清楚？如果能，就不要引入第四个。
适合谁来了解这个内容？如果你正在做代码生成、模板渲染、配置驱动类的工具，或者你单纯对“如何把项目结构压到最简”感兴趣，那 t3code 背后的思路值得花时间琢磨。它不要求你掌握什么冷门技术，但要求你对“什么该留、什么该砍”有判断力。下面我会从它的核心构成、运行机制、实操步骤、常见坑点几个角度，把这件事拆开讲透。
2. t3code 的三个核心块：入口、配置、输出
2.1 入口块：只做一件事，就是“读”
任何一套 t3code 风格的实现，入口部分都极其克制。它不负责业务逻辑，不负责异常兜底，甚至不负责参数校验——这些统统交给后面的块。入口只做一件事：把外部输入读进来，然后原封不动地传给配置块。
我见过不少人在这里犯同一个错误：在入口里就开始写 if-else。比如判断用户传了哪些参数、没传哪些参数、传的参数格式对不对。这些判断本身没错，但放在入口里就会让入口膨胀。一旦入口超过二十行，它就不再是“入口”了，而是一个隐形的业务层。t3code 的做法是：入口只负责读取，读取的方式可以是从命令行、从文件、从环境变量，但读完就扔给下一块，自己不加工。
具体到代码层面，一个典型的入口块可能长这样：
import sys import json def load_input(): raw = sys.stdin.read() return json.loads(raw) if raw.strip() else {}你看，它没有 try-except，没有类型检查，没有默认值填充。这些事后面会做。入口的职责边界清晰到近乎“冷漠”，但正是这种冷漠让整个结构变得可预测。你知道只要输入进来了，后面一定有人处理；你也知道入口不会偷偷改你的数据。
注意：入口块不处理异常，不代表整个系统不处理异常。异常处理应该放在配置块或者输出块里，因为只有那里才知道“什么样的输入算合法”。
2.2 配置块：把“变化”关进笼子
配置块是 t3code 里最容易被低估的部分。很多人觉得配置就是读个 JSON、YAML，没什么技术含量。但在 t3code 的语境下，配置块承担了一个更重要的角色：它是整个系统里唯一允许“变化”的地方。
什么意思？入口块是固定的，输出块是固定的，只有配置块可以根据不同场景调整。你想换一个模板？改配置。你想换一个输出路径？改配置。你想调整生成规则？还是改配置。配置块就像一个“变化收纳箱”，把所有可能变的东西都吸进去，让入口和输出保持稳定。
一个合格的配置块通常包含三样东西：默认值、校验逻辑、合并策略。默认值保证即使外部什么都不传，系统也能跑起来；校验逻辑保证传进来的东西不会把后面搞崩；合并策略决定当默认值和外部输入冲突时听谁的。我个人的习惯是“外部优先，但默认值兜底”，这样既灵活又安全。
DEFAULTS = { "template": "basic", "output": "./dist", "overwrite": False } def resolve_config(user_input): config = {**DEFAULTS, **user_input} if config["template"] not in AVAILABLE_TEMPLATES: raise ValueError(f"未知模板: {config['template']}") return config这段代码里，{**DEFAULTS, **user_input}就是合并策略，一行搞定。校验逻辑只检查最关键的一个字段，不做过度的格式审查。因为过度校验会把配置块变成第二个入口，那就违背了 t3code 的初衷。
2.3 输出块：只认配置，不认人情
输出块是最终干活的地方。它拿到配置块处理好的配置，然后按照配置去渲染模板、生成文件、打印结果。它的特点是：不关心输入从哪来，也不关心配置为什么这么定，只关心“配置让我干什么”。
这种“只认配置”的态度很重要。我见过一些实现，输出块里会偷偷读环境变量，或者根据当前时间做判断，或者根据用户 ID 走不同分支。这些行为看似灵活，实际上破坏了 t3code 的结构。因为一旦输出块开始“自己拿主意”，配置块就不再是唯一的变化来源，整个系统的行为就变得难以预测。
输出块的理想状态是：给它同样的配置，它永远产出同样的结果。这叫幂等性，也是 t3code 能被信任的基础。如果你需要“根据时间不同输出不同内容”，那应该把时间作为配置的一部分传进来，而不是让输出块自己去读系统时间。
def render(config): template = load_template(config["template"]) content = template.render(config) path = os.path.join(config["output"], "result.txt") if os.path.exists(path) and not config["overwrite"]: raise FileExistsError(path) with open(path, "w") as f: f.write(content) return path这段代码里，输出块没有做任何“额外判断”。它不检查模板文件是否存在（那是配置块该保证的），不检查输出目录是否可写（那是环境问题，不是逻辑问题）。它只做一件事：按配置输出。
3. 为什么是“三”，而不是“二”或者“四”
3.1 两块结构的问题：入口和输出容易纠缠
如果你把 t3code 压缩成两块——入口和输出——会发生什么？最直接的问题是：入口读进来的原始数据，输出块不一定能直接用。比如入口读进来的是一个字符串，输出块需要的是一个字典；或者入口读进来的是命令行参数，输出块需要的是带默认值的配置对象。这时候你只有两个选择：要么在入口里做转换，要么在输出里做转换。无论选哪个，都会让那一块变得臃肿。
我试过用两块结构写一个简单的代码生成器，结果入口函数里塞了参数解析、默认值填充、类型转换、路径拼接，最后入口比输出还长。这完全违背了“入口只做读”的原则。后来我把转换逻辑单独抽出来，变成配置块，入口和输出立刻都瘦下来了。三块结构不是拍脑袋定的，而是“读、算、写”这三个动作天然需要分开。
3.2 四块结构的问题：多出来的那块往往在“打架”
那为什么不是四块？比如在配置和输出之间再加一个“校验块”或者“转换块”？我的经验是：多出来的那一块，最后往往会和配置块抢活干。你加一个校验块，它要读配置，配置块也要读配置；你加一个转换块，它要改配置，配置块本身就有合并策略。两块之间的边界一旦模糊，维护成本就会指数上升。
更现实的问题是：四块结构会让新人不知道往哪放代码。他写了一个新功能，应该放校验块还是配置块？如果两个地方都能放，那最后一定是两边都放一点，然后逻辑就散了。三块结构的好处是：每个块的职责足够少，少到不需要犹豫。读的放入口，变的放配置，写的放输出。没有第四种可能。
3.3 三块之间的通信约定：只传配置对象
t3code 能成立的关键，是三块之间只通过一个东西通信：配置对象。入口把原始输入交给配置块，配置块吐出一个配置对象，输出块只认这个配置对象。除此之外，三块之间没有任何其他耦合。
这个约定看起来简单，但威力很大。它意味着你可以单独测试配置块：给它不同的输入，看它吐出什么配置。你也可以单独测试输出块：给它不同的配置，看它产出什么结果。入口块甚至不需要测试，因为它只做读取，逻辑少到几乎不会出错。
我见过有人在三块之间传额外的“上下文对象”“运行时状态”“全局单例”，结果就是三块又缠在一起了。t3code 的纪律性就体现在这里：除了配置对象，什么都不传。如果你觉得需要传别的东西，那说明你的配置对象设计得不够好，应该去改配置对象，而不是加通道。
4. 动手搭一个最小 t3code 骨架
4.1 目录结构：三个文件，一个目录
我不喜欢一上来就讲抽象概念，直接看目录结构最直观。一个最小可用的 t3code 骨架长这样：
t3code-demo/ ├── entry.py ├── config.py ├── output.py └── templates/ └── basic.txt四个文件，其中三个是代码，一个是模板。没有utils/，没有helpers/，没有core/。你可能会觉得“这也太简陋了”，但正是这种简陋让它容易被理解、容易被修改。我见过太多项目，光目录结构就让人不想看第二眼，而 t3code 的目标恰恰相反：让你在三十秒内看懂整个项目在干什么。
entry.py负责读，config.py负责算，output.py负责写。templates/目录放模板文件，模板文件本身不包含逻辑，只包含占位符。这种“逻辑和内容分离”的做法，让改模板的人不需要懂代码，改代码的人不需要动模板。
4.2 入口的写法：十行以内解决战斗
entry.py的完整内容可以短到令人发指：
import sys import json from config import resolve_config from output import render def main(): raw = sys.stdin.read() user_input = json.loads(raw) if raw.strip() else {} config = resolve_config(user_input) result = render(config) print(result) if __name__ == "__main__": main()十行出头。它做了四件事：读标准输入、解析 JSON、调配置块、调输出块。没有异常处理，没有日志，没有参数解析库。你可能会问：如果 JSON 解析失败怎么办？答案是：让它失败。失败信息会直接抛到终端，用户看到json.decoder.JSONDecodeError就知道自己传的格式不对。这比你自己写一堆错误提示更直接，也更省事。
提示：如果你确实需要友好的错误提示，可以在
main外面包一层 try-except，但不要把这个逻辑塞进entry.py的核心流程里。保持入口的干净比“友好”更重要。
4.3 配置的默认值与覆盖逻辑
config.py是三个文件里唯一需要动脑子的地方。它的核心是一个字典和一个合并函数：
DEFAULTS = { "template": "basic", "output": "./dist", "overwrite": False, "vars": {} } def resolve_config(user_input): config = {**DEFAULTS, **user_input} if not isinstance(config["vars"], dict): raise TypeError("vars 必须是字典") return config这里有一个细节值得展开：vars字段用来放模板里需要替换的变量。比如模板里写了{{name}}，那vars里就要有{"name": "张三"}。为什么把vars单独拎出来？因为它是唯一一个“嵌套结构”，其他字段都是标量。把嵌套结构集中在一个字段里，可以让合并逻辑保持简单——浅合并就够了，不需要递归合并。
如果你需要更复杂的配置，比如多环境配置、配置继承，我的建议是：不要在三块结构里做。你可以写一个独立的配置预处理脚本，在调用entry.py之前把配置处理好。t3code 的边界很清楚：它只处理“已经确定好的配置”，不处理“配置是怎么来的”。
4.4 输出块的模板渲染与文件写入
output.py的核心是模板替换和文件写入：
import os def load_template(name): path = os.path.join("templates", f"{name}.txt") with open(path, "r", encoding="utf-8") as f: return f.read() def render(config): template = load_template(config["template"]) content = template for key, value in config["vars"].items(): content = content.replace("{{" + key + "}}", str(value)) out_dir = config["output"] os.makedirs(out_dir, exist_ok=True) out_path = os.path.join(out_dir, "result.txt") if os.path.exists(out_path) and not config["overwrite"]: raise FileExistsError(f"文件已存在: {out_path}") with open(out_path, "w", encoding="utf-8") as f: f.write(content) return out_path这段代码里，模板替换用的是最简单的字符串替换，没有引入 Jinja2 或者 Mustache。为什么？因为 t3code 的定位是“最小可用”，不是“功能完备”。如果你需要循环、条件判断、过滤器，那说明你的模板已经复杂到需要专门的模板引擎了，那时候你应该换工具，而不是把 t3code 撑大。
文件写入部分有一个overwrite检查，这是配置块传下来的。输出块不判断“该不该覆盖”，它只执行配置说的“覆盖”或“不覆盖”。这就是“只认配置”的体现。
5. 跑起来之后才会遇到的五个坑
5.1 坑一：入口读不到数据，因为标准输入被占用了
第一次跑entry.py的时候，我习惯性地直接python entry.py，然后终端就卡住了。因为sys.stdin.read()在等输入。正确的做法是echo '{"template":"basic"}' | python entry.py，或者用文件重定向python entry.py < input.json。这个坑很小，但如果你不知道，会以为程序挂了。
更隐蔽的情况是：在某些 CI 环境里，标准输入默认是关闭的，sys.stdin.read()会直接返回空字符串。这时候你的程序会用一个空字典去跑配置，然后输出默认模板。如果你没意识到这一点，可能会奇怪“为什么 CI 里生成的内容和本地不一样”。解决办法是在入口里加一个判断：如果标准输入是空的，就从环境变量或者默认文件里读。但注意，这个判断要放在entry.py里，不要放到配置块里，因为“从哪读”是入口的职责。
5.2 坑二：配置合并时嵌套字典被整个替换
{**DEFAULTS, **user_input}是浅合并。如果DEFAULTS里的vars是{"a": 1}，而用户传了{"vars": {"b": 2}}，合并结果是{"vars": {"b": 2}}，a丢了。这个行为在大多数情况下没问题，但如果你期望的是“合并 vars 里的键”，就会踩坑。
我的处理方式是：在文档里写清楚这是浅合并，并且建议用户传完整的 vars。如果你确实需要深合并，可以写一个递归合并函数，但我不建议把它放进config.py的核心逻辑里。你可以单独写一个merge_deep函数，在调用resolve_config之前先处理用户输入。这样config.py保持简单，深合并的需求也不会被忽略。
5.3 坑三：模板里的占位符和变量名对不上
模板里写了{{name}}，但配置里的vars是{"username": "张三"}，替换不会报错，只会留下{{name}}原样输出。这种“静默失败”很坑，因为你可能过了很久才发现输出文件里有一堆没替换的占位符。
我的做法是在render函数里加一个检查：替换完成后，用正则扫一遍{{...}}，如果还有残留，就抛异常。这样至少能让你在第一时间知道“有变量没对上”。代码大概长这样：
import re def render(config): # ... 前面的替换逻辑 ... remaining = re.findall(r"\{\{\w+\}\}", content) if remaining: raise ValueError(f"未替换的占位符: {remaining}") # ... 写入逻辑 ...这个检查会增加一点点开销，但比起“生成了一堆坏文件却不知道”，这点开销完全值得。
5.4 坑四：输出目录不存在导致写入失败
os.makedirs(out_dir, exist_ok=True)这行代码看起来没问题，但如果out_dir是一个已经存在的文件而不是目录，makedirs会抛FileExistsError。更常见的情况是：out_dir的父目录没有写权限，makedirs会抛PermissionError。这些错误信息本身是清楚的，但如果你在 CI 里跑，可能会被一堆日志淹没。
我的经验是：在配置块里做一次路径合法性检查。检查output字段是不是字符串、是不是绝对路径、父目录是否存在。这些检查不涉及文件系统操作，只是字符串和os.path的判断，放在配置块里很合适。输出块只负责“写”，不负责“判断能不能写”。
5.5 坑五：并发调用时文件被覆盖
如果你同时跑两个entry.py，它们可能同时往同一个result.txt里写。overwrite检查在并发下不可靠，因为“检查”和“写入”之间有时间窗口。两个进程可能都通过了检查，然后都写入，后写的覆盖先写的。
t3code 本身不解决并发问题，因为它的定位是“单次调用工具”。如果你需要并发，应该在外面加锁，或者让每次调用的输出路径不同（比如用时间戳或者随机数作为文件名）。我的建议是：不要在 t3code 里加锁，那会让结构变复杂。并发控制是调用方的事，不是工具的事。
6. 把 t3code 用在实际项目里的三个场景
6.1 场景一：批量生成配置文件
我接过一个需求：给五十台服务器生成配置文件，每台服务器的 IP、端口、角色不同。如果用 Ansible 或者 Shell 脚本，写起来很快，但改起来很痛苦。用 t3code 的思路，我把模板写成server.conf.tpl，把五十台服务器的信息写成一个 JSON 数组，然后写一个循环调用entry.py。
这个场景里，t3code 的优势是模板和逻辑分离。运维同事想改配置格式，直接改模板文件，不需要懂 Python。我想改生成逻辑，直接改output.py，不需要动模板。两边可以并行工作，互不干扰。
6.2 场景二：代码脚手架的最小实现
很多团队用 Yeoman 或者 Plop 来做代码脚手架，但这些工具本身有一定的学习成本。如果你只需要“根据几个参数生成几个文件”，t3code 完全够用。你可以把模板目录设计成和输出目录同构，然后在output.py里遍历模板目录，对每个文件做替换，再写到对应的输出路径。
这个场景的关键是：模板目录的结构就是输出目录的结构。比如templates/src/index.js会生成到dist/src/index.js。这样你不需要在配置里写“哪个模板对应哪个输出”，目录结构本身就是映射关系。这种“约定优于配置”的做法，能让配置块保持极简。
6.3 场景三：数据报表的快速产出
我每周要出一份数据报表，格式固定，只是数字不同。以前我是手动改 Excel，后来改成用 t3code 生成 Markdown 报表。模板里写表格的骨架，vars里放数字，输出块生成.md文件。整个过程不到一秒，而且格式永远不会错。
这个场景里，t3code 的价值是可重复性。手动改 Excel 每次都可能漏掉某个单元格，或者格式刷错。用模板生成，只要模板是对的，输出就是对的。而且你可以把生成过程放进定时任务，每周自动跑，连手动触发都省了。
7. 关于 t3code 的几个常见误解
7.1 误解一：t3code 是一个框架或者库
不是。t3code 更像是一种代码组织约定，而不是一个可以pip install的东西。你不需要引入任何依赖，只需要按照“入口、配置、输出”三块来组织你的代码。它没有版本号，没有 API 文档，没有社区。它的全部内容就是这篇文章里讲的这些原则。
这个误解的来源可能是“t3”这个前缀让人联想到某些框架的命名风格。但 t3code 的“t3”指的是“three”，也就是三个核心块。它不提供任何运行时能力，只提供一种结构上的参考。
7.2 误解二：三块结构只适合小项目
恰恰相反。小项目用三块结构是“杀鸡用牛刀”，因为小项目本身就没多少逻辑，分不分块区别不大。三块结构真正发挥价值的地方是中等规模的项目——大到需要分文件，但又没大到需要分层架构。这时候三块结构能帮你避免“过度设计”，同时保持清晰。
对于大项目，三块结构可以作为“最小单元”嵌套使用。比如你的系统有十个生成器，每个生成器内部用三块结构，生成器之间通过配置对象通信。这样每个生成器都是独立的、可测试的，整体又不会失控。
7.3 误解三：配置块就是读配置文件
读配置文件只是配置块最基础的功能。配置块的核心是把变化收敛到一个地方。它可以是读文件，也可以是读环境变量、读命令行参数、读数据库。关键是：不管变化从哪来，最终都变成一个配置对象，传给输出块。
我见过一些实现，配置块只负责读 YAML，然后输出块里又去读环境变量。这就把变化来源分散了，违背了 t3code 的原则。正确的做法是：配置块把 YAML 和环境变量都读进来，合并成一个配置对象。输出块只认这个对象，不认 YAML 也不认环境变量。
8. 我踩过的两个真实坑和最后的建议
第一个坑是关于模板引擎的。我一开始觉得字符串替换太简陋，就引入了 Jinja2。结果模板里开始出现{% for %}和{% if %}，配置块里开始出现“渲染上下文”和“过滤器注册”。三块结构被撑成了五块，入口、配置、渲染、过滤、输出。后来我把 Jinja2 去掉，回到字符串替换，整个项目立刻清爽了。如果你的模板需要循环和条件，那说明你不应该用 t3code，应该用真正的模板引擎。t3code 的边界就是“简单替换”，越界了就要换工具。
第二个坑是关于错误处理的。我一开始在入口里加了 try-except，把所有异常都捕获，然后打印“出错了，请检查输入”。结果调试的时候完全不知道哪里错了，因为所有错误信息都被吞掉了。后来我把 try-except 去掉，让异常直接抛出来，调试效率立刻提升。t3code 的哲学是“让错误暴露，而不是掩盖”。如果你需要友好的错误提示，那应该是调用方的事，不是工具的事。
最后分享一个小技巧：如果你不确定某个逻辑该放哪一块，就问自己一个问题——“这个逻辑在配置不变的情况下会变吗？”如果会变，放配置块；如果不会变，放输出块；如果它只跟“怎么读数据”有关，放入口块。这个判断标准我用了很多次，基本没出过错。
