t3code 这个名字熟悉全栈开发的朋友大概能看出门道前面的 t3 指的就是那套很有名的 T3 技术栈——Tailwind CSS、TypeScript、tRPC 的组合而 code 是它真正要解决的事情——代码片段的沉淀与管理。简单说t3code 是我最近从零到一做完的一个全栈代码片段管理工具用来替代我散落在浏览器书签、ChatGPT 收藏、本地文件里的各种随手记代码。这篇文章会把整个项目的设计思路、技术选型、核心实现、上线前后踩过的坑完整梳理一遍给正在折腾 T3 Stack 或者想做类似工具型产品的朋友一份可复现的参考。1. 先聊聊 t3code 要解决什么问题1.1 那些散落各处的代码碎片做开发久了你会发现一个很诡异的现象我们天天写代码、搜代码、抄代码但真正属于自己的代码资产少得可怜。最常见的状态是——某个函数写法这周刚用过下周要用的时候死活想不起来只能重新去 Stack Overflow 翻、去命令行历史里翻、去 git 提交记录里翻。我以前试过浏览器书签存链接、本地 Markdown 文件做笔记、看一眼就丢进收藏夹结果没有一个能长期坚持下来。问题出在哪书签只能存链接存不了正文Markdown 笔记写起来太重收藏夹里的内容没有检索能力。等你想找一段怎么给日期格式化成 YYYY-MM-DD的片段时你面对的是一个巨大的、无索引的、毫无分类的垃圾堆。t3code 最开始就是冲着这个痛点去的我需要一个能把代码片段快速存进来、打上标签、随时全文检索、还能一键复制回剪贴板的地方。1.2 产品边界不做大而全做贴身手账工具类产品最容易犯的错误是一上来就想做团队协作 权限管理 工作流审批这种大而全的东西。t3code 我刻意把边界收得很窄单人为主、少量协作为辅核心功能就三件——存片段、打标签、全文搜索。分享功能只做一个公开链接不做复杂的团队权限体系。这样做的好处非常明显产品逻辑简单数据模型清爽全栈开发的工作量被控制在一个周末加几个晚上就能完成的范围内。而且单人场景下你不需要考虑并发、权限、审计日志这些复杂话题可以把精力全部花在类型安全、搜索体验和复制粘贴效率上。我觉得做工具型项目先做个人工具先解决自己的问题是最稳的切入点。2. 技术选型为什么是 T3 全家桶2.1 全栈类型安全到底省了多少事T3 Stack 的核心思想是类型安全优先最直接的体现就是前后端共享一套类型定义。传统的前后端分离模式里接口文档是前后端沟通的唯一桥梁前端拿到接口第一件事是去手写一遍类型声明后端字段一改前端就静默崩掉。t3code 的场景几乎是为 tRPC 量身定做的全栈都是 TypeScript没有第三方客户端不需要搞 REST 风格的资源路径设计。tRPC 最爽的地方在于后端 Router 里定义好一个查询前端直接 import 就能拿到带完整类型推断的结果。改后端响应结构时TypeScript 编译器会立刻在前端调用处报错这种类型错误当场暴露的体验一旦用上就很难回去。我在项目里用一句话概括这种差距以前是前端猜后端的返回现在是前端和后端共享同一张类型契约猜不存在的。2.2 为什么是 Next.js Prisma NextAuthNext.js 在这个项目里承担的是全栈容器页面渲染、API 路由、服务端逻辑都跑在同一个应用里。t3code 的页面量不大一个列表页、一个详情页、一个新增/编辑页用 App Router 的文件系统路由很合适。配合 Server Component列表页可以直接在服务端拉数据渲染首屏速度非常理想。数据层选了 Prisma坦白说主要是看中它的开发体验。手写 SQL 在简单 CRUD 里确实没必要Prisma 的 schema 即文档、迁移命令一键搞定对个人项目来说能省掉大量样板代码。需要注意的一点是 Prisma 在服务端环境下用起来很顺但在客户端组件里千万不要直接调 Prisma client会带来严重的安全隐患——客户端拿到的数据库连接等于裸奔。身份认证选的 NextAuth因为 T3 Stack 生态里它是默认集成方案。t3code 支持 GitHub OAuth 登录目的是让分享功能有一个归属概念。如果你是自己单机部署、纯个人使用甚至可以不开认证把 NextAuth 配置留着以后需要时再启用。3. 核心实现从数据模型到交互落地3.1 数据模型设计t3code 的数据模型非常简洁核心就三张表用户、代码片段、标签。多对多关系通过一张隐式的关联表处理。下面是我在schema.prisma里实际使用的定义model User { id String id default(cuid()) name String? email String? unique emailVerified DateTime? image String? snippets Snippet[] } model Snippet { id String id default(cuid()) title String description String? code String language String default(text) visibility String default(private) createdAt DateTime default(now()) map(created_at) updatedAt DateTime updatedAt map(updated_at) authorId String author User relation(fields: [authorId], references: [id]) tags Tag[] index([authorId, createdAt]) map(snippets) } model Tag { id String id default(cuid()) name String unique snippets Snippet[] }这个模型有几点值得说道。language字段没有用枚举而是普通字符串加前端下拉选择因为代码语言列表一直在膨胀硬编码进数据库枚举会让后续扩展非常痛苦。visibility字段我预留了private和public两个值公开片段会生成一个不包含用户信息的只读分享链接私有片段只对创建者自己可见。index里把作者 ID 和时间戳做成联合索引是因为列表页最常见的查询就是某个用户的片段按时间倒序。3.2 tRPC Router 划分与核心 APItRPC 的项目组织方式我推荐按领域拆 Router而不是按页面拆。t3code 里我拆了两个snippetRouter管片段的增删改查tagRouter管标签的列表和聚合。入口文件用一个appRouter把它们合并起来前端调用时是一个扁平的类型空间。// server/api/root.ts export const appRouter router({ snippet: snippetRouter, tag: tagRouter, }); export type AppRouter typeof appRouter;片段列表的查询接口是关键我用 tRPC 的publicProcedure加输入校验接收authorId、tagId、keyword、cursor四个参数。搜索用 Prisma 的contains做模糊匹配再加上标签过滤和基于游标的分页。// server/api/routers/snippet.ts list: publicProcedure .input( z.object({ authorId: z.string().optional(), tagId: z.string().optional(), keyword: z.string().optional(), cursor: z.string().optional(), }) ) .query(async ({ ctx, input }) { return ctx.prisma.snippet.findMany({ take: 20, skip: input.cursor ? 1 : 0, cursor: input.cursor ? { id: input.cursor } : undefined, where: { ...(input.authorId ? { authorId: input.authorId } : {}), ...(input.tagId ? { tags: { some: { id: input.tagId } } } : {}), ...(input.keyword ? { OR: [ { title: { contains: input.keyword } }, { code: { contains: input.keyword } }, ], } : {}), }, include: { tags: true }, orderBy: { createdAt: desc }, }); }),这段代码里最实用的是OR条件组合它保证用户搜关键词时能同时命中标题和代码正文。有一个细节要注意用skip cursor做分页时如果表里恰好有数据在翻页过程中被删除可能出现某一页少一条的情况。个人项目场景下问题不大但如果你做面向公众的产品建议换成基于上次返回的最后一条记录 ID做范围的方案。3.3 重点功能新增片段与一键复制新增片段页面是我花时间最多的部分。因为代码片段的核心消费场景是复制完就走所以表单交互必须快。我做了两个小优化标题输入框支持失焦自动保存到本地草稿刷新页面不会丢内容保存成功之后自动跳转到片段详情页减少一次点击。编辑器区域我没有上重型代码编辑器组件只用了带等宽字体和行号的自定义textarea搭配pre高亮展示。一键复制用的是navigator.clipboard.writeText在 HTTPS 环境下表现很稳。但浏览器对 clipboard API 的权限策略有个坑只有在用户手势点击按钮触发的回调里调用才会成功如果你在useEffect或者异步回调的末尾再复制大概率被浏览器静默拒绝。稳妥做法是把复制方法直接绑在按钮的onClick上不做中间状态。4. 上线前踩过的坑排查实录4.1 tRPC 类型不更新的问题tRPC 项目开发中最常见的问题就是前端明明改了后端代码类型却还是旧的。t3code 里我第一次遇到时排查了半天一度以为是 Next.js 缓存问题。后来发现根因是 tRPC 的类型是从AppRouter推导出来的如果你在多个文件里引用了旧版本的AppRouter类型编辑器会把旧的声明缓存住。解决手段很直接改完 Router重启 dev server 让 TS 重新做一次全量类型检查同时确认tsconfig.json没有开启过度的路径映射别名导致指向了别的地方。4.2 Prisma 连接数打满部署到服务器之后我观察到数据库偶尔报Too many connections。这个问题在本地开发完全不会出现一到生产环境就暴露。原因是我在服务端组件里多处直接new PrismaClient()每个实例都会占用一个连接池。修复方法是把 Prisma client 做成了全局单例// server/db.ts import { PrismaClient } from prisma/client; const globalForPrisma globalThis as unknown as { prisma: PrismaClient | undefined; }; export const prisma globalForPrisma.prisma ?? new PrismaClient(); if (process.env.NODE_ENV ! production) { globalForPrisma.prisma prisma; }这个模式在 Next.js 官方文档里也有体现核心价值就是利用globalThis在开发环境的热更新过程中维持同一个 client 实例避免每次刷新都新建连接。4.3 NextAuth 登录回调 401配置 GitHub OAuth 后本地登录一切正常部署到线上就出现登录成功但回调 401 的情况。查了一圈发现是环境变量的问题NextAuth 要求NEXTAUTH_URL必须和实际访问地址完全一致包括协议头否则回调地址会对不上。还有一个很容易忽略的点是AUTH_SECRET老版本叫NEXTAUTH_SECRET必须显式设置不要依赖自动生成。自动生成的 secret 在每次重启后都会变已签发的 session 全部失效用户会莫名其妙被踢下线。这两个环境变量在生产环境务必写死在部署平台的配置中心里。4.4 全文搜索的性能边界t3code 早期用的是 Prisma 的contains做模糊搜索数据量在几千条以内响应时间非常可观所以一开始我觉得这个方案够用了。直到我把几年前攒的上万条代码笔记导入进去明显感觉到关键词搜索变慢。contains在后台生成的是LIKE %keyword%查询这种查询无法走普通 B-Tree 索引只能全表扫描。针对这个瓶颈我做了分层处理数据量小的自建部署继续用contains需要高性能搜索时切换到一个支持全文索引的方案。具体做法是把片段正文在写入时拆成词项存一份搜索时走索引表复杂度从全表扫描降到了索引查询。这个优化不复杂但对阅读体验和搜索结果相关性帮助极大。如果你也是个人项目建议数据量没破万之前别折腾搜索引擎保持简单优先。5. 一点个人经验做工具型项目的心得t3code 做完之后我最大的感受是技术栈的选择其实是在给未来的自己省麻烦。T3 Stack 最大的价值不是某个单一框架多好用而是类型安全、约定一致、文档少这三个特性能让一个人的全栈开发保持在一个很舒服的节奏上。以前我在前后端分离项目里光维护接口文档和联调就消耗大量精力在 t3code 里这些成本几乎为零因为类型系统把错误挡在了编译之前。如果你也想复刻一个类似的工具型项目我给三个建议。第一数据模型一定从简开始能用两到三张主表解决的场景绝不要一开始就上十张表。第二搜索功能等有真实数据量再优化不要为了技术亮点提前引入过重的组件。第三剪贴板、键盘快捷键、本地草稿这类不起眼的体验细节才是工具类产品真正留住用户的地方。t3code 后续我打算加上浏览器扩展让收藏代码变成浏览器右键一键的事再把公开分享页做成一个轻量级的代码展示名片。工具不一定要大但一定要顺手。 
长河君 · 2026/10/26 17:17:30 · 阅读 1.2k 基于T3 Stack打造全栈代码片段管理工具t3code实战
t3code 这个名字熟悉全栈开发的朋友大概能看出门道前面的 t3 指的就是那套很有名的 T3 技术栈——Tailwind CSS、TypeScript、tRPC 的组合而 code 是它真正要解决的事情——代码片段的沉淀与管理。简单说t3code 是我最近从零到一做完的一个全栈代码片段管理工具用来替代我散落在浏览器书签、ChatGPT 收藏、本地文件里的各种随手记代码。这篇文章会把整个项目的设计思路、技术选型、核心实现、上线前后踩过的坑完整梳理一遍给正在折腾 T3 Stack 或者想做类似工具型产品的朋友一份可复现的参考。1. 先聊聊 t3code 要解决什么问题1.1 那些散落各处的代码碎片做开发久了你会发现一个很诡异的现象我们天天写代码、搜代码、抄代码但真正属于自己的代码资产少得可怜。最常见的状态是——某个函数写法这周刚用过下周要用的时候死活想不起来只能重新去 Stack Overflow 翻、去命令行历史里翻、去 git 提交记录里翻。我以前试过浏览器书签存链接、本地 Markdown 文件做笔记、看一眼就丢进收藏夹结果没有一个能长期坚持下来。问题出在哪书签只能存链接存不了正文Markdown 笔记写起来太重收藏夹里的内容没有检索能力。等你想找一段怎么给日期格式化成 YYYY-MM-DD的片段时你面对的是一个巨大的、无索引的、毫无分类的垃圾堆。t3code 最开始就是冲着这个痛点去的我需要一个能把代码片段快速存进来、打上标签、随时全文检索、还能一键复制回剪贴板的地方。1.2 产品边界不做大而全做贴身手账工具类产品最容易犯的错误是一上来就想做团队协作 权限管理 工作流审批这种大而全的东西。t3code 我刻意把边界收得很窄单人为主、少量协作为辅核心功能就三件——存片段、打标签、全文搜索。分享功能只做一个公开链接不做复杂的团队权限体系。这样做的好处非常明显产品逻辑简单数据模型清爽全栈开发的工作量被控制在一个周末加几个晚上就能完成的范围内。而且单人场景下你不需要考虑并发、权限、审计日志这些复杂话题可以把精力全部花在类型安全、搜索体验和复制粘贴效率上。我觉得做工具型项目先做个人工具先解决自己的问题是最稳的切入点。2. 技术选型为什么是 T3 全家桶2.1 全栈类型安全到底省了多少事T3 Stack 的核心思想是类型安全优先最直接的体现就是前后端共享一套类型定义。传统的前后端分离模式里接口文档是前后端沟通的唯一桥梁前端拿到接口第一件事是去手写一遍类型声明后端字段一改前端就静默崩掉。t3code 的场景几乎是为 tRPC 量身定做的全栈都是 TypeScript没有第三方客户端不需要搞 REST 风格的资源路径设计。tRPC 最爽的地方在于后端 Router 里定义好一个查询前端直接 import 就能拿到带完整类型推断的结果。改后端响应结构时TypeScript 编译器会立刻在前端调用处报错这种类型错误当场暴露的体验一旦用上就很难回去。我在项目里用一句话概括这种差距以前是前端猜后端的返回现在是前端和后端共享同一张类型契约猜不存在的。2.2 为什么是 Next.js Prisma NextAuthNext.js 在这个项目里承担的是全栈容器页面渲染、API 路由、服务端逻辑都跑在同一个应用里。t3code 的页面量不大一个列表页、一个详情页、一个新增/编辑页用 App Router 的文件系统路由很合适。配合 Server Component列表页可以直接在服务端拉数据渲染首屏速度非常理想。数据层选了 Prisma坦白说主要是看中它的开发体验。手写 SQL 在简单 CRUD 里确实没必要Prisma 的 schema 即文档、迁移命令一键搞定对个人项目来说能省掉大量样板代码。需要注意的一点是 Prisma 在服务端环境下用起来很顺但在客户端组件里千万不要直接调 Prisma client会带来严重的安全隐患——客户端拿到的数据库连接等于裸奔。身份认证选的 NextAuth因为 T3 Stack 生态里它是默认集成方案。t3code 支持 GitHub OAuth 登录目的是让分享功能有一个归属概念。如果你是自己单机部署、纯个人使用甚至可以不开认证把 NextAuth 配置留着以后需要时再启用。3. 核心实现从数据模型到交互落地3.1 数据模型设计t3code 的数据模型非常简洁核心就三张表用户、代码片段、标签。多对多关系通过一张隐式的关联表处理。下面是我在schema.prisma里实际使用的定义model User { id String id default(cuid()) name String? email String? unique emailVerified DateTime? image String? snippets Snippet[] } model Snippet { id String id default(cuid()) title String description String? code String language String default(text) visibility String default(private) createdAt DateTime default(now()) map(created_at) updatedAt DateTime updatedAt map(updated_at) authorId String author User relation(fields: [authorId], references: [id]) tags Tag[] index([authorId, createdAt]) map(snippets) } model Tag { id String id default(cuid()) name String unique snippets Snippet[] }这个模型有几点值得说道。language字段没有用枚举而是普通字符串加前端下拉选择因为代码语言列表一直在膨胀硬编码进数据库枚举会让后续扩展非常痛苦。visibility字段我预留了private和public两个值公开片段会生成一个不包含用户信息的只读分享链接私有片段只对创建者自己可见。index里把作者 ID 和时间戳做成联合索引是因为列表页最常见的查询就是某个用户的片段按时间倒序。3.2 tRPC Router 划分与核心 APItRPC 的项目组织方式我推荐按领域拆 Router而不是按页面拆。t3code 里我拆了两个snippetRouter管片段的增删改查tagRouter管标签的列表和聚合。入口文件用一个appRouter把它们合并起来前端调用时是一个扁平的类型空间。// server/api/root.ts export const appRouter router({ snippet: snippetRouter, tag: tagRouter, }); export type AppRouter typeof appRouter;片段列表的查询接口是关键我用 tRPC 的publicProcedure加输入校验接收authorId、tagId、keyword、cursor四个参数。搜索用 Prisma 的contains做模糊匹配再加上标签过滤和基于游标的分页。// server/api/routers/snippet.ts list: publicProcedure .input( z.object({ authorId: z.string().optional(), tagId: z.string().optional(), keyword: z.string().optional(), cursor: z.string().optional(), }) ) .query(async ({ ctx, input }) { return ctx.prisma.snippet.findMany({ take: 20, skip: input.cursor ? 1 : 0, cursor: input.cursor ? { id: input.cursor } : undefined, where: { ...(input.authorId ? { authorId: input.authorId } : {}), ...(input.tagId ? { tags: { some: { id: input.tagId } } } : {}), ...(input.keyword ? { OR: [ { title: { contains: input.keyword } }, { code: { contains: input.keyword } }, ], } : {}), }, include: { tags: true }, orderBy: { createdAt: desc }, }); }),这段代码里最实用的是OR条件组合它保证用户搜关键词时能同时命中标题和代码正文。有一个细节要注意用skip cursor做分页时如果表里恰好有数据在翻页过程中被删除可能出现某一页少一条的情况。个人项目场景下问题不大但如果你做面向公众的产品建议换成基于上次返回的最后一条记录 ID做范围的方案。3.3 重点功能新增片段与一键复制新增片段页面是我花时间最多的部分。因为代码片段的核心消费场景是复制完就走所以表单交互必须快。我做了两个小优化标题输入框支持失焦自动保存到本地草稿刷新页面不会丢内容保存成功之后自动跳转到片段详情页减少一次点击。编辑器区域我没有上重型代码编辑器组件只用了带等宽字体和行号的自定义textarea搭配pre高亮展示。一键复制用的是navigator.clipboard.writeText在 HTTPS 环境下表现很稳。但浏览器对 clipboard API 的权限策略有个坑只有在用户手势点击按钮触发的回调里调用才会成功如果你在useEffect或者异步回调的末尾再复制大概率被浏览器静默拒绝。稳妥做法是把复制方法直接绑在按钮的onClick上不做中间状态。4. 上线前踩过的坑排查实录4.1 tRPC 类型不更新的问题tRPC 项目开发中最常见的问题就是前端明明改了后端代码类型却还是旧的。t3code 里我第一次遇到时排查了半天一度以为是 Next.js 缓存问题。后来发现根因是 tRPC 的类型是从AppRouter推导出来的如果你在多个文件里引用了旧版本的AppRouter类型编辑器会把旧的声明缓存住。解决手段很直接改完 Router重启 dev server 让 TS 重新做一次全量类型检查同时确认tsconfig.json没有开启过度的路径映射别名导致指向了别的地方。4.2 Prisma 连接数打满部署到服务器之后我观察到数据库偶尔报Too many connections。这个问题在本地开发完全不会出现一到生产环境就暴露。原因是我在服务端组件里多处直接new PrismaClient()每个实例都会占用一个连接池。修复方法是把 Prisma client 做成了全局单例// server/db.ts import { PrismaClient } from prisma/client; const globalForPrisma globalThis as unknown as { prisma: PrismaClient | undefined; }; export const prisma globalForPrisma.prisma ?? new PrismaClient(); if (process.env.NODE_ENV ! production) { globalForPrisma.prisma prisma; }这个模式在 Next.js 官方文档里也有体现核心价值就是利用globalThis在开发环境的热更新过程中维持同一个 client 实例避免每次刷新都新建连接。4.3 NextAuth 登录回调 401配置 GitHub OAuth 后本地登录一切正常部署到线上就出现登录成功但回调 401 的情况。查了一圈发现是环境变量的问题NextAuth 要求NEXTAUTH_URL必须和实际访问地址完全一致包括协议头否则回调地址会对不上。还有一个很容易忽略的点是AUTH_SECRET老版本叫NEXTAUTH_SECRET必须显式设置不要依赖自动生成。自动生成的 secret 在每次重启后都会变已签发的 session 全部失效用户会莫名其妙被踢下线。这两个环境变量在生产环境务必写死在部署平台的配置中心里。4.4 全文搜索的性能边界t3code 早期用的是 Prisma 的contains做模糊搜索数据量在几千条以内响应时间非常可观所以一开始我觉得这个方案够用了。直到我把几年前攒的上万条代码笔记导入进去明显感觉到关键词搜索变慢。contains在后台生成的是LIKE %keyword%查询这种查询无法走普通 B-Tree 索引只能全表扫描。针对这个瓶颈我做了分层处理数据量小的自建部署继续用contains需要高性能搜索时切换到一个支持全文索引的方案。具体做法是把片段正文在写入时拆成词项存一份搜索时走索引表复杂度从全表扫描降到了索引查询。这个优化不复杂但对阅读体验和搜索结果相关性帮助极大。如果你也是个人项目建议数据量没破万之前别折腾搜索引擎保持简单优先。5. 一点个人经验做工具型项目的心得t3code 做完之后我最大的感受是技术栈的选择其实是在给未来的自己省麻烦。T3 Stack 最大的价值不是某个单一框架多好用而是类型安全、约定一致、文档少这三个特性能让一个人的全栈开发保持在一个很舒服的节奏上。以前我在前后端分离项目里光维护接口文档和联调就消耗大量精力在 t3code 里这些成本几乎为零因为类型系统把错误挡在了编译之前。如果你也想复刻一个类似的工具型项目我给三个建议。第一数据模型一定从简开始能用两到三张主表解决的场景绝不要一开始就上十张表。第二搜索功能等有真实数据量再优化不要为了技术亮点提前引入过重的组件。第三剪贴板、键盘快捷键、本地草稿这类不起眼的体验细节才是工具类产品真正留住用户的地方。t3code 后续我打算加上浏览器扩展让收藏代码变成浏览器右键一键的事再把公开分享页做成一个轻量级的代码展示名片。工具不一定要大但一定要顺手。