★ FEATURED ARTICLE 从零开始做一个“无标题”项目我的个人项目构思与落地全记录很多年前我第一次动手写自己的项目时打开编辑器想了半天连文件名都不知道该叫什么。后来我明白一件事一个项目最不值钱的恰恰是名字最值钱的却是从“无标题”这个状态里生长出来的那一整套思考过程。今天把这套流程完整拆开讲包括我怎么定位需求、怎么选技术栈、怎么设计核心模块、怎么排查那些折腾人的bug以及最后怎么把项目从“能跑”打磨到“好用”。不管你是刚接触开发的新手还是已经写过不少代码但总卡在项目规划阶段的同学这篇内容应该都能给你一点参考。我所说的“无标题”项目指的是一个我花了大概两周业余时间做出来的个人内容工作流小工具。它解决的问题其实很朴素我每天要从各个渠道收集很多文章、片段、笔记但它们散落在不同地方有的在浏览器书签里有的在备忘录里有的干脆就是聊天记录里的一句话。等真正要写东西的时候又得翻半天。这个工具做的事情就是把所有碎片内容统一收进来做一个轻量的归类和全文检索让我随时能把某条内容捞出来并且按我自己的方式重新组织成草稿。1. 项目定位先想清楚“要解决谁的问题”做项目最容易踩的坑不是技术不会而是做出来的东西根本不是自己真正需要的。我见过太多人一上来就想“我要做一个很酷的东西”然后为了炫技堆了一堆框架最后连自己都不用。所以我在动手之前很刻意地给自己定了一条规矩这个项目只解决我自己的一个问题不做大而全只做小而准。1.1 从“痛点清单”到“核心需求”我做的第一件事是列了一张痛点清单把我使用现有工具时不爽的点全部写下来。不夸张地说我写了差不多二十条其中有几条特别扎心收藏的内容多了之后看到标题根本想不起来里面讲的是什么想搜索某条内容时工具自带的搜索功能要么太弱要么按我的关键词根本匹配不上不同工具之间内容互不相通手动搬来搬去特别容易丢想输出一个汇总草稿时只能在几个应用之间来回切换复制粘贴列完清单之后我给所有痛点排了一个优先级。设计学里有个词叫“用户故事”我那时才真正体会到它的意思把“我想要一个搜索功能”转成“当我想引用某条内容时我可以在几秒内通过关键词找到它”需求就变具体了。于是我的核心需求就收敛成了三句话第一捕获要足够快。从我发现一条内容到它进入我的资料库不能超过几步操作最好一步到位。第二存储要足够简单。我不需要复杂的数据库设计一条内容就是一段文字加一个来源加几个标签这样的模型足够轻。第三检索要足够顺手。不光是按标签找更重要的是支持全文搜索哪怕我只记得里面某个冷门词汇也能把内容捞出来。1.2 为项目划清边界什么不做比做什么更重要做完需求收敛之后我接着做的事情是给项目划边界。这一步很重要因为一个业余项目最怕的就是失控做着做着就开始往里面加功能。我当时给自己定了三条很明确的不做不做移动端App。手机端的使用场景确实存在但开发成本会多出一大截我决定先留着后续再考虑。不做多人协同。这是我个人的工具不需要权限系统、多人实时同步这些功能。不做复杂的数据分析。我不需要统计每天收藏多少条、来源分布如何这些表面功能对核心价值没有帮助。划完边界之后我心里就踏实了。因为我非常清楚地知道这个项目要做成什么样、做多大、什么时候算完。说句实话很多开源项目之所以烂尾不是因为作者能力不够而是因为从来没定义过“做完”是什么样子。2. 技术选型与架构设计别为了工具而选工具技术选型是每个开发者在项目初期都会纠结的事情。我的经验是选型的标准永远只有一个它能不能用最低的成本解决你的核心问题。这个“成本”不只是学习成本还包括维护成本、部署成本和后续扩展的成本。所以在动手敲代码之前我花了不少时间做技术选型和架构设计。2.1 技术选型为什么我最终选择了这套组合先说我最终选型后端用 Python 搭配 FastAPI前端用一套极简的 Web 界面数据库用 SQLite全文搜索用了 SQLite 自带的 FTS5 扩展整个项目跑 Docker 部署。这套组合可能看起来其貌不扬但每一样都是经过比较之后才定的。我之所以不选更重的方案原因很简单。我最早考虑过用 PostgreSQL因为它的全文搜索能力确实更强。但后来转念一想我这个工具是给自己用的数据量撑死了也就几千条文本用 PostgreSQL 属于大炮打蚊子还多了一个需要维护的数据库服务。SQLite 单文件存储备份也就是复制一个文件对个人工具来说简直完美。再加上 FTS5 全文搜索在这样量级的数据上性能完全够用我就不再纠结了。前端没有选择复杂框架也是同样的逻辑。我这个工具的使用者只有一个我不需要组件化工程化那套体系一个页面、几个按钮、一个列表最原始的 HTML 加一点 JavaScript 就足够了。少依赖一个前端框架就少了一层构建链路的维护成本。很多人可能会觉得这不“现代”但工具类项目的第一原则是解决问题不是表演技术。当然如果你和我一样喜欢折腾前端也可以用现成的组件库这个没有对错之分适合自己就好。后端用 FastAPI 的原因比较实际。它的代码结构简洁自动生成的接口文档对调试特别友好同时基于异步框架虽然我这个场景不太需要高并发但写起来确实清爽。选 Python 还有一个隐性好处后续如果想在这个工具上做点文本处理、关键词提取之类的事Python 生态里有现成的库可以直接调用扩展起来不费劲。2.2 架构分层不要让所有逻辑挤在一坨代码里虽然这是一个小项目但我还是从一开始就保持了基础的架构分层。整个系统被我分成了三层路由层、服务层、存储层。路由层只负责接口的接收和响应。也就是说前端发过来的请求到了路由层之后它只做一件事情把参数交给服务层然后把服务层返回的结果封装成响应。这样做的好处是接口的入参出参非常清晰调试的时候一眼就能看出来问题在哪个环节。服务层承载所有业务逻辑。比如“新增一条内容”这个操作实际要做的事情是校验参数是不是合法、把标题和正文拆开、生成标签索引、最后写入数据库。还有“搜索”这个操作要先判断用户输入是精确标签还是全文检索然后决定走哪条查询路径。这些规则全都在服务层里体现写清楚之后对后续扩展非常关键。存储层只管和数据库打交道。我对存储层的要求是对上层永远只暴露简单的读写方法上层永远不需要关心 SQL 怎么写。比如服务层调用一个create_content方法存储层内部去拼接 SQL 语句、执行事务、处理错误服务层只需要拿到一个成功或失败的结果。这样的好处是哪天我要把 SQLite 换成 MySQL服务层和路由层一行代码都不用改只换存储层内部实现就行。说个实话很多新手写项目的时候觉得反正功能简单直接在一个文件里从请求处理写到 SQL 查询代码也能跑。但等到项目写了一半想加个新功能时就会发现所有逻辑纠缠在一起动一处牵扯一片。分层的意义不是让你的代码看起来更“专业”而是替你未来的自己省时间。3. 核心模块设计把“收集、存储、检索”三件事做扎实项目整体功能并不复杂严格来说就三个核心模块采集入口、内容存储、全文检索。但越是简单的功能越是值得抠细节。这三个模块里我踩过的坑几乎全在“看起来很简单”的地方。3.1 采集入口从“复制粘贴”到“一键收纳”采集模块的核心诉求是当我在读一篇文章或者一段聊天记录时我可以以最快的速度把它保存到资料库。我最终做的是一个浏览器书签小工具式的入口收藏一段文字其实就是把网页里的文本选中然后点击收藏按钮内容就自动到了我的资料库。因为我把入口做成了浏览器里的收藏夹功能所以整个操作变成一步不需要打开任何额外的应用。这里有一个关键细节我怎么决定收藏什么内容我的方案是让用户也就是我自己在收藏的时候可以输一个简短的说明这个说明会作为内容的首段摘要存储下来。很多人会觉得标签就够用了不用多此一举写摘要。但实际操作之后我发现写摘要的过程其实就是逼迫自己“想清楚这条内容为什么值得收藏”这个思考本身价值极大。哪怕只有一句话三个月后再看到时它所传递的上下文信息比十个标签都管用。采集模块还有一个小细节是对重复内容的处理。如果某条内容已经被收藏过了再次收藏时我不应该创建一条新记录而是提示已有记录让用户决定是跳转过去还是仍然要重新保存。这个逻辑虽然简单但避免了资料库膨胀和搜索时出现重复结果。我处理的方式是对文本内容做一个内容哈希每次入库前先查一下哈希是否已存在重复就直接拒绝。3.2 内容存储数据模型要够“薄”但别太“脆”数据模型是整个项目的地基。如果数据模型设计得有问题后面所有功能都会变得束手束脚。我当时把一张叫contents的表当成了核心它在数据库里长这样CREATE TABLE contents ( id INTEGER PRIMARY KEY AUTOINCREMENT, title TEXT NOT NULL, body TEXT NOT NULL, summary TEXT DEFAULT , source_url TEXT DEFAULT , tags TEXT DEFAULT , created_at DATETIME DEFAULT CURRENT_TIMESTAMP, updated_at DATETIME DEFAULT CURRENT_TIMESTAMP );看起来很简单对不对但有几个字段是我尝试之后才确认需要加的。第一个是source_url。最初我的表里没有这个字段因为我想的是“我就是记录一个片段要什么来源链接”。直到有一天我收藏了一条重要信息过了几周去看完全不记得它出自哪里那一刻我才意识到来源信息对一条引用来说是多么关键。第二个是updated_at最初也没有。后来我想给记录加备注时发现没有更新时间字段我根本没法分辨哪条记录是最近动过的于是老老实实补上了。关于标签的存储我采用了最简单的方案直接用逗号分隔的字符串存在tags字段里。有些设计上比较较真的人会用单独的关联表存标签因为它更规范、支持一对多关系。但说实话对一个个人工具而言把“标签”这种数据单独拆表意义不大平白增加查询复杂度。我只需要在查询时用LIKE匹配一下tags字段就够了。你可能觉得这样不“正规”但项目是自己的适合自己的才是最好的。3.3 全文检索从“找得到”到“找得快”说到全文检索这个模块在我最初的设计里是被忽略的。我当时想得很简单加一个搜索框程序把数据库里所有内容都读一遍然后逐个判断有没有包含关键词。在数据量只有几百条的时候这招确实没问题速度也还过得去。但当我收集的内容开始破千之后这种遍历式的搜索就明显吃力了尤其是界面有卡顿感。所以后来我把搜索模块切到了 SQLite 的 FTS5 全文搜索扩展上。这个扩展是 SQLite 自带的不需要额外安装任何服务。它做的事情本质上是对文本内容建立倒排索引搜索的时候不是一条条去比对而是直接根据索引定位到包含关键词的记录速度提升非常明显。我建了一张虚拟表核心 SQL 长这样CREATE VIRTUAL TABLE contents_fts USING fts5( title, body, summary, contentcontents, content_rowidid );这里有个细节值得注意FTS5 虚拟表本身不是数据存储的地方它只是一个索引。所以我的真实数据是在contents表里而contents_fts像一个检索入口通过外联关系把匹配的记录关联回来。这种设计的好处是数据只存一份不会出现两边不同步的情况。为了保持两边数据一致每次往contents表插入或更新数据时还要同步更新 FTS 表我用库里面提供的触发器来完成这件事。搜索的时候典型的查询语句是SELECT c.*, bm25(contents_fts) AS rank FROM contents_fts f JOIN contents c ON c.id f.rowid WHERE contents_fts MATCH ? ORDER BY rank;有编程经验的朋友看到bm25应该很亲切。BM25 是一种经典的相关性排序算法简单说就是根据关键词在文档中出现的频率、逆文档频率等因素算出一个分数分数越高说明匹配度越好。这比简单的时间排序要聪明得多因为当用户搜索一个词时排在最前面的往往是他真正想找的内容而不是最新收藏的无关结果。这个细节我特别满意因为它让“搜索”这个动作从“勉强能用”变成了“确实好用”。4. 实操过程接口开发、调试与打磨前期的设计和选型做完之后真正的编码工作反而比较顺理成章。但编码中依然有许多值得记录的实操细节比如接口设计、数据验证、错误处理等。这些细节决定了项目在真实使用中是否顺手。4.1 接口设计让前后端之间的语言清晰起来我给自己定义了四个核心接口基本上覆盖了一个内容管理工具的全部操作POST /api/contents 新增一条内容 GET /api/contents 分页获取内容列表可按标签筛选 GET /api/contents/{id} 获取单条内容的详情 DELETE /api/contents/{id} 删除一条内容 GET /api/search?q关键词 执行全文搜索这个接口清单看起来非常简单但我特意避开了PUT和PATCH这类更新操作因为当前阶段我并不需要主动编辑内容。如果以后真的需要修改再补一个更新接口也不迟。千万不要一开始就把所有 CRUD 都对一遍很多方法在真实使用中根本用不到接口越多维护负担越大。在请求数据验证上我用上了一件值得一说的事情FastAPI 自带请求体校验。我设定了一个输入模型比如新增内容时前端传给我的 JSON 必须包含title和body两个字段如果一个为空就直接返回 400 错误。许多初学者容易忽略这一步觉得传过来的数据没人会乱写可实际上调试时最容易出的幺蛾子往往是某个字段在某个环节变成了空值。4.2 写入流程一段代码说清“入库前和入库后”为了让你更直观地理解整个写入接口的逻辑我把新增内容的后端处理流程简化了一下。这一步对应的服务层代码大致是这样的逻辑思路def create_content(payload: ContentCreate): # 1. 检查内容哈希是否已存在避免重复入库 content_hash sha256(payload.title payload.body) existing storage.find_by_hash(content_hash) if existing: raise DuplicateContentError(这条内容已经收藏过了) # 2. 调用存储层接口写入数据库同时更新FTS索引 content_id storage.create_content(content_hash, payload) # 3. 返回创建成功的完整对象给前端 return storage.get_content(content_id)你可能注意到我在入库之前额外做了一个“哈希查重”。这个做法源于一次惨痛教训某一天我从同一个网页的不同入口重复收藏了同一篇文章因为标题大小写和正文的微小差异数据库里存了两条几乎一模一样的记录。从那以后我坚定地给每次入库做哈希指纹凡是指纹相同的内容直接拒绝。这里的指纹是指对标题和正文组合算出的一个唯一字符串好比内容是人的脸哈希就是这张脸的身份证号拿着身份证号一比对就知道是不是同一个人。在数据库写入之后FTS 索引的更新也由一个触发器自动完成这一点是 SQLite 提供的便利。只要把更新逻辑写在触发器里就不必在业务代码中手动维护两套数据写入逻辑省心很多。触发器本质上是一种数据库级别的自动响应机制就是“当某张表发生某个动作时自动执行预定的额外操作”。4.3 界面交互细节搜索体验是打磨出来的搜索模块的界面虽然简陋但我在交互上打磨了很多细节。因为我知道一个工具好不好用很多时候不在于功能多不多而在于那几个高频操作是否顺畅。我在搜索结果页里加了一个关键词高亮效果。用户输入关键词后返回结果中所有命中的文字都会被打上高亮标记。这个功能的技术原理非常简单就是把返回的文本里的关键词替换成带标记的 HTML 片段但体验上的提升非常直观。如果没有高亮用户看到一长段搜索结果时还得自己找关键词在哪有了高亮一眼就能定位到目标。我还有一个细节是搜索时的“空查询不搜库”。也就是说搜索框空了就直接显示最近内容列表不会触发一次无意义的全文检索。很多工具没有在意这种细节用户把搜索框清空了还在傻傻地执行模糊查询浪费资源不说返回结果还会让用户困惑。我自己的原则是对用户呈现的结果一定要清楚、直白、不啰嗦。5. 常见问题与排查技巧实录写这个项目的两周里我遇到了不少值得一提的问题。这些问题如果不记下来可能过两个月我就忘了当时是怎么解决的。这里整理成一个小型的速查表供参考。加粗的地方是我认为最关键的经验。5.1 FTS 搜索匹配不到内容这是我最开始启用 FTS5 时遇到的头号问题。我当时往数据库里插入了一条标题为“如何提炼会议纪要”的内容然后用“会议”去搜结果后台返回了零条数据。我当时第一反应是索引没有建好检查了半天触发器确认没问题后才开始怀疑是不是分词的问题。后来我用 FTS5 的默认分词器去分析才发现它默认不会把中文句子按单个词语切分而是把整段中文当成一串连续字符来处理。也就是说“如何提炼会议纪要”在索引里其实是“如何提炼会议纪要”这一整串连续字符搜索“会议”时因为“会议”并不是整串字符的连续子串所以匹配失败。解决方式也简单建表时指定tokenize unicode61加上一个移除分隔符的选项或者换用专门的中文分词器。但我个人做项目不想引入太多额外依赖所以最后采用的是预处理方案入库前先把文本按空格分词存进一个附加字段然后再对这个字段建 FTS 索引。这样搜索的时候先用空格分词再匹配就能获得较好的中文搜索效果。如果你也做中文全文搜索千万不要想当然直接用默认配置要先小样本做一轮验证再正式接用。5.2 日期显示时区错乱这个问题不大但困扰了我一个下午。我的内容表里记录了一个created_at字段存的是带时区的本地时间。没想到前端拿到显示时变成了 UTC 时间导致我收藏一条内容显示的时间会比实际提前八个小时。排查之后发现问题出在数据序列化时没有明确指定时区后端在返回 JSON 时默认为 ISO 格式的 UTC 时间而我的前端没有做时区转换。解决方式是在接口返回前统一转换成指定时区字符串或者干脆把数据库里的时间统一存成 UTC只在展示时转换成当地时间。时间处理是个很容易被小看的环节一旦项目跨设备使用这种错位就会变得特别扎眼。我现在的经验是数据库里统一存 UTC所有展示由前端负责转成当地时区避免后端到处做时区判断。5.3 部署到新机器上总是忘记初始化 FTS这个坑说出来有点不好意思。因为 FTS5 的表是虚拟表数据不落盘到普通表里所以每次把数据库文件复制到新环境时都必须先跑一遍索引重建脚本否则搜索功能就是坏的。我前两次部署都忘了这一茬还一度以为是数据库文件损坏了。后来我在服务启动脚本里加了一步强制重建 FTS 的校验每次启动时检测一下 FTS 表是否存在若缺失就自动执行初始化。如果你也用了 SQLite 的 FTS无论怎么迁移数据记住迁移后第一步一定是触发索引重建。5.4 输入超长文本导致的数据库写入失败当用户收藏一条很长的文章内容时数据库会直接拒绝写入错误信息是“data too long”。这是因为 SQLite 对TEXT类型字段默认有一个长度限制超出后写入就失败。我之前没考虑过这个问题因为个人笔记通常不会太夸张。但收藏一整篇长文时确实可能踩中。解决方案有两种第一种是写入前检查长度超过阈值就报错并提醒用户第二种是把超长内容拆分成多个块存储但查询时又要处理拼接逻辑。我选的是第一种方案因为我的工具定位是“片段、摘要、引用”而不是全文仓库。给自己定一个数据上限其实也是帮项目保持边界的一种方式不要什么都往里塞。5.5 SQL 参数注入风险如果你写的功能里包含用户输入那么参数注入是永远绕不开的话题。我这个项目里搜索关键词肯定来自用户输入在最初版本里我图方便直接用了字符串拼接。某一天我拿一个包含特殊符号的关键词测试时程序直接报错了而且报错语句里能看出 SQL 块的内容。那一刻我心里咯噔一下立刻把所有 SQL 都改成了参数化查询的写法。在 SQLite 中正确的做法是使用问号占位符然后传入参数数组。任何时候都不要把用户输入直接拼进 SQL这个教训值一部手机的钱。6. 工具与工作流让项目后续维护更轻松项目能跑通只是第一步真正让我觉得这个项目“完工了”的瞬间是我把部署、备份和后续开发的工作流也一并理顺的时候。6.1 开发环境工具链这个项目我是从零开始搭建开发环境和工具链的。开发环境使用容器化方案因为这样可以保证不同机器上的运行环境完全一致。我第一次在新电脑上跑项目时因为没有容器化方案光是装依赖就花了一上午那时候我就下定决心要换用容器方案。我写了一个极简的容器配置文件里面定义了 Python 版本、安装依赖的命令、启动服务的指令然后在本地一条命令就能把整个环境拉起来半分钟不到就能开始改代码。编译调试方面我用的是日志加断点的组合策略。由于接口数量较少打印请求日志是最高效的调试手段之一。我开发的习惯是在路由层打一眼就能看到的进入日志在服务层关键时刻打带参数的详细日志在存储层打 SQL 执行日志。这个三层日志体系帮我节省了无数定位问题的时间。6.2 数据备份与恢复策略个人项目最怕的不是代码丢了而是数据丢了。代码可以从代码仓库里恢复但内容数据库一旦损坏那就真的全没了。我的备份方案很简单基于这样一个事实SQLite 整个数据库就是一个单文件备份只需要把这个文件复制走。我用系统自带的定时任务每天凌晨自动把数据库文件复制到指定备份目录同时保留最近七天的版本。恢复路径也很直接把备份文件复制回数据目录即可。如果你担心备份在同一块硬盘上不保险也可以定期手动把备份上传到对象存储或者推到自己的存储空间里因人而异。个人项目的备份策略核心就三个字一定做。6.3 可移植性与后续扩展最后聊聊项目中那些“以后再说”的设计。我现在使用的这套架构本质上留了不少扩展接口。比如存储层目前写死了 SQLite但由于我把所有数据库访问都收敛到了一个模块里未来换数据库时只需要改这一个地方。再比如采集入口目前只做了一件事从浏览器收藏夹收集片段以后如果需要支持邮件、即时通讯工具或者其他来源也只需要新增一个入口模块业务逻辑不用大改。我还给自己留了一个数据处理的后门在服务层里预留了“对文本执行任意处理函数”的能力。这个设计让我可以做很多实验例如用 Python 写个简单的关键词抽取脚本接入到工具里以后每次入库自动把关键词补成标签。这个功能我还没完全实现但架构上已经趟平了路。这句话送给所有喜欢做个人项目的朋友过度设计是负担但合理预留扩展点是对未来自己的善意。结尾写到这里这个“无标题”项目从构思到落地的全过程基本讲完了。回过头看最有价值的并不全是那几段代码而是我在过程中反复做取舍的思考方式。我最大的体会是个人项目的成败往往不取决于代码写得有多花哨而在于你有没有把“要解决什么问题”这件事想透。你可能和我一样经常冒出各种点子但落到行动时又容易被各种选择困住。我的建议很简单先想清楚自己要什么然后选择最顺手的工具把核心功能做扎实其余的功能以后再补。每一次动手完成一个项目你对“怎么做选择”这件事的理解就会加深一层。希望这篇记录能给你一点启发也欢迎你从自己的“无标题”开始做出一个真正顺手的东西。
阅读完成 · 觉得有帮助？
