af1de30 推上远程分支的那一刻,“生灵集”这门课的作业就算正式交了。
我关掉答辩用的幻灯片,在宿舍椅子上伸了个懒腰,又鬼使神差地把仓库重新点开。
讲台上做汇报的时候,人很容易被气氛带着走。对着大屏幕上挑出来的几张漂亮截图,我们顺着立项时的构想,聊物种图鉴、社区互动、问答互助、智能推荐,说得好像手里已经攥着一款羽翼丰满的应用。可回到宿舍敲下命令把目录树展开,那股热闹劲儿就慢慢沉下来了。剥掉汇报时的修辞,眼前这个工程长得很朴素:一套对外演示的静态网页,一个以子模块挂进来的 Android 客户端,还有一个 Node.js 搭的后端服务。
趁刚结课手还热,我想撇开那些宏大的设想,就对着仓库里摸得到的文件和调试时踩过的坑,把这段工程练习好好记一笔。
先把仓库拆开看
顺着根目录往下翻,父仓库扮演的角色更像是一个总览归档柜:里头放着项目整体说明、设计文档、一套由基础 HTML、CSS 与 JavaScript 写成的静态展示页,以及一沓 Android 和网页端的界面截图。真正的客户端代码是用 Jetpack Compose 写的,通过 Git submodule 指向了另一处独立仓库;而服务端代码则安放在同级的 shenglingji-backend 目录里。
当初用子模块,是图移动端和后端能分开提交,聚在一起也省心。直到有一次在实验室换了台电脑重新拉取仓库,点进客户端目录一看空空如也,我才意识到这种结构给后来者留了一道隐形的门槛:如果只执行了最普通的克隆命令,本地拿到的其实只是一个指向特定提交的空壳指针,既看不到客户端完整的演进历史,想追查某个具体页面的实现细节时,还得额外跑一遍子模块初始化与更新命令。(那天旁边的同学看我对着空文件夹发呆,还以为我把代码删了。)
根目录那套静态展示页,当初写它是为了让老师和访客不用安装安装包,点开浏览器就能第一时间看到“生灵集”的视觉排版和页面长相。它像一扇擦得很干净的橱窗,视觉预览的活干得不错;可橱窗里摆的按钮模型,终归和真正接通了后端数据库的客户端逻辑是两码事。把“展示给别人看的静态页面”和“真正在手机里跑通的业务代码”区分清楚,是我们整理这个仓库时迈出的第一步。
后端真正做了什么
切进 shenglingji-backend 翻 package.json,里头规规矩矩地列着 Express、Sequelize、MySQL、JWT 和 Multer 等一串熟悉的名字。整个服务端的源码按控制器、模型、中间件和路由做了最经典的分层:用户注册与登录、个人资料维护、帖子发布以及评论交互的入口各归其位;认证中间件专门负责从请求头里提取并核验 Bearer Token;上传中间件则接管了动植物照片等媒体文件的落盘处理。
平心而论,这套拆法谈不上什么高深的架构设计,但放在一个校园项目的体量里已经足够好用。每一条从手机端发出的网络请求都有迹可循,出了毛病,顺着路由表就能迅速按住对应的代码文件。
翻看后端提交记录时,有一条故障修复让我印象格外深刻,当时在实验室调到那一步,真是惊出一身冷汗。
那次改动是为了给帖子加上更丰富的多媒体展示,我们在帖子模型里一口气新增了 coverImage、mediaUrl 和 mediaType 三个字段。代码改完在本地一跑,业务接口里的查询语句已经兴冲冲地去读这三个新字段了,可底下连着的旧版 MySQL 数据库表结构还没来得及同步加上对应的列。手机端一点击进入帖子详情页,后端接口瞬间因为 SQL 报“未知列”直接抛了 500,原本好端端的页面一下子白了屏。
我们赶紧在同一次修复提交里补齐了数据库表结构的更新脚本。这个看似不起眼的报错给我敲了一记很响的警钟:只要工程里涉及数据库存储,ORM 模型文件、数据库迁移脚本与部署执行步骤就像连体婴一样,必须成双成对地一起提交。如果只图省事改了代码里的模型定义,却忘了同步演进数据库的真实表结构,换一台机器或者重新部署时,第一条真实请求打过来就会立刻露馅。
也是从那个报错开始,我们把后端 README 里的接口说明当成一份认真的前后端契约来维护。注册登录返回什么样的用户信息结构与令牌格式,修改资料要带什么认证头,帖子详情怎么兼容图文与视频两种媒体字段,都老老实实列在里面。越是两三个人合作的小项目,越需要把这些约定就近写在能跟着代码一块更新的地方,省得隔上两个星期再打开工程,连自己都要对着接口名盲猜参数。
设计文档和代码之间的距离
仓库里那份 design.md 写得很厚实,是刚立项时我们熬了几个晚上攒出来的蓝图:从启动页、登录、首页信息流,一直到动植物科普图鉴与社区互动模块,每一章都规划得头头是道;一旁的 README 里也写满了问答互助、用户关注与多级评论等构想。
刚开启一个新项目时,人总恨不得把脑子里所有觉得酷的点子全塞进设计文档,那份心气本身挺珍贵的。只是到了学期末回头清点战果,总得老老实实面对理想蓝图与实际代码之间的落差。
整理仓库时,我在草稿纸上画了三列,把文档里写过的功能挨个放进对应的篮子里:第一列是已经在客户端与后端跑通闭环的;第二列是后端接口或数据库表搭好了架子、但前端界面还没来得及接上的;第三列则是自始至终只停留在纸面上的愿望。
把这三笔账算清楚之后,心里反而一下子敞亮了。数据表的名字出现在了初始化 SQL 脚本里,代表着我们当时确实认真推敲过这部分的数据结构;而把那些没写完的模块坦坦荡荡地标成“待实现”,也一点不会折损那些已经跑通的代码的分量。不拿设计草图去冒充完工的功能,也不因为还有未竟的空白就轻视自己写下的每一行逻辑,这大概就是复盘一个校园作品最舒服的姿态。
留给下一个项目的几条习惯
把“生灵集”的前后脉络彻底梳理了一遍之后,有几条关于如何打理工程的朴素习惯,在心里慢慢定了型。
无论项目大小,动工之初最要紧的是先把那条能够独立跑通的最小路径保存下来:客户端、后端服务与底层数据库都备好各自清晰的启动说明,锁死依赖版本;倘若像这次一样把客户端拆成了 Git 子模块,就一定要在父仓库 README 的显眼位置写清子模块的初始化命令与当时对齐的提交哈希,别让后来者在第一步就对着空文件夹犯难。
一旦项目涉及到数据库结构,就把表结构变更当成代码提交里不可分割的一环。模型新增字段,顺手附上可执行的迁移脚本和回滚方法,让代码里的模型定义与数据库里的物理表结构永远保持同步。而在所有正常的主流程之外,更得早早为各种日常的小意外留出余地:认证令牌突然过期、旧数据缺了某个媒体字段、图片地址偶尔加载失败,这些在真实使用里再普通不过。扎实写好的错误响应码、清晰的日志打印与体面的前端占位提示,往往比花哨的动效更能让一个应用显得踏实可靠。
“生灵集”现在就静静停在 af1de30 那次提交上:里头有 Jetpack Compose 写出的界面组件,有 Express 分发的路由,有修补过 500 报错的数据库脚本,也有几处没来得及填上的设计留白。对于一个在大学校园里摸索出来的作品而言,这样一份优缺点都摊开的真实底片,就已经是最好的留念了。
往后哪天闲下来再打开它,我大概会先照着 README 把本地服务拉起来,再决定要不要为它补上那枚还没写完的按钮。