关于 t3code一个由原生小程序驱动的一体化业务交付方案我最初接触 t3code 这个代号是在一个做本地生活服务的客户项目里。当时团队刚接手一个既有 App 端、又有 Web 管理后台和商家小程序的混合项目代码仓库散落接口风格不统一前端同学和后端同学各维护一套字段映射联调时经常因为字段名大小写问题来回扯皮。t3code 是另一个团队留下的内部代号起初我以为是某个自动化代码生成工具的版本号翻完文档和技术栈清单后才发现它本质上是一套围绕“原生小程序 统一服务层”的轻量级全栈交付方案——用微信小程序原生语法做用户端载体用 Node.js 的通用中间层做业务聚合再把后台管理端收敛到一个基础框架里复用。这套东西不是那种需要你重学一套新语言、新框架的“全家桶”反倒是把大家已经熟悉的技术栈用一套约定串了起来通过类型定义、接口约定和目录规范来约束协作方式。t3code 能解决的问题说白了就是中小型业务中最常见的三类痛一是小程序原生开发在多人协作时的代码组织混乱Page 里挂一堆业务请求公共逻辑和页面逻辑混在一起二是前后端接口数据结构的语义断层后端返回created_at前端写成createTime再经过一层数据清洗到最后渲染层都不知道哪个字段才是对的三是多端项目用户小程序、商家端、管理后台重复建设登录态、请求封装、权限路由、错误提示这些基础模块每个端都写一遍样式风格还不统一。t3code 通过把整套技术栈固化成模板和约定让新成员入职后能直接进入业务开发而不是先花两周搞懂各端各自的封装方式。如果你手头正在做一个需要小程序端 管理后台 API 服务三个部分同时推进的小项目或者团队中已经有了一套独立小程序代码库却苦于没有好的方式去规范多端协作那 t3code 这套思路很值得你花点时间看完。接下来我会从项目结构设计、核心模块拆解、服务端接口约定、实际部署维护这几个角度完整复盘这套方案的关键细节和落地经验。1. 整体设计与架构思路为什么是原生小程序而不是跨端框架先回到方案选择的最前端。很多项目一开始会纠结小程序要不要用跨端框架来写比如 uni-app、Taro 这类。t3code 的设计选择是坚持用微信小程序原生语法做用户端和商家端Web 管理后台保留传统模板加 AJAX 的方式服务端用 Node.js。乍一看这个选型有点保守但实际落地跑完几个版本后我反而越发认可这个判断——对于依赖微信生态能力的项目原生语法能少很多麻烦而对团队协作而言固定一套目录结构和公共模块约定的价值要远大于框架本身给的那点语法糖。1.1 原生小程序的真实收益接口体验与迭代节奏不受框架约束跨端框架最大的诱惑是一套代码多端复用。但这个收益在小程序场景里经常大打折扣因为各个小程序平台的基础库能力、隐私合规要求、支付逻辑都不一样。你为了兼容多端引入的抽象层往往在实际开发中变成了条件编译碎片的堆砌地。t3code 采用原生语法第一个好处就是对微信基础库的新特性可以第一时间直接用不用等框架层适配。比如最新的手机号快速验证组件、交易组件、订阅消息的模板升级这些如果是靠第三方框架封装通常会慢半拍而原生语法能跟官方的迭代节奏保持一致。第二个好处是调试成本低。原生小程序开发者工具对原生代码的报错、断点、性能面板支持最直接不需要额外关心框架的编译产物和 sourcemap 映射问题。我在实际项目里遇到过 Taro 项目报错堆栈指不到原始代码的情况排查成本会明显增加而原生代码基本不会出这种问题。当然坚持原生写法的前提是不要重复造轮子。t3code 里抽了一套公共的core目录把请求封装、登录态、工具函数、自定义导航栏这些高频模块全部沉淀下来各端通过相对路径引用同一套代码。业务页面里只写页面逻辑跨端的公共能力全部走core。这样做既能享受原生语法的直接性又不至于每个页面都重复一堆初始化代码。1.2 统一服务层设计请求聚合与数据结构固定t3code 的服务端设计的核心是所有端面对的不是散落的业务表而是一个聚合后的业务服务层。用户端小程序、商家端小程序、Web 管理后台统一通过这个业务服务层拿数据。这个服务层在 Node.js 里以路由模块加服务模块的方式组织每个业务领域的服务模块对外暴露固定方法路由负责参数校验和身份校验服务模块负责业务规则和存储层对接。这样设计的好处在于数据结构是稳定的。比如订单详情无论在哪个端请求返回的都是同一套字段结构不存在用户端拿到的订单状态和管理后台拿到的状态含义不一致的情况。数据结构的定义集中在一个types文件里前端各端直接引用这份类型定义生成对应的数据结构映射。如果后端需要调整字段改动类型定义后各端都会在同一次联调中感知到而不是靠群里吼一声然后各改各的。这类统一数据结构在 t3code 里实际上是全局约束。所有服务接口的返回格式固定为三段式code、message、data。code是业务状态码不是 HTTP 状态码message是给前端提示用的文本data是真正的业务数据。这样设计下前端的统一请求层只需要处理这一种结构网络异常、业务失败、正常返回的情况在入口处就分流清楚不会出现页面里到处写各种状态判断的散乱局面。表面上看这只是一套规约但真正落地后前后端联调效率确实提升明显——因为类型定义文件和接口文档是在同一个仓库里维护的代码即文档文档即类型任何不一致在编译阶段就会被拦截而不是等运行时报错才暴露。1.3 多端协作的目录规范一方定义多方复用t3code 的代码仓库采用单仓库结构里面按端划分了三个主目录miniprogram-user、miniprogram-merchant、admin-web以及一个共享的service-server。每个端目录下面又固定划分为pages、components、core、utils、styles这五个子目录。这套划分解决了我在多个项目中反复遇到的共性问题组件不知道该放哪个目录、页面和通用逻辑的界限模糊、样式变量散落各处难以统一维护。共享层专门抽出了shared-types目录里面放接口类型定义和枚举常量前后端所有引用都从这一份代码里导入。实际效果是只要类型定义统一前端写页面时自带的智能提示就能告诉你能用哪些字段后端也能通过校验规则确保不会把范围外的状态值写入存储。遇到要修改接口字段的场景改动集中在类型定义一处所有引用方都会在编译时报错提示这比任何文档流程都来得可靠。2. 核心技术拆解目录、类型与请求层是如何协同工作的不少团队不是没有技术规范而是规范散落在各种文档里落实不到实际代码上。t3code 的做法是把规范固化到模板和工具链中。这一节我拆解三个具体的技术环节核心目录的组织逻辑、类型定义如何联动前后端、统一请求层如何降低调用成本。2.1 核心目录结构与职责边界t3code 的小程序端目录结构大体如下miniprogram-user/ ├── pages/ │ ├── index/ │ ├── order/ │ └── profile/ ├── components/ │ ├── custom-nav/ │ ├── order-card/ │ └── empty-state/ ├── core/ │ ├── request.js │ ├── auth.js │ ├── config.js │ └── constants.js ├── utils/ │ ├── format.js │ ├── validator.js │ └── share.js └── styles/ ├── variables.wxss ├── mixins.wxss └── common.wxsspages目录严格只放页面级代码每个页面一个文件夹里面包含.wxml、.wxss、.js、.json四个文件。页面内允许有少量该页面特有的展示逻辑但所有涉及数据请求的代码一律调用core/request.js暴露的方法不允许在Page({})里裸写wx.request。components目录放的是跨页面复用的业务组件比如订单卡片、空状态、自定义导航栏。组件的样式统一引用styles下的变量和混入保证视觉一致性。core目录是重点它封装了所有端共用的底层能力请求实例、登录流程、全局配置、常量枚举。utils目录放纯函数工具比如日期格式化、手机号脱敏、校验规则不依赖任何页面上下文。styles目录只有样式变量和混入不承载业务逻辑。这套边界一旦定了团队协作时基本不用讨论某个文件该放哪里。新成员看着目录结构就知道职责归属代码评审的时候也只需要盯着核心业务逻辑不用反复纠正基础模块的放置位置。2.2 类型定义如何成为前后端的连接器t3code 的类型定义文件不是泛泛地写一份接口文档而是切实参与到代码生成和编译检查中的。下面以一个典型的商品对象为例// shared-types/product.ts export interface Product { id: string; title: string; coverUrl: string; price: number; originalPrice?: number; sales: number; stock: number; status: on | off | deleted; categoryId: string; createdAt: string; updatedAt: string; } export interface ProductListParams { page: number; pageSize: number; categoryId?: string; keyword?: string; sortBy?: default | sales | price_asc | price_desc; } export interface ProductListResult { list: Product[]; total: number; hasMore: boolean; }小程序端虽然不能直接运行 TypeScript但借助开发者工具自带的 TypeScript 编译能力同样可以在代码中引入类型定义。这样在小程序端写页面时编辑器能准确提示每个字段的类型和可选性拼错字段名、把数字类型当成字符串拼接这类问题在一开始就能被工具发现。服务端的路由处理直接引用同一份类型定义参数校验通过后返回的数据必须符合ProductListResult的结构。我实际落地时还加了一层简单的运行时校验在非生产环境打印结构不符的警告方便第一时间发现前后端定义不同步的问题。这套方案比手工维护接口文档好用得多因为业务改字段时你只需要改动类型定义然后所有引用方会通过编译提示告诉你还有哪些地方没有同步改到位。2.3 统一请求层的设计与实现小程序端的网络层如果没有统一封装最常见的后果是每个页面的onLoad里堆着一堆wx.request回调错误处理方式五花八门。t3code 将请求层收敛到core/request.js核心实现思路如下// core/request.js const request (url, options {}) { return new Promise((resolve, reject) { wx.request({ url: getBaseUrl() url, method: options.method || GET, data: options.data || {}, header: buildHeader(options.auth ! false), success(res) { const { code, message, data } res.data || {}; if (code 0) { resolve(data); } else { handleBusinessError(code, message); reject({ code, message }); } }, fail(err) { handleNetworkError(err); reject(err); }, }); }); };所有接口返回统一为{ code, message, data }结构code为 0 表示成功非 0 根据业务错误码做提示或跳转登录。页面调用时不用关心loading和错误弹窗因为通用逻辑都收口在处理函数里。需要拉取最新数据做下拉刷新时直接重新调用请求方法即可不用在页面里维护一堆请求状态。这个封装给团队带来的最大收益是排错简单。线上出了问题看网络请求面板能直接看到某个接口产生了一个非 0 的业务错误码而且每个页面展示的错误是一致的不会出现一个人写toast、一个人写modal的情况。登录失效的处理也统一了当请求层识别到未授权错误时会自动清理本地登录态并跳转到登录页每个页面无需各自处理。3. 从零搭建到首版交付完整实操过程记录做技术方案分享最怕没有实操参考。这节我以一个虚拟的业务场景为例完整走一遍 t3code 体系下从初始化项目到首版交付的过程假设要做一个社区生鲜团购的小程序包括用户端浏览商品、下单支付和运营端商品管理、订单处理。3.1 项目初始化与依赖安装使用 t3code 模板初始化项目首先是拉取仓库模板和安装依赖git clone gityour-git-host:t3code/t3code-starter.git fresh-project cd fresh-project npm install模板自带以下基础配置// project.config.json 关键项 { miniprogramRoot: miniprogram-user/, cloudfunctionRoot: service-server/, setting: { es6: true, minified: true, urlCheck: true } }miniprogramRoot指向用户端小程序目录cloudfunctionRoot指向服务端目录。如果商家端要单独跑用微信开发者工具导入miniprogram-merchant目录即可。管理后台是纯 Web 项目直接npm run dev启动。整个模板启动后三端工程会共享同一份类型定义和服务端契约新需求的接口设计在类型定义里完成然后三端并行开发。3.2 商品模块的类型定义与服务端实现在设计商品列表这个业务时先约定类型定义。商品数据在用户端要展示标题、封面、价格、销量在运营端还需要管理库存、分类和上下架状态。因此商品类型需要同时覆盖两端诉求但可以通过不同接口返回不同字段的子集。服务端的实现是路由加服务分离// service-server/routes/product.ts router.get(/list, validate(ProductListParams), async (ctx) { const params ctx.validatedData; const result await productService.getList(params); ctx.body success(result); }); router.post(/upsert, checkPermission(product:write), async (ctx) { const data ctx.request.body; await productService.upsert(data); ctx.body success(null); });validate中间件负责校验参数checkPermission负责权限控制真正业务逻辑放在productService.getList和productService.upsert里。参数校验通过后才进入服务层避免把一堆参数判断塞进业务逻辑里。productService.getList内部处理了列表查询和总数统计。我在这类场景里会额外注意 SQL 的查询效率问题尤其是分页场景下避免先查全量再切页的做法。列表接口返回结构里有一个hasMore字段小程序端通过这个字段判断是否还有下一页从而决定是否触发上拉加载避免重复请求无数据的分页。3.3 小程序端的页面实现与状态管理用户端商品列表页的实现要点是页面只负责渲染和交互反馈数据请求走core/request数据状态在onLoad和下拉刷新、上拉加载中维护。// miniprogram-user/pages/index/index.js const { getProductList } require(../../core/api); Page({ data: { list: [], page: 1, hasMore: true, loading: false, }, async onLoad() { await this.loadList(true); }, async loadList(reset false) { if (this.data.loading) return; if (reset) { this.setData({ page: 1, hasMore: true, list: [] }); } if (!this.data.hasMore) return; this.setData({ loading: true }); try { const result await getProductList({ page: this.data.page, pageSize: 10, }); this.setData({ list: reset ? result.list : this.data.list.concat(result.list), hasMore: result.hasMore, page: this.data.page 1, }); } finally { this.setData({ loading: false }); } }, onPullDownRefresh() { this.loadList(true).finally(() wx.stopPullDownRefresh()); }, onReachBottom() { this.loadList(); }, });这段代码展示了一个典型的分页列表逻辑首次加载、下拉刷新、上拉加载三者共用同一个方法通过reset参数区分场景。这里有个比较关键的细节页面上展示的列表数据一定来自统一接口返回的list字段不能各自在页面里改data不然刷新后会看到旧数据残留在一两秒内的情况。凡是列表页都建议维护list、page、hasMore、loading这四个状态字段结构统一后页面写起来会非常流畅。3.4 管理后台的模块复用与权限控制管理后台不用单独引入前端框架t3code 模板默认采用 Vue 3 加 Element Plus但业务页面的写法统一按模块化方式组织。每个业务模块一个目录包含列表页、编辑页、API 定义和类型引用。权限控制不是在每个路由里散落判断而是集中到路由配置的meta字段中由全局路由守卫统一检查。实际体验下来管理后台维护最频繁的地方是权限点的增减集中在路由配置里调整比在组件里改判断要省力得多。4. 常见问题与运维维护实录再严密的模板落到真实线上环境也会遇到各种预想不到的问题。这里整理我在实际项目中碰到的几类典型问题基本都是 t3code 这种多端模式下特有的挑战。4.1 小程序端类型不同步导致的字段缺失小程序端引用共享类型的一个麻烦是类型定义改了但小程序端没有重新编译导致接口返回的新字段在小程序端获取不到。这个问题最容易出现在新增功能迭代时后端提前返回了新字段前端还没发布新版本。最直接的规避方案是前端在代码里对关键字段做兜底处理比如商品封面加一个默认图价格显示加一个0.00的降级文案这样即使字段缺失展示层也不会显得异常。另外一个更有效的手段是把类型检查接入小程序的 CI 流程。在提交代码前跑一次tsc --noEmit能提前暴露类型不一致的问题。微信小程序开发者工具的构建默认不检查类型所以一定要在 CI 脚本里显式加这一步。我在实际项目中就是因为在 CI 里加了类型检查才堵住了好几次后端改了字段、前端没同步改完的情况。4.2 分页接口的重复请求问题分页列表最常见的线上 bug 是重复请求用户快速上拉时同一页数据被请求了两次。根因通常是onReachBottom触发的频率比setData更新loading状态更快。在低端手机上这种情况更容易复现。解决方案就是我在前面代码中展示的if (this.data.loading) return;这个前置判定。凡是列表页建议都把这个检查放在请求方法第一行这是个成本极低但收益非常明显的防护。另一个分页相关的坑是下拉刷新后页码重置的时机。如果先重置page再发起请求页面会短暂显示空列表如果请求成功后再重置旧数据又会残留一段时间。所以我习惯的做法是进入loadList(true)时同步清空列表和重置页码用loading状态配合展示一个顶部的加载提示体验上是自然的。4.3 登录态失效后的联动跳转多端项目中登录态管理一直是重点。t3code 的做法是登录凭证集中存放在core/auth.js中统一处理读取、写入、清除。小程序端的wx.login换取 openid 和会话凭证的过程也被封装在core/auth.js里页面不感知具体实现。线上真正需要关注的问题是登录态失效时多个接口同时报错导致多个页面同时弹出重新登录的提示。t3code 的解决方案是在请求层维护一个isRedirecting标志第一个识别到登录失效的请求负责跳转登录页其余请求仅静默失败避免跳转重复触发。这个标志在登录成功后重置整个联动过程对用户无感实际体验下来比每个页面各自处理要顺畅得多。4.4 服务端跨域与会话配置问题Web 管理后台调用服务端的跨域配置看似简单但实际坑不少。t3code 的服务端用koa/cors处理跨域需要注意两点一是credentials要设置为true否则携带 Cookie 的请求会失败二是允许的来源不要用*必须明确指定管理后台的域名。如果要用 Nginx 反向代理同域部署就不需要配置跨域但这种情况下务必确认路径转发规则无误。服务端和各端实际部署时我用的是 PM2 加 Nginx。服务端应用本身用 PM2 守护进程管理面板看 CPU 和内存占用跑挂了会自动拉起。Nginx 层负责 HTTPS 终结和静态资源托管接口路径统一转发到 Node 服务。这个组合对中小型项目来说非常稳定几乎没有遇到过需要上容器编排的复杂度。5. 这套方案适合谁以及落地前需要想清楚的事如果你正在评估要不要参考 t3code 这套思路我最后分享一下实际运用中的感受。这套方案最舒服的适用场景是团队成员数量不多三五个人以内、前后端边界清晰、需求迭代节奏快的项目。因为它舍弃了一些大型框架的通用性换来了极高的协作确定性和开发效率。成员不纠结技术选型、不反复讨论代码结构可以直接进入业务逻辑。但如果你要做一个超大型项目多团队并行开发、微服务拆分是硬需求的时候这套轻量级约定就需要做额外扩展了比如增加独立的网关层、更细粒度的权限中心、领域事件的支持。t3code 的定位是快、稳、省不是包治百病。选择任何技术方案本质上是选择一套协作方式我对这套方案的理解是它把一个多端项目最耗精力的部分——沟通和约定——用代码结构和类型约束解决了让团队把精力聚焦在真正有业务价值的功能上。团队落地的时候还有一个小建议不要一上来就铺开全部模块先选一个核心业务链路比如用户端浏览商品到支付、运营端上架商品到发货完整走通验证这套约定在实际协作中的流畅度再逐步把其他业务模块迁移进来。这样团队对这套规范的接受度会高很多推进阻力也小很多。 
长河君 · 2026/10/26 8:23:35 · 阅读 1.2k t3code架构解析：原生小程序与统一服务层如何重塑多端协作
关于 t3code一个由原生小程序驱动的一体化业务交付方案我最初接触 t3code 这个代号是在一个做本地生活服务的客户项目里。当时团队刚接手一个既有 App 端、又有 Web 管理后台和商家小程序的混合项目代码仓库散落接口风格不统一前端同学和后端同学各维护一套字段映射联调时经常因为字段名大小写问题来回扯皮。t3code 是另一个团队留下的内部代号起初我以为是某个自动化代码生成工具的版本号翻完文档和技术栈清单后才发现它本质上是一套围绕“原生小程序 统一服务层”的轻量级全栈交付方案——用微信小程序原生语法做用户端载体用 Node.js 的通用中间层做业务聚合再把后台管理端收敛到一个基础框架里复用。这套东西不是那种需要你重学一套新语言、新框架的“全家桶”反倒是把大家已经熟悉的技术栈用一套约定串了起来通过类型定义、接口约定和目录规范来约束协作方式。t3code 能解决的问题说白了就是中小型业务中最常见的三类痛一是小程序原生开发在多人协作时的代码组织混乱Page 里挂一堆业务请求公共逻辑和页面逻辑混在一起二是前后端接口数据结构的语义断层后端返回created_at前端写成createTime再经过一层数据清洗到最后渲染层都不知道哪个字段才是对的三是多端项目用户小程序、商家端、管理后台重复建设登录态、请求封装、权限路由、错误提示这些基础模块每个端都写一遍样式风格还不统一。t3code 通过把整套技术栈固化成模板和约定让新成员入职后能直接进入业务开发而不是先花两周搞懂各端各自的封装方式。如果你手头正在做一个需要小程序端 管理后台 API 服务三个部分同时推进的小项目或者团队中已经有了一套独立小程序代码库却苦于没有好的方式去规范多端协作那 t3code 这套思路很值得你花点时间看完。接下来我会从项目结构设计、核心模块拆解、服务端接口约定、实际部署维护这几个角度完整复盘这套方案的关键细节和落地经验。1. 整体设计与架构思路为什么是原生小程序而不是跨端框架先回到方案选择的最前端。很多项目一开始会纠结小程序要不要用跨端框架来写比如 uni-app、Taro 这类。t3code 的设计选择是坚持用微信小程序原生语法做用户端和商家端Web 管理后台保留传统模板加 AJAX 的方式服务端用 Node.js。乍一看这个选型有点保守但实际落地跑完几个版本后我反而越发认可这个判断——对于依赖微信生态能力的项目原生语法能少很多麻烦而对团队协作而言固定一套目录结构和公共模块约定的价值要远大于框架本身给的那点语法糖。1.1 原生小程序的真实收益接口体验与迭代节奏不受框架约束跨端框架最大的诱惑是一套代码多端复用。但这个收益在小程序场景里经常大打折扣因为各个小程序平台的基础库能力、隐私合规要求、支付逻辑都不一样。你为了兼容多端引入的抽象层往往在实际开发中变成了条件编译碎片的堆砌地。t3code 采用原生语法第一个好处就是对微信基础库的新特性可以第一时间直接用不用等框架层适配。比如最新的手机号快速验证组件、交易组件、订阅消息的模板升级这些如果是靠第三方框架封装通常会慢半拍而原生语法能跟官方的迭代节奏保持一致。第二个好处是调试成本低。原生小程序开发者工具对原生代码的报错、断点、性能面板支持最直接不需要额外关心框架的编译产物和 sourcemap 映射问题。我在实际项目里遇到过 Taro 项目报错堆栈指不到原始代码的情况排查成本会明显增加而原生代码基本不会出这种问题。当然坚持原生写法的前提是不要重复造轮子。t3code 里抽了一套公共的core目录把请求封装、登录态、工具函数、自定义导航栏这些高频模块全部沉淀下来各端通过相对路径引用同一套代码。业务页面里只写页面逻辑跨端的公共能力全部走core。这样做既能享受原生语法的直接性又不至于每个页面都重复一堆初始化代码。1.2 统一服务层设计请求聚合与数据结构固定t3code 的服务端设计的核心是所有端面对的不是散落的业务表而是一个聚合后的业务服务层。用户端小程序、商家端小程序、Web 管理后台统一通过这个业务服务层拿数据。这个服务层在 Node.js 里以路由模块加服务模块的方式组织每个业务领域的服务模块对外暴露固定方法路由负责参数校验和身份校验服务模块负责业务规则和存储层对接。这样设计的好处在于数据结构是稳定的。比如订单详情无论在哪个端请求返回的都是同一套字段结构不存在用户端拿到的订单状态和管理后台拿到的状态含义不一致的情况。数据结构的定义集中在一个types文件里前端各端直接引用这份类型定义生成对应的数据结构映射。如果后端需要调整字段改动类型定义后各端都会在同一次联调中感知到而不是靠群里吼一声然后各改各的。这类统一数据结构在 t3code 里实际上是全局约束。所有服务接口的返回格式固定为三段式code、message、data。code是业务状态码不是 HTTP 状态码message是给前端提示用的文本data是真正的业务数据。这样设计下前端的统一请求层只需要处理这一种结构网络异常、业务失败、正常返回的情况在入口处就分流清楚不会出现页面里到处写各种状态判断的散乱局面。表面上看这只是一套规约但真正落地后前后端联调效率确实提升明显——因为类型定义文件和接口文档是在同一个仓库里维护的代码即文档文档即类型任何不一致在编译阶段就会被拦截而不是等运行时报错才暴露。1.3 多端协作的目录规范一方定义多方复用t3code 的代码仓库采用单仓库结构里面按端划分了三个主目录miniprogram-user、miniprogram-merchant、admin-web以及一个共享的service-server。每个端目录下面又固定划分为pages、components、core、utils、styles这五个子目录。这套划分解决了我在多个项目中反复遇到的共性问题组件不知道该放哪个目录、页面和通用逻辑的界限模糊、样式变量散落各处难以统一维护。共享层专门抽出了shared-types目录里面放接口类型定义和枚举常量前后端所有引用都从这一份代码里导入。实际效果是只要类型定义统一前端写页面时自带的智能提示就能告诉你能用哪些字段后端也能通过校验规则确保不会把范围外的状态值写入存储。遇到要修改接口字段的场景改动集中在类型定义一处所有引用方都会在编译时报错提示这比任何文档流程都来得可靠。2. 核心技术拆解目录、类型与请求层是如何协同工作的不少团队不是没有技术规范而是规范散落在各种文档里落实不到实际代码上。t3code 的做法是把规范固化到模板和工具链中。这一节我拆解三个具体的技术环节核心目录的组织逻辑、类型定义如何联动前后端、统一请求层如何降低调用成本。2.1 核心目录结构与职责边界t3code 的小程序端目录结构大体如下miniprogram-user/ ├── pages/ │ ├── index/ │ ├── order/ │ └── profile/ ├── components/ │ ├── custom-nav/ │ ├── order-card/ │ └── empty-state/ ├── core/ │ ├── request.js │ ├── auth.js │ ├── config.js │ └── constants.js ├── utils/ │ ├── format.js │ ├── validator.js │ └── share.js └── styles/ ├── variables.wxss ├── mixins.wxss └── common.wxsspages目录严格只放页面级代码每个页面一个文件夹里面包含.wxml、.wxss、.js、.json四个文件。页面内允许有少量该页面特有的展示逻辑但所有涉及数据请求的代码一律调用core/request.js暴露的方法不允许在Page({})里裸写wx.request。components目录放的是跨页面复用的业务组件比如订单卡片、空状态、自定义导航栏。组件的样式统一引用styles下的变量和混入保证视觉一致性。core目录是重点它封装了所有端共用的底层能力请求实例、登录流程、全局配置、常量枚举。utils目录放纯函数工具比如日期格式化、手机号脱敏、校验规则不依赖任何页面上下文。styles目录只有样式变量和混入不承载业务逻辑。这套边界一旦定了团队协作时基本不用讨论某个文件该放哪里。新成员看着目录结构就知道职责归属代码评审的时候也只需要盯着核心业务逻辑不用反复纠正基础模块的放置位置。2.2 类型定义如何成为前后端的连接器t3code 的类型定义文件不是泛泛地写一份接口文档而是切实参与到代码生成和编译检查中的。下面以一个典型的商品对象为例// shared-types/product.ts export interface Product { id: string; title: string; coverUrl: string; price: number; originalPrice?: number; sales: number; stock: number; status: on | off | deleted; categoryId: string; createdAt: string; updatedAt: string; } export interface ProductListParams { page: number; pageSize: number; categoryId?: string; keyword?: string; sortBy?: default | sales | price_asc | price_desc; } export interface ProductListResult { list: Product[]; total: number; hasMore: boolean; }小程序端虽然不能直接运行 TypeScript但借助开发者工具自带的 TypeScript 编译能力同样可以在代码中引入类型定义。这样在小程序端写页面时编辑器能准确提示每个字段的类型和可选性拼错字段名、把数字类型当成字符串拼接这类问题在一开始就能被工具发现。服务端的路由处理直接引用同一份类型定义参数校验通过后返回的数据必须符合ProductListResult的结构。我实际落地时还加了一层简单的运行时校验在非生产环境打印结构不符的警告方便第一时间发现前后端定义不同步的问题。这套方案比手工维护接口文档好用得多因为业务改字段时你只需要改动类型定义然后所有引用方会通过编译提示告诉你还有哪些地方没有同步改到位。2.3 统一请求层的设计与实现小程序端的网络层如果没有统一封装最常见的后果是每个页面的onLoad里堆着一堆wx.request回调错误处理方式五花八门。t3code 将请求层收敛到core/request.js核心实现思路如下// core/request.js const request (url, options {}) { return new Promise((resolve, reject) { wx.request({ url: getBaseUrl() url, method: options.method || GET, data: options.data || {}, header: buildHeader(options.auth ! false), success(res) { const { code, message, data } res.data || {}; if (code 0) { resolve(data); } else { handleBusinessError(code, message); reject({ code, message }); } }, fail(err) { handleNetworkError(err); reject(err); }, }); }); };所有接口返回统一为{ code, message, data }结构code为 0 表示成功非 0 根据业务错误码做提示或跳转登录。页面调用时不用关心loading和错误弹窗因为通用逻辑都收口在处理函数里。需要拉取最新数据做下拉刷新时直接重新调用请求方法即可不用在页面里维护一堆请求状态。这个封装给团队带来的最大收益是排错简单。线上出了问题看网络请求面板能直接看到某个接口产生了一个非 0 的业务错误码而且每个页面展示的错误是一致的不会出现一个人写toast、一个人写modal的情况。登录失效的处理也统一了当请求层识别到未授权错误时会自动清理本地登录态并跳转到登录页每个页面无需各自处理。3. 从零搭建到首版交付完整实操过程记录做技术方案分享最怕没有实操参考。这节我以一个虚拟的业务场景为例完整走一遍 t3code 体系下从初始化项目到首版交付的过程假设要做一个社区生鲜团购的小程序包括用户端浏览商品、下单支付和运营端商品管理、订单处理。3.1 项目初始化与依赖安装使用 t3code 模板初始化项目首先是拉取仓库模板和安装依赖git clone gityour-git-host:t3code/t3code-starter.git fresh-project cd fresh-project npm install模板自带以下基础配置// project.config.json 关键项 { miniprogramRoot: miniprogram-user/, cloudfunctionRoot: service-server/, setting: { es6: true, minified: true, urlCheck: true } }miniprogramRoot指向用户端小程序目录cloudfunctionRoot指向服务端目录。如果商家端要单独跑用微信开发者工具导入miniprogram-merchant目录即可。管理后台是纯 Web 项目直接npm run dev启动。整个模板启动后三端工程会共享同一份类型定义和服务端契约新需求的接口设计在类型定义里完成然后三端并行开发。3.2 商品模块的类型定义与服务端实现在设计商品列表这个业务时先约定类型定义。商品数据在用户端要展示标题、封面、价格、销量在运营端还需要管理库存、分类和上下架状态。因此商品类型需要同时覆盖两端诉求但可以通过不同接口返回不同字段的子集。服务端的实现是路由加服务分离// service-server/routes/product.ts router.get(/list, validate(ProductListParams), async (ctx) { const params ctx.validatedData; const result await productService.getList(params); ctx.body success(result); }); router.post(/upsert, checkPermission(product:write), async (ctx) { const data ctx.request.body; await productService.upsert(data); ctx.body success(null); });validate中间件负责校验参数checkPermission负责权限控制真正业务逻辑放在productService.getList和productService.upsert里。参数校验通过后才进入服务层避免把一堆参数判断塞进业务逻辑里。productService.getList内部处理了列表查询和总数统计。我在这类场景里会额外注意 SQL 的查询效率问题尤其是分页场景下避免先查全量再切页的做法。列表接口返回结构里有一个hasMore字段小程序端通过这个字段判断是否还有下一页从而决定是否触发上拉加载避免重复请求无数据的分页。3.3 小程序端的页面实现与状态管理用户端商品列表页的实现要点是页面只负责渲染和交互反馈数据请求走core/request数据状态在onLoad和下拉刷新、上拉加载中维护。// miniprogram-user/pages/index/index.js const { getProductList } require(../../core/api); Page({ data: { list: [], page: 1, hasMore: true, loading: false, }, async onLoad() { await this.loadList(true); }, async loadList(reset false) { if (this.data.loading) return; if (reset) { this.setData({ page: 1, hasMore: true, list: [] }); } if (!this.data.hasMore) return; this.setData({ loading: true }); try { const result await getProductList({ page: this.data.page, pageSize: 10, }); this.setData({ list: reset ? result.list : this.data.list.concat(result.list), hasMore: result.hasMore, page: this.data.page 1, }); } finally { this.setData({ loading: false }); } }, onPullDownRefresh() { this.loadList(true).finally(() wx.stopPullDownRefresh()); }, onReachBottom() { this.loadList(); }, });这段代码展示了一个典型的分页列表逻辑首次加载、下拉刷新、上拉加载三者共用同一个方法通过reset参数区分场景。这里有个比较关键的细节页面上展示的列表数据一定来自统一接口返回的list字段不能各自在页面里改data不然刷新后会看到旧数据残留在一两秒内的情况。凡是列表页都建议维护list、page、hasMore、loading这四个状态字段结构统一后页面写起来会非常流畅。3.4 管理后台的模块复用与权限控制管理后台不用单独引入前端框架t3code 模板默认采用 Vue 3 加 Element Plus但业务页面的写法统一按模块化方式组织。每个业务模块一个目录包含列表页、编辑页、API 定义和类型引用。权限控制不是在每个路由里散落判断而是集中到路由配置的meta字段中由全局路由守卫统一检查。实际体验下来管理后台维护最频繁的地方是权限点的增减集中在路由配置里调整比在组件里改判断要省力得多。4. 常见问题与运维维护实录再严密的模板落到真实线上环境也会遇到各种预想不到的问题。这里整理我在实际项目中碰到的几类典型问题基本都是 t3code 这种多端模式下特有的挑战。4.1 小程序端类型不同步导致的字段缺失小程序端引用共享类型的一个麻烦是类型定义改了但小程序端没有重新编译导致接口返回的新字段在小程序端获取不到。这个问题最容易出现在新增功能迭代时后端提前返回了新字段前端还没发布新版本。最直接的规避方案是前端在代码里对关键字段做兜底处理比如商品封面加一个默认图价格显示加一个0.00的降级文案这样即使字段缺失展示层也不会显得异常。另外一个更有效的手段是把类型检查接入小程序的 CI 流程。在提交代码前跑一次tsc --noEmit能提前暴露类型不一致的问题。微信小程序开发者工具的构建默认不检查类型所以一定要在 CI 脚本里显式加这一步。我在实际项目中就是因为在 CI 里加了类型检查才堵住了好几次后端改了字段、前端没同步改完的情况。4.2 分页接口的重复请求问题分页列表最常见的线上 bug 是重复请求用户快速上拉时同一页数据被请求了两次。根因通常是onReachBottom触发的频率比setData更新loading状态更快。在低端手机上这种情况更容易复现。解决方案就是我在前面代码中展示的if (this.data.loading) return;这个前置判定。凡是列表页建议都把这个检查放在请求方法第一行这是个成本极低但收益非常明显的防护。另一个分页相关的坑是下拉刷新后页码重置的时机。如果先重置page再发起请求页面会短暂显示空列表如果请求成功后再重置旧数据又会残留一段时间。所以我习惯的做法是进入loadList(true)时同步清空列表和重置页码用loading状态配合展示一个顶部的加载提示体验上是自然的。4.3 登录态失效后的联动跳转多端项目中登录态管理一直是重点。t3code 的做法是登录凭证集中存放在core/auth.js中统一处理读取、写入、清除。小程序端的wx.login换取 openid 和会话凭证的过程也被封装在core/auth.js里页面不感知具体实现。线上真正需要关注的问题是登录态失效时多个接口同时报错导致多个页面同时弹出重新登录的提示。t3code 的解决方案是在请求层维护一个isRedirecting标志第一个识别到登录失效的请求负责跳转登录页其余请求仅静默失败避免跳转重复触发。这个标志在登录成功后重置整个联动过程对用户无感实际体验下来比每个页面各自处理要顺畅得多。4.4 服务端跨域与会话配置问题Web 管理后台调用服务端的跨域配置看似简单但实际坑不少。t3code 的服务端用koa/cors处理跨域需要注意两点一是credentials要设置为true否则携带 Cookie 的请求会失败二是允许的来源不要用*必须明确指定管理后台的域名。如果要用 Nginx 反向代理同域部署就不需要配置跨域但这种情况下务必确认路径转发规则无误。服务端和各端实际部署时我用的是 PM2 加 Nginx。服务端应用本身用 PM2 守护进程管理面板看 CPU 和内存占用跑挂了会自动拉起。Nginx 层负责 HTTPS 终结和静态资源托管接口路径统一转发到 Node 服务。这个组合对中小型项目来说非常稳定几乎没有遇到过需要上容器编排的复杂度。5. 这套方案适合谁以及落地前需要想清楚的事如果你正在评估要不要参考 t3code 这套思路我最后分享一下实际运用中的感受。这套方案最舒服的适用场景是团队成员数量不多三五个人以内、前后端边界清晰、需求迭代节奏快的项目。因为它舍弃了一些大型框架的通用性换来了极高的协作确定性和开发效率。成员不纠结技术选型、不反复讨论代码结构可以直接进入业务逻辑。但如果你要做一个超大型项目多团队并行开发、微服务拆分是硬需求的时候这套轻量级约定就需要做额外扩展了比如增加独立的网关层、更细粒度的权限中心、领域事件的支持。t3code 的定位是快、稳、省不是包治百病。选择任何技术方案本质上是选择一套协作方式我对这套方案的理解是它把一个多端项目最耗精力的部分——沟通和约定——用代码结构和类型约束解决了让团队把精力聚焦在真正有业务价值的功能上。团队落地的时候还有一个小建议不要一上来就铺开全部模块先选一个核心业务链路比如用户端浏览商品到支付、运营端上架商品到发货完整走通验证这套约定在实际协作中的流畅度再逐步把其他业务模块迁移进来。这样团队对这套规范的接受度会高很多推进阻力也小很多。