当一个小程序从单一的金价查询逐渐加入计分板、倒数日、汇率、番茄钟和健康打卡时真正困难的不是再写一个页面而是让第十七个工具仍像第一个一样容易接入、独立运行和安全发布。项目预览一、问题不是“页面变多了”「零碎百宝箱」最初是一个金价排行榜后来逐步容纳了 17 个工具。它们的运行形态并不一致瞬间听力、聚会决定器、单位换算等工具可以纯前端运行台球、倒数日等工具要求离线可用同时希望换机后恢复历史金价、油价和汇率依赖定时更新的服务端数据麻将计分以联机房间为主服务端才是事实来源喝水提醒还需要处理微信一次性订阅消息和后台调度。如果所有功能都堆在一个目录、共享任意状态并请求任意接口新功能越多主包体积、命名冲突和回归范围都会同步增长。这个项目的解法是先规定边界再允许工具在边界内自由选择实现。二、总体结构一个壳多种工具形态微信小程序主包首页工具注册表core 基础设施design 设计系统行情类分包计分类分包纯前端分包记录类分包Nginx 路径网关统一认证服务专属 Flask 服务通用 records 服务实例MySQL客户端主包只保留首页和公共能力。每个工具位于packages/tool-slug/并在pages.json中注册为分包。首页不硬编码卡片而由config/tools.js的注册表驱动名称、分类、图标、主题、入口和启用状态都在一处声明。这种结构带来两个直接收益用户只在进入某个工具时下载对应分包主包不会随着工具数量线性膨胀。新工具的接入点是显式的建分包、注册页面、登记工具不会偷偷依赖另一个工具的内部代码。项目进一步规定分包之间禁止互相import只能依赖主包的core/和design/。这条规则看似严格却能防止“倒数日复用了健康打卡的一段代码后来两个分包必须同时发布”的隐形耦合。三、用工厂函数统一网络边界每个服务在网关下拥有独立前缀。分包只需要声明自己的服务名import{createRequest}from../../core/request;constrequestcreateRequest(gold-price);constresawaitrequest({url:brands,method:GET});公共请求层完成三件事将相对路径拼为/service/api/v1/path从本地读取 JWT 并注入Authorization: Bearer ...收到 401 后静默登录并将原请求重放一次。微信登录本身也做了“单飞”控制。多个并发请求同时发现 token 过期时共享同一个loginPromise而不是同时调用多次wx.loginletloginPromisenull;exportfunctionwxLogin(){if(loginPromise)returnloginPromise;loginPromisedoLogin().finally((){loginPromisenull;});returnloginPromise;}服务端由认证服务用微信临时 code 换取 openid再签发只包含openid和过期时间的 HS256 JWT。所有业务服务共享签名密钥因此可以本地验签不必让每个请求再次穿过认证服务。这是一种适合小型微服务系统的取舍认证入口集中鉴权执行分散。它减少了一次内部网络调用但也意味着密钥轮换必须让所有服务同步更新。四、本地优先不是“有缓存就行”计分、倒数日和健康记录发生在球桌、牌桌或日常打卡中。网络短暂不可用不应该阻塞一次记分所以项目把本地存储定义为主存储云端负责异步备份。所有分包通过命名空间存储避免 key 冲突conststoragecreateStorage(billiards);storage.set(settings,settings);// 实际写入 keybilliards:settings更通用的记录同步由createRecordSync(service)提供。一次同步分为三个阶段records 服务待删队列本地记录records 服务待删队列本地记录1. 补交历史删除仅保留失败项2. 拉取云端记录按 clientKey 合并updatedAt 新者胜3. 分批推送未同步记录返回幂等保存结果这里最容易漏掉的是“删除”。如果用户离线删除一条记录只从本地数组移除下一次拉取时云端旧数据会再次出现。因此删除动作会先写入pendingDeletes云端确认删除后才移出队列。若用户用同一个clientKey重建记录则撤销对应删除意图。服务端按(openid, client_key)幂等 upsert。客户端主导身份服务端负责备份与跨设备恢复双方用updated_at做简单的最后写入者胜出。它并不试图解决协作文档级别的合并冲突但足以覆盖个人记录工具的真实场景。五、后端为什么同时存在专属服务和通用服务给每个工具复制一套 Flask CRUD 很快会产生大量相似代码反过来把所有业务塞进一个服务又会让金价爬虫、麻将房间和喝水提醒互相影响。项目采用两种后端形态专属服务金价、油价、汇率、台球、麻将等具有独特数据模型或调度逻辑的工具通用 records 服务球拍计分、棋牌计分、倒数日、健康记录和自由记分复用同一份代码但以不同容器、数据库名和服务名运行。通用服务复用实现不共享数据。专属服务保留业务表达力不被“万能记录表”限制。这比“一工具一套复制代码”或“所有工具共用一张表”都更平衡。Docker Compose 负责启动 MySQL 和各业务容器Nginx 按路径转发/auth/ - auth:5000 /gold-price/ - gold-price:5000 /mahjong/ - mahjong:5000 /health-log/ - health-log:5000数据库容器还针对小内存服务器关闭了 performance schema并缩小 InnoDB buffer pool。架构设计不仅要画出服务边界也要尊重实际机器的资源上限。六、设计系统只统一外壳工具箱容易走向两个极端要么每个页面完全不同像跳进了另一个应用要么为了统一而抹掉工具个性。项目把颜色、间距、圆角等基础变量集中在design/tokens.scss通用页面头、返回按钮、图标和工具卡使用tb-前缀组件。工具内部仍可以保留自己的交互语言例如金价品牌卡的行情感、听力测试的游戏感、横屏计分板的大字号操作感。统一的是导航、反馈和基础尺度不是所有页面必须长成同一张卡片。七、新工具如何选择落点接入前先判断数据归属而不是先复制最近的目录工具特征推荐形态参考实现无持久数据、无需联网纯前端分包瞬间听力、单位换算个人记录、离线必须可用createRecordSync records 服务倒数日、健康记录业务模型复杂、仍以本地为主专属 store 专属备份 API台球计分多人共享实时状态服务端主存 版本控制麻将计分周期采集公共行情专属服务 调度器 缓存展示金价、油价、汇率这个判断比技术选型本身更重要。离线个人记录和多人联机房间虽然都叫“同步”一致性目标完全不同不应被同一套抽象强行覆盖。八、这套架构的边界当前方案适合中小规模工具箱但仍有明确的演进点JWT 使用共享对称密钥服务数量继续增长时可考虑非对称签名和密钥轮换最后写入者胜出适合个人记录不适合多人同时编辑APScheduler 随应用进程运行便于部署多进程或多副本后应拆为独立 worker各服务独立容器提高隔离性也增加部署和可观测性成本需要统一日志与指标。好的架构不是一开始就上最复杂的组件而是让每种复杂度只出现在真正需要它的工具里。这个项目最值得复用的并非某个框架而是“主包提供稳定能力分包表达业务差异简单工具保持简单复杂工具拥有自己的边界”这一原则。
