从单文件脚本到全栈应用：个人项目迭代实战复盘

我的代码仓库里躺着一个名字很随意的项目liubingchen2-2。拼音加数字看起来就像谁在键盘上随手敲出来的ID。说实话我现在看着这个名字也有点想笑但就是这个随手敲出来的名字让我从只会写单文件脚本的小白一步一步走到了能独立设计和维护一套小型全栈应用的状态。这篇文章想聊聊这个代号背后一个个人项目从命名、规划、迭代到最终成为作品集的完整过程也算是一次诚实的复盘。如果你也手头有一个自己练手的项目或者正准备从零开始一个个人主页、工具站、后台管理系统这篇文章里写的思路和踩过的坑应该能帮你少走一些弯路。1. 为什么破名字也能撑起一个项目命名与定位先聊聊这个名字本身。很多人会在意项目名不够酷、不够响亮担心拿不出手。但我的经验是个人项目的名字越随意越说明你在开始阶段更关注做出来而不是秀出去。liubingchen是我的名字拼音2-2是我自己定的迭代编号2 代表第二个练手项目第二个 2 代表这是它的第二轮重构。1.1 从拼音加编号说起仓库命名的实用主义如果你准备把项目放到代码托管平台上我强烈建议你接受实用主义命名。不管你是用 GitHub、Gitee 还是自建的 GitLab仓库名最重要的是三点唯一、好找、不会引发歧义。我当时选择liubingchen2-2的理由很朴素第一liubingchen能让人一眼看出归属第二2-2让我自己在本地和线上仓库之间切换时不会和2-1搞混。这种做法在小圈子里并不少见很多独立开发者会用名字拼音 序号来表示某个阶段的练习成果。真正有价值的不是名字本身而是这个名字背后的版本意识。当你开始用编号、日期、语义化版本来标识项目时你就已经和桌面新建文件夹1、文件夹2那种状态拉开了距离。1.2 项目定位不追求大而全用任务清单倒推功能很多个人项目死在定位太大上。比如一开始就想做一个全功能的内容管理平台、一个社区系统、一个电商中台于是去研究微服务、消息队列、分布式缓存最后代码写了一堆功能全没落地。第二个项目启动时我给自己定了一条规矩只做一件具体的事并把这件事拆成可以勾选的任务清单。liubingchen2-2当时的定位是一个带登录、数据录入和简单报表展示的个人工具站。没有复杂权限没有多人协作没有消息推送。就这三个功能我拆出了十几条小任务每一项都是点击某个按钮看到某个结果这种可以验证的颗粒度。提示个人项目最好的状态是麻雀虽小五脏俱全——技术栈完整业务流程闭环但功能数量控制在个位数。这样你才有精力把每段代码写干净、把每个交互想清楚。当你把定位缩小之后后续所有决策都会变得容易数据库表少接口少页面少出错的地方自然也少。2. 从零搭建时的三个关键决定技术选型与目录设计一个项目的骨架往往在最初的三天里就定下来了。技术栈怎么选、目录怎么分、环境怎么配这三件事直接决定了你后续两个月是舒服还是痛苦。liubingchen2-2的技术栈是 Vue 3 Vite Express SQLite当时这么选不是因为它最热门而是因为它最不容易让我中途放弃。2.1 技术栈怎么选学过的、常用的、能维护的好记性不如烂笔头但烂笔头不如用过的框架。前端框架我选 Vue 3是因为那段时间我天天用 Vue组合式 API 写起来顺手生态也成熟。如果当时让我去碰一个完全陌生的新框架大概率会在组件通信或者状态管理上卡两天热情直接凉一半。后端我选了 Express它是 Node.js 生态里最基础、资料最多的框架中间件逻辑清晰非常适合一个人维护的小服务。SQLite 作为数据库也是刻意的选择——它不需要单独安装数据库服务一个文件就是一个库对本地跑、对后期打包部署都极其友好。我画过一张简单的技术选型对比当时是真写在笔记本上的大致是这个思路考虑项选择理由前端框架Vue 3熟悉度高文档友好适合中小型项目构建工具Vite启动快热更新稳配置少后端框架Express门槛低中间件机制清晰数据库SQLite零配置文件适合单机个人项目部署方式Docker环境隔离换机器不慌这套组合谈不上惊艳但它有一个核心优势我一个人能在三天内把 Hello World 跑通并且能在三个月后看懂自己写过的东西。学习成本、维护成本和试错成本全部控制在合理范围内这才是一个人在有限精力下最该看重的事。2.2 目录结构给半年后的自己留条活路目录结构不复杂但我吃了不少亏之后总结出了一条经验不要把业务代码和配置文件混在一起也不要用a.jsb.js这种文件名。下面是liubingchen2-2第二轮重构后大致采用的目录布局liubingchen2-2 ├── client # 前端代码 │ ├── src │ │ ├── api # 所有接口请求封装 │ │ ├── assets # 静态资源 │ │ ├── components # 公共组件 │ │ ├── router # 路由配置 │ │ ├── store # 全局状态 │ │ ├── views # 页面级组件 │ │ └── main.js │ ├── package.json │ └── vite.config.js ├── server # 后端代码 │ ├── routes # 路由 │ ├── controllers # 业务逻辑 │ ├── models # 数据模型 │ ├── middlewares # 中间件 │ ├── utils # 工具函数 │ └── app.js ├── data # SQLite 文件目录 ├── docs # 自己的设计文档和笔记 ├── scripts # 启动/部署脚本 └── docker-compose.yml很多人会问就这么小的项目需要把前后端代码放在一个仓库里吗我是故意这么做的。放在一起的好处是本地调试方便一个仓库、一条命令就能把前端后端都拉起来commit 历史也是完整的一个功能从接口到页面都集中在一个提交记录里。对单人项目来说这是效率最高的一种方式。3. 迭代两轮的完整记录从 2-1 到 2-2 的重构经历liubingchen2-2里的2-2不是凭空来的。我第一次写完这个工具站时它的代号是2-1。第一版能用但很粗糙代码全堆在app.js里前端页面用模板字符串拼 HTML改一个按钮样式要翻到几十行下去。我在用了它大概两周之后做了一个决定推翻重来。这不是一时冲动而是积累了足够多的不方便到了不得不重构的地步。3.1 为什么第一版必须推倒重构要趁早第一版最大的问题不是代码丑而是扩展太难。每加一个功能我都需要在一堆互相纠缠的函数里小心翼翼地插入逻辑改一处经常崩三处。这种状态持续下去这个项目就会彻底变成屎山。重构前我先列出继续使用中暴露的问题后端没有分层路由、业务逻辑、数据访问全在一个文件里前端用模板字符串渲染页面动态数据一多就混乱没有任何自动化测试改完代码只能靠手动点页面验证数据库没有做版本管理字段一改就要手动备份和迁移这些问题的本质是结构缺失而不是某个具体 bug。所以在 2-2 这场重构里我做的第一件事不是写功能而是搭分层结构。后端按routes → controllers → models分层之后路由文件只负责定义 URL 和 HTTP 方法具体逻辑放到 controller操作数据放到 model。这样我新增一个接口通常只需要复制一份 controller 和 model 的模板改改逻辑就行几乎不会再牵扯到无关代码。前端重构则引入了组件化思维。比如原来所有页面的表格都靠循环拼 HTML现在抽出了一个DataTable组件把列配置、排序、分页都封装进去。新的列表页只需要几行代码就能接入整体代码量反而下降了。重构是一场为了走得快而先慢下来的投资。这句话在做完 2-2 之后我才真正理解。3.2 写 Commit 和版本号让记录说话个人项目最容易忽略的就是版本管理。很多人包括我在内早期喜欢一次性写一大堆代码然后提交一条消息更新。等过一个月回头看完全不知道每次提交改了什么。在 2-2 的开发过程中我开始严格规范 commit message。虽然不要求像大团队那样复杂但基本格式是固定的git commit -m feat: 新增数据导出功能 git commit -m fix: 修复日期筛选边界问题 git commit -m refactor: 重构报表查询逻辑约定的关键字包括feat新功能fix修 bugdocs文档改动style格式调整不影响逻辑refactor重构不改功能chore构建、依赖等杂项这样一条 commit 就是一条清晰的改动记录。出问题时git log拉出来看英文关键词和描述基本能秒定位是哪次改动引入了问题。此外我给每一次可发布的节点打上了 tag比如v2.0.0、v2.0.1、v2.1.0这样无论本地还是服务器只要切到对应 tag 就能还原当时的完整代码状态。3.3 自动化构建给个人项目带来的安全感个人项目没有专门的运维部署也不该每次手工操作一堆命令。我花了一个下午把docker-compose.yml和构建脚本捋顺之后每次部署基本就是一条命令的事。docker-compose.yml核心内容大概是services: app: build: . ports: - 8080:8080 volumes: - ./data:/app/data - ./logs:/app/logs restart: always配合一个简单的部署脚本scripts/deploy.sh#!/bin/bash set -e git pull origin main docker compose up -d --build docker image prune -f这样做的直接好处是哪怕我半年不动这个项目再回来部署新版本时也不会忘记任何步骤。自动化构建把部署从一门手艺变成了一条指令安全感提升非常明显。4. 避坑指南个人项目最容易翻车的四件事和liubingchen2-2相处的过程中我踩过的坑远比写出来的代码多。这里挑几个最有代表性的算是给后来者的一份避坑手册。4.1 数据丢过一次之后我学乖了备份策略在 2-1 阶段我犯过一个低级错误。有一台测试服务器我为了升级某个系统组件用rm -rf清理临时目录结果路径少写了一个字母把存放 SQLite 数据库文件的目录给删了。那一刻的心情真是一言难尽。数据丢了功能写得再好也归零。从那以后我养成了一个习惯所有个人项目必须至少有本地 云端两份数据备份。对于 SQLite备份最简单的方式就是定期复制数据库文件。我写了一个小脚本每天用定时任务把.db文件压缩并传到一个独立的备份目录同时保留最近 7 天的版本#!/bin/bash BACKUP_DIR./backups DB_FILE./data/app.db STAMP$(date %Y%m%d) cp $DB_FILE $BACKUP_DIR/app_$STAMP.db find $BACKUP_DIR -name *.db -mtime 7 -delete注意千万不要把备份文件放在项目的 data 目录里否则可能被 Docker 数据卷覆盖或者被清理命令误删。独立目录、独立路径、保留周期这三个原则缺一不可。4.2 依赖地狱与锁定版本Node 项目的package.json如果从一开始不管理好版本过几个月再打开可能连依赖都装不上。我有一次拉取旧代码npm install报错报了一大片就是因为当时的依赖版本和现在的新版本不兼容。解决办法很直接锁版本。npm install时如果带着^或~前缀会允许小版本或补丁版本升级。但对于个人长期维护的项目我建议干脆去掉前缀锁定精确版本或者每次安装后把package-lock.json提交到仓库保证任何时间拉代码都能还原出一模一样的环境。我现在的习惯是{ dependencies: { express: 4.18.2, vue: 3.3.4 } }不加^不给自己留惊喜。虽然每次升级依赖要手动改版本号但对一个人维护的项目来说可控比自动更新重要得多。4.3 文档是给未来自己看的情书个人项目不留文档等于给自己埋雷。liubingchen2-2的 docs 目录里现在放着几份简单的 Markdown内容不多但每一份都能救命README.md项目简介、本地启动步骤architecture.md目录结构说明、模块职责划分schema.md数据表字段说明changelog.md每个版本的重大变更很多人觉得代码自己写的自己肯定记得住但事实是三个月后的你就是另一个陌生的程序员。你可能会忘记某个接口为什么必须传这个参数忘记某个表为什么要有那个冗余字段忘记那个可疑的setTimeout是为了等哪个异步任务完成。文档不需要写得像产品手册只需要当时的我给未来的我留几个箭头。我的原则是当一个模块的逻辑让我自己都犹豫时立刻写两句话进去。这两句话可能在关键时刻帮你省下半天排查时间。4.4 不要过度设计YAGNI 原则YAGNI 全称是You Arent Gonna Need It意思是你其实用不到它。个人项目最容易犯的另一个错误是提前给不一定到来的未来做准备。我见过有人做一个简单的博客系统第一版就上了 Redis 缓存、Elasticsearch 搜索、RabbitMQ 消息队列。结果是配置这些东西花了几周真正写博客功能的代码反而没几行。等用户量还是个位数这些组件纯属资源浪费。liubingchen2-2在 2-2 阶段我一度想引入完整的权限系统设计角色表、权限表、菜单表后来冷静下来想这个工具站就我一个人登录、一个人管理数据要那么多角色干什么于是砍掉这个需求只在用户表加了一个role字段默认都是admin。整个权限判断就是一行代码的事但完全够用。好的个人项目不是用上了多少技术而是每个技术都服务了真实需求。这个认知直接决定你的项目是能收尾还是永远停留在半成品状态。5. 从练手作品到作品集亮点让项目替你说话做到这里liubingchen2-2已经不再是一个简单的练习项目了。它有一个完整的生命周期有需求、有设计、有开发、有重构、有部署、有文档还踩过并修复了不少问题。这些经历比单纯背面试题要值钱得多。5.1 开源展示的取舍不是所有代码都要公开如果你打算把个人项目放进简历或者发到技术社区我建议你先想清楚这个项目最打动人的点是什么是整套流程完整是某个模块设计得巧妙还是踩坑过程值得分享我当时做了一件事把项目里涉及个人隐私的配置全部剥离整理出一份脱敏版本放到公开仓库。同时写了一篇开发日志把2-1到2-2的重构过程、为什么换技术方案、数据库结构怎么调整都写成了一篇图文并茂的博客。很多人会问你把代码公开了不怕别人看你写的东西烂吗我是这样想的烂代码被围观恰恰是进步的开始。只要你愿意复盘愿意在下一篇里改进呈现出来的就是一个真实、立体的学习轨迹。比起一个完美却虚假的大型项目真实的迭代过程反而更能打动人。5.2 用项目说明书讲清楚你的思考过程简历上写熟悉 Vue、Express、SQLite、Docker远不如写独立开发并部署个人工具站前后端分离容器化部署处理了数据备份和依赖版本管理问题来得有说服力。技术名词只是标签解决问题的过程才是资产。我在项目 README 里专门加了一个 section叫 Design Notes记录自己在这个项目中做的关键决策。比如为什么用 SQLite 而不是 MySQL为什么选择 Express 而不是 NestJS为什么一开始就要写备份脚本。这些为什么比是什么更能体现出你的思考深度。面试官或者读者看到你的项目时如果只能看到一个能跑的功能那它和别人的 demo 没有区别但如果他们能看到你为什么这么想、为什么这么选、踩过什么坑、怎么爬出来那你的项目就真正开始替你说话了。写在最后liubingchen2-2这个名字我后来没有再改。它像一个坐标记录着某一阶段的我技术还比较生涩但已经开始认真对待每一行代码。每次看到这个仓库名我都会想起那个对着 500 行app.js发愁的晚上。如果你也在维护一个名字随便、功能不大但一直在迭代的个人项目请一定把它坚持下去。不要急着推倒重来也不要急着加功能先把当前这版用顺、用透把所有不顺手的地方记录下来用一次认真的重构去解决它们。过几个月再回来看你会感谢现在这个愿意较真的自己。