1. 为什么要从零开始写后端项目后端这行最不缺的就是“会用一个框架”的人。Spring Boot、Django、Express、Gin照着官方 Quick Start 点几下一个 hello world 接口就起来了。但真正遇到问题时你还是会慌为什么这里要加事务为什么这个查询这么慢为什么并发一高就超时如果这些问题的答案你只能从搜索引擎里找而且找完还不一定看懂那就说明你缺的并不是更多教程而是一个从头到尾、不看脚手架、纯靠自己搭起来的小项目。这个“从头开始项目”本质上不是让你重新发明轮子。它的价值在于你在没有任何现成代码可抄的情况下被迫把后端开发里的每一个环节都亲手过一遍。从项目初始化、依赖管理、目录设计到数据库建模、接口设计、鉴权方案再到日志、配置、部署所有平时藏在框架背后的东西都会被逼着摊在你面前。这个过程会非常难受但也是成长最快的方式。我整理这份笔记时用的就是一个虚拟的“某内容管理平台”后端作为例子。技术栈选的是当前比较主流、同时资料丰富的一组语言用 Node.js 环境下跑 TypeScript框架选轻量级的 Express 类方案数据库用 PostgreSQL 搭配 ORM缓存用 Redis部署走 Docker Compose。这套组合的好处是每个组件都不算冷门遇到问题能搜到答案同时它们之间没有那种“全家桶”式的框架帮你包办一切很多细节必须自己配正好达到练手的目的。这篇笔记适合谁看两类人。第一类是刚学完语法、想正经做第一个项目的初中级开发者你会在这里看到一条完整的、可落地的开发路径第二类是平时只写业务 CRUD、想补基础的老开发像事务边界、连接池、索引失效这些问题很多人会用但讲不清原理这篇笔记能帮你把知识点串起来。2. 项目初始化先把地基打正2.1 初始化项目与依赖管理很多人起步就错在贪快一上来就敲npm init -y然后哐哐装一堆依赖最后package.json里一半的包不知道干嘛的。我的习惯是先把目录结构想清楚再开始装东西。虽然这样看起来慢但后面每个模块放哪、依赖关系长什么样心里都有数。一个典型的后端项目目录大致分成这几块src/主代码目录routes/路由接口入口层controllers/控制器接参数、调服务、返回响应services/业务逻辑层核心规则都在这models/数据模型定义对应数据库表结构middlewares/中间件鉴权、日志、错误处理等utils/工具函数config/配置文件区分开发和生产的配置migrations/数据库迁移脚本scripts/一些一次性脚本比如初始化种子数据你先别急着问我“为什么不用框架推荐的单文件结构”。对于小项目单文件确实够用但既然是以“从头开始”为目标的练习项目分层的好处是后面项目变大时你不需要重构。我自己实操下来最舒服的依赖规则是路由只做转发、控制器只做参数解析和响应、业务规则全放服务层。谁越界谁负责改测试起来定位也快。初始化阶段还容易忽略一个东西版本锁定。package.json里如果依赖版本前面带着^你过三个月再装依赖拿到的可能就不是同一套代码小版本升级经常引入行为变化到时候排错排到怀疑人生。建议装上锁文件npm 默认的package-lock.json就够用提交到仓库里确保所有人、所有环境拉到的依赖版本一致。2.2 从空白目录到可运行服务这里我记录一下最简骨架的搭建过程从零到一个能返回 JSON 的接口大概就这几步创建目录初始化 npm 项目安装运行时依赖和开发依赖运行时依赖只装真正需要的开发依赖主要放 TypeScript 类型声明和编译工具配置 TypeScript 编译选项重点是把strict模式打开虽然写起来会痛但能拦住大量低级错误创建最简服务器入口先不接数据库、不接 Redis只要一个健康检查接口配好 npm scripts开发时用热重载部署时用编译后的产物这个阶段的目标不是功能是“能跑”。你需要在终端里看到服务启动成功的日志然后用浏览器或接口调试工具访问到那个健康检查接口。我实践的时候会在这个阶段多做一件事直接把统一响应格式定义好。统一响应格式听起来简单但很多项目直到上线都没有一个稳定的约定。前端拿到 200 就当成功、拿到业务错误码就弹 toast每个接口各写各的联调时能吵一天。我在这个项目里用的格式是{ code: 0, message: success, data: {} }code 为 0 表示业务成功非 0 是业务错误码HTTP 层面的 4xx/5xx 只用来表达传输或系统层错误。这样前后端约定就清晰了看到 HTTP 200 只能说明请求通了真正成败要看 code。这个小约定让我后期加鉴权、加参数校验时省了很多沟通成本。注意开发阶段最好把strict模式打开到底宁可编译时报错多也不要留着隐患到运行时才爆。2.3 工具链配置的取舍心得工欲善其事必先利其器。我这里的“器”指的是静态检查、格式化、调试配置这些不太起眼但每天都要碰的东西。静态检查工具帮你拦住“声明了没用到”“隐式 any”“空值判断遗漏”这类问题。新手最容易嫌它烦但其实它等于一个免费的朋友在帮你 review 代码。我建议把规则配严一点宁可多报错不要放水。格式化工具解决“每个人代码风格不一样”的问题。装上之后保存就自动整理格式commit 之前再跑一遍diff 里就再也不会出现“这里多了个空格”这种无营养的修改。调试器很多人写后端口头禅是“console.log 大法”但项目一复杂你会发现console.log出来的对象是“活”的——你展开看的时候值已经变了特别容易误导。断点调试虽然上手有一点门槛但看清楚调用栈、变量在每一行的变化排查逻辑错误是真省时间。还有一个常被忽略的细节环境变量。别把数据库密码、密钥直接写死在代码里或配置里。项目根目录放一个.env.example作为模板里面写好所有需要设置的变量名和示例值提交到仓库真正的.env文件加入 .gitignore只存在于本机和服务器上。这样换环境、加人照着模板复制一份就行密钥不会泄露。3. 数据库设计与迁移表结构才是产品逻辑的根3.1 核心库表怎么建我这次设计数据库时第一个感受是建表这件事看着像体力活实际上非常考验对业务的理解。就拿“内容管理平台”举例最核心的表至少有三张用户表存放账号基础信息包括用户名、密码哈希、昵称、头像地址、状态等内容表存放用户发布的内容包括标题、正文、作者 ID、状态、发布时间分类表给内容做归类内容表通过外键关联分类表表结构设计最容易犯的错是把所有字段堆在一张表里。比如把分类名直接写在内容表上图一时方便后面分类改名时就要遍历所有内容去更新还要担心有的漏改。规范的做法是拆表每次联表查询多出的那点开销和“一处修改、全局生效”的维护便利性比起来几乎可以忽略。我自己在建表时有几条固定原则主键用自增 ID 还是用 UUID如果表是内部的、不暴露给用户自增 ID 简单高效如果要暴露给外部就避开自增 ID不然竞争对手一眼就能看出你的业务量也存在被遍历抓取的风险。我这次内部表用自增 ID对外接口返回的数据用一个业务唯一标识去映射。时间字段统一用带时区的时间类型。后端服务一旦部署到多区域没有时区信息的时间早晚会出问题。凡是表示状态的字段加默认值且尽量用数字或简短字符串不要用中文。能加非空约束的就不要留 nullable。每少一个空值判断代码里就少一种出错的可能。3.2 迁移脚本让表结构跟着代码走后端开发里有一句老话“代码可以重构数据库不能随便删了重建。”如果表结构是靠人去手动改的那开发、测试、生产三个环境的库结构迟早会不一致——这就是“在我机器上能跑部署上去就报错”的重要源头。解决办法是数据库迁移。简单理解每次表结构的变更都写成一个迁移脚本脚本里面写明“要做什么”和“怎么撤销”。执行顺序固定执行过的脚本会被记录这样无论哪个环境只要顺序执行同一批脚本最终结构一定一致。我用 ORM 自带的迁移工具来管这件事实操步骤如下在项目里初始化迁移配置指定迁移文件存放目录新建迁移给用户表加一个“最后登录时间”字段生成 SQL 前先确认字段名、类型和默认值正确执行迁移完毕后去数据库客户端确认表结构更新数据模型里的实体定义保持代码和库结构同步这里有个关键点迁移脚本一旦提交并被环境执行过就不要再直接编辑它了。你要改就新建一个迁移去改。因为每个环境执行记录里都记着这个脚本的哈希或文件名你改历史脚本环境 A 跑过了、环境 B 还没跑两边就分叉了。这是很多人踩过、还会继续踩的坑。迁移之外种子数据也值得一提。你不可能每次启动项目都手动插一条测试用户。写一个种子脚本把初始账号、默认分类、示例内容一次性灌进去。这样新同事 clone 完项目跑一次就能有一个看起来还算真实的环境而不是对着空库发呆。3.3 索引设计别等慢查询找上门索引这个话题平时 CRUD 写多了真容易忽略。数据量只有几千条时全表扫描也快到了几十万、上百万条没有索引的查询会让人怀疑服务器是不是死了。但索引也不能乱加加多了写入变慢、占用磁盘还可能误导优化器选错执行计划。我的索引设计经验是先想清楚查询场景再谈索引。用户登录要按用户名查那用户名就应该建唯一索引内容列表要按分类和时间排序展示那分类 id 和时间字段的联合索引就比两个独立索引更贴合查询。一个实用的排查技巧任何 SQL 都要能讲清楚它走了哪个索引或者为什么没走索引。你可以在数据库客户端里执行查询计划分析看看扫描行数是多少。我见过一个典型的坑在字符串字段上建了索引但因为查询时没注意字符集或类型转换索引完全没被用上。还有一次某人习惯了写LIKE %关键词%做模糊搜索数据量大时慢得离谱后面改成全文检索方案才解决。4. 业务接口实现从需求到能用的 API4.1 接口设计与参数校验接口设计这件事我最大的体会是先定契约再写实现。前后端并行开发时如果接口文档是模糊的联调环节就会变成一场灾难。虽然现在的接口文档工具能自动生成文档但前提是代码里的注释写到位。设计接口时有几个原则我一直在用URL 用资源名HTTP 方法表达动作。比如获取内容列表是 GET /contents创建内容是 POST /contents。不要出现 GET /delete_content 这种缝合怪。列表接口必须考虑分页。没有分页的列表接口数据量一大就是隐患。我习惯用页码和每页条数来控制超过上限就截断。创建和更新的字段要明确区分。创建时允许传全部字段更新时往往只允许传部分字段接口上要写清楚实现时用对应的 DTO 去接收而不是整个请求体直接透传给数据库。接口返回值不要直接抛数据库的错误信息。数据库报错对用户来说就是天书你应该把它翻译成业务可读的错误码和提示。参数校验我放在路由的处理链里和业务代码完全分开。定义一个校验规则文件声明每个字段的类型、是否必填、长度范围、枚举值路由进来先校验再进控制器。这样做的好处是业务代码里干净了每个函数都只关心自己该关心的事。一个项目里最容易失控的其实不是接口数量而是错误码管理。我见过有人把错误码写在各个文件里查文档都查不全。我的做法是建一个错误码清单模块统一注册、全局只有这一处定义。新增错误码时按模块分配区间注释里写明场景和返回给前端的提示文案。这样无论后端写接口还是前端做提示查一处就够了。4.2 鉴权方案从 Session 到 Token鉴权是后端绕不开的环节这个项目我用了基于 Token 的认证方案。它的逻辑其实很朴素用户登录时校验账号密码通过后签发一个有一定有效期的 Token 给前端前端请求时把 Token 放在请求头里后端写一个中间件每个受保护接口先验 Token 再放行。选 Token 而不是方案 Session 的原因主要是为了前后端分离和未来可能的多端扩展。手机 App、网页端、第三方开放接口只要验签同一个 Token 生成和校验逻辑就都能接入。Session 方案在“浏览器 服务器同域”的传统场景里很顺但一跨端就麻烦。实操中有几个安全细节值得注意Token 中不要放敏感信息比如密码。它能被解码出来只不过有签名保护、改不了内容。一定要设置过期时间。无期限的 Token 等于把大门钥匙永久交给别人泄漏了都没办法收回。登出功能要么前端丢弃 Token要么后端维护一个黑名单把 Token 拉黑。前者实现简单但有延迟后者需要额外存储开销。我这次选择了前者因为项目复杂度还没到需要实时拉黑的级别。密码存储用的是哈希加盐不用可逆加密。可逆加密意味着能解密回明文一旦密钥泄漏等于明文密码全裸奔哈希是单向的验证时对输入重复哈希比对结果是否一致。加盐的目的是防止两个相同密码产出相同哈希降低彩虹表攻击的风险。注意自己实现的加密和签名逻辑即使自我感觉再良好也不要直接用“手写”方案。用成熟的、经过大量审计的库把密钥管理好比发明新算法安全得多。4.3 连接池与事务边界并发场景的定海神针初学者最容易忽略连接池。数据库连接的建立和销毁开销很大如果不复用每次请求新建、请求结束销毁高并发时数据库直接就崩了。连接池的作用就是维护一批已经建立好的连接谁用谁借、用完归还。连接池的几个参数要理解其含义。池的最大连接数、最小空闲连接数、连接的最大空闲时间、获取连接的超时时间。配置太小高峰期请求排队配置太大数据库资源被撑爆。这个值不能照抄网上的模板要结合你的数据库实例规格和业务流量去调。我的参考是先从数据库可承受的连接上限的 1/3 开始通过压测慢慢往上加。事务边界是另一个重灾区。一次业务操作里涉及到多张表的更新时比如“创建内容”同时要“更新作者发布计数”这两步要么一起成功要么一起回滚。把事务开在服务层的方法上而不是数据库客户端里手写 BEGIN/COMMIT用框架的事务注解或封装好的事务方法即可。这里要留心的坑是事务千万别跨远程调用。比如你在事务里调了一个外部 API外部 API 超时了事务就一直挂着数据库连接被占住不放连接池很快就被耗尽。5. 部署上线最后一公里最考验基本功5.1 环境准备与容器化启动总算到了部署环节。在服务器上我一般不用 Node 直接跑而是用进程守护工具来管。为什么因为 Node 服务如果崩溃了直接跑的方式不会自动恢复。单独配 systemd 服务或用进程守护工具才能做到崩溃自动重启、开机自启、日志统一收集。但比直接裸跑更省心的方案是把整个应用包括数据库、缓存、应用进程全部容器化。用容器编排文件把一堆服务串起来一条命令就把整套环境启动好。环境隔离的好处是在本地能跑通的环境服务器上部署也大概率能跑通不再有“系统版本不一样导致装不上依赖”的苦恼。容器编排文件里要定义的资源包括应用服务构建镜像、映射端口、设置环境变量、声明依赖数据库服务数据卷挂载、账号密码环境变量、端口映射缓存服务持久化配置自动重启策略确保容器挂了能自动拉起来我先在本地跑一遍整套编排文件确认所有服务都能起来、接口能通再上服务器。本地没问题之后服务器上只需要把代码拉下来、准备好环境变量文件、执行启动命令即可。5.2 日志与监控出了问题别靠猜服务上线后最怕的问题就是“用户说报错了但你不知道发生了什么”。日志就是你的案发现场。但日志也不是随便打的打少了查不到线索打多了把磁盘塞满、把关键信息淹没。我这次给日志分了等级调试信息写开发环境生产环境只记录业务关键事件和错误堆栈。日志里必须包含的信息有时间戳、请求 ID、请求路径、请求方法、状态码、耗时、错误堆栈。请求 ID 尤其重要。前端报错时如果能带上这个 ID后端顺着一查就能把这一个请求经过的所有日志串起来。监控方面最基础也最重要的是这三件事健康检查接口告诉负载均衡或运维系统“我还活着”基础资源监控CPU、内存、磁盘、网络错误率与耗时统计接口的成功率、平均响应时间、慢接口排名我遇到过最典型的生产事故是服务日志显示内存持续缓慢上涨几天后 OOM 被系统杀掉。排查后发现是一个静态变量往里面存数据、从不清理。这类问题靠眼很难发现必须有资源监控曲线配合才能定位。所以别等出事了才想起来搭监控上线第一天就把这些配好。5.3 常见部署问题速查部署阶段的问题往往是组合式的我整理了一个清单现象可能原因排查方向接口超时但数据库看起来正常连接池耗尽连接没归还检查连接池监控确认事务是否正常释放能访问但登录总是失败Token 签名密钥不一致检查不同环境的密钥环境变量是否统一静态资源加载慢未配置缓存头加一层 Web 缓存层或静态资源服务容器重启后数据丢失数据卷未挂载确认数据库容器配置了卷映射环境变量改了但没生效配置文件有缓存或容器没重建修改后确认服务重启、容器重新创建这里每一条背后都是我或身边同事真踩过的坑。比如容器重启丢数据就是典型的“容器是临时性”的理解不到位。容器本身是“用完即弃”的数据必须写进持久化存储否则重建容器就是一把梭哈重来。6. 写在最后项目之外的一点体会这份笔记能写出来的部分是技术流程但真正有价值的是流程背后那些被迫想清楚的问题。我从零搭完这个项目后最大的变化是看任何框架文档时不再是被动接受“它帮我做了什么”而是主动去辨识“它在哪一层替我干了活出了问题时我应该去查哪一层”。有几个习惯我想特别建议每写一段代码问自己一句“如果这个模块被删掉系统会不会出问题”。会说明它是核心不会说明它可能设计得不够内聚或者根本不该存在。接口和数据库字段的命名花一分钟想清楚比以后全局重命名省几百分钟。我见过太多 user_name 和 userName 混用的代码库了单个文件里看没什么一全局搜索就头疼。遇到查了半小时还解决不了的问题先把代码放一放重新读一遍报错信息。很多时候答案就在最后一行的英文里只不过被前面一堆无关日志带偏了注意力。最后再分享一个对我帮助很大的小技巧写“开发日志”。不是代码注释也不是周报而是用你自己的话把昨天做了哪些决策、为什么这样选、遇到了哪些问题记下来。三个月后你和别人争论某个设计时这份日志就是最有力的论据。这个项目做完之后你完全可以在它的基础上继续加东西比如引入消息队列做异步处理、增加单元测试和接口测试、加上持续集成和持续部署。每加一层都是对之前设计的验证和修正。后端这条路不怕走得慢就怕一直停留在看教程的阶段动手的那一刻才是真正开始的时刻。 
长河君 · 2026/10/15 6:36:46 · 阅读 1.2k 从零开始写后端项目：工程化落地与部署实战指南
1. 为什么要从零开始写后端项目后端这行最不缺的就是“会用一个框架”的人。Spring Boot、Django、Express、Gin照着官方 Quick Start 点几下一个 hello world 接口就起来了。但真正遇到问题时你还是会慌为什么这里要加事务为什么这个查询这么慢为什么并发一高就超时如果这些问题的答案你只能从搜索引擎里找而且找完还不一定看懂那就说明你缺的并不是更多教程而是一个从头到尾、不看脚手架、纯靠自己搭起来的小项目。这个“从头开始项目”本质上不是让你重新发明轮子。它的价值在于你在没有任何现成代码可抄的情况下被迫把后端开发里的每一个环节都亲手过一遍。从项目初始化、依赖管理、目录设计到数据库建模、接口设计、鉴权方案再到日志、配置、部署所有平时藏在框架背后的东西都会被逼着摊在你面前。这个过程会非常难受但也是成长最快的方式。我整理这份笔记时用的就是一个虚拟的“某内容管理平台”后端作为例子。技术栈选的是当前比较主流、同时资料丰富的一组语言用 Node.js 环境下跑 TypeScript框架选轻量级的 Express 类方案数据库用 PostgreSQL 搭配 ORM缓存用 Redis部署走 Docker Compose。这套组合的好处是每个组件都不算冷门遇到问题能搜到答案同时它们之间没有那种“全家桶”式的框架帮你包办一切很多细节必须自己配正好达到练手的目的。这篇笔记适合谁看两类人。第一类是刚学完语法、想正经做第一个项目的初中级开发者你会在这里看到一条完整的、可落地的开发路径第二类是平时只写业务 CRUD、想补基础的老开发像事务边界、连接池、索引失效这些问题很多人会用但讲不清原理这篇笔记能帮你把知识点串起来。2. 项目初始化先把地基打正2.1 初始化项目与依赖管理很多人起步就错在贪快一上来就敲npm init -y然后哐哐装一堆依赖最后package.json里一半的包不知道干嘛的。我的习惯是先把目录结构想清楚再开始装东西。虽然这样看起来慢但后面每个模块放哪、依赖关系长什么样心里都有数。一个典型的后端项目目录大致分成这几块src/主代码目录routes/路由接口入口层controllers/控制器接参数、调服务、返回响应services/业务逻辑层核心规则都在这models/数据模型定义对应数据库表结构middlewares/中间件鉴权、日志、错误处理等utils/工具函数config/配置文件区分开发和生产的配置migrations/数据库迁移脚本scripts/一些一次性脚本比如初始化种子数据你先别急着问我“为什么不用框架推荐的单文件结构”。对于小项目单文件确实够用但既然是以“从头开始”为目标的练习项目分层的好处是后面项目变大时你不需要重构。我自己实操下来最舒服的依赖规则是路由只做转发、控制器只做参数解析和响应、业务规则全放服务层。谁越界谁负责改测试起来定位也快。初始化阶段还容易忽略一个东西版本锁定。package.json里如果依赖版本前面带着^你过三个月再装依赖拿到的可能就不是同一套代码小版本升级经常引入行为变化到时候排错排到怀疑人生。建议装上锁文件npm 默认的package-lock.json就够用提交到仓库里确保所有人、所有环境拉到的依赖版本一致。2.2 从空白目录到可运行服务这里我记录一下最简骨架的搭建过程从零到一个能返回 JSON 的接口大概就这几步创建目录初始化 npm 项目安装运行时依赖和开发依赖运行时依赖只装真正需要的开发依赖主要放 TypeScript 类型声明和编译工具配置 TypeScript 编译选项重点是把strict模式打开虽然写起来会痛但能拦住大量低级错误创建最简服务器入口先不接数据库、不接 Redis只要一个健康检查接口配好 npm scripts开发时用热重载部署时用编译后的产物这个阶段的目标不是功能是“能跑”。你需要在终端里看到服务启动成功的日志然后用浏览器或接口调试工具访问到那个健康检查接口。我实践的时候会在这个阶段多做一件事直接把统一响应格式定义好。统一响应格式听起来简单但很多项目直到上线都没有一个稳定的约定。前端拿到 200 就当成功、拿到业务错误码就弹 toast每个接口各写各的联调时能吵一天。我在这个项目里用的格式是{ code: 0, message: success, data: {} }code 为 0 表示业务成功非 0 是业务错误码HTTP 层面的 4xx/5xx 只用来表达传输或系统层错误。这样前后端约定就清晰了看到 HTTP 200 只能说明请求通了真正成败要看 code。这个小约定让我后期加鉴权、加参数校验时省了很多沟通成本。注意开发阶段最好把strict模式打开到底宁可编译时报错多也不要留着隐患到运行时才爆。2.3 工具链配置的取舍心得工欲善其事必先利其器。我这里的“器”指的是静态检查、格式化、调试配置这些不太起眼但每天都要碰的东西。静态检查工具帮你拦住“声明了没用到”“隐式 any”“空值判断遗漏”这类问题。新手最容易嫌它烦但其实它等于一个免费的朋友在帮你 review 代码。我建议把规则配严一点宁可多报错不要放水。格式化工具解决“每个人代码风格不一样”的问题。装上之后保存就自动整理格式commit 之前再跑一遍diff 里就再也不会出现“这里多了个空格”这种无营养的修改。调试器很多人写后端口头禅是“console.log 大法”但项目一复杂你会发现console.log出来的对象是“活”的——你展开看的时候值已经变了特别容易误导。断点调试虽然上手有一点门槛但看清楚调用栈、变量在每一行的变化排查逻辑错误是真省时间。还有一个常被忽略的细节环境变量。别把数据库密码、密钥直接写死在代码里或配置里。项目根目录放一个.env.example作为模板里面写好所有需要设置的变量名和示例值提交到仓库真正的.env文件加入 .gitignore只存在于本机和服务器上。这样换环境、加人照着模板复制一份就行密钥不会泄露。3. 数据库设计与迁移表结构才是产品逻辑的根3.1 核心库表怎么建我这次设计数据库时第一个感受是建表这件事看着像体力活实际上非常考验对业务的理解。就拿“内容管理平台”举例最核心的表至少有三张用户表存放账号基础信息包括用户名、密码哈希、昵称、头像地址、状态等内容表存放用户发布的内容包括标题、正文、作者 ID、状态、发布时间分类表给内容做归类内容表通过外键关联分类表表结构设计最容易犯的错是把所有字段堆在一张表里。比如把分类名直接写在内容表上图一时方便后面分类改名时就要遍历所有内容去更新还要担心有的漏改。规范的做法是拆表每次联表查询多出的那点开销和“一处修改、全局生效”的维护便利性比起来几乎可以忽略。我自己在建表时有几条固定原则主键用自增 ID 还是用 UUID如果表是内部的、不暴露给用户自增 ID 简单高效如果要暴露给外部就避开自增 ID不然竞争对手一眼就能看出你的业务量也存在被遍历抓取的风险。我这次内部表用自增 ID对外接口返回的数据用一个业务唯一标识去映射。时间字段统一用带时区的时间类型。后端服务一旦部署到多区域没有时区信息的时间早晚会出问题。凡是表示状态的字段加默认值且尽量用数字或简短字符串不要用中文。能加非空约束的就不要留 nullable。每少一个空值判断代码里就少一种出错的可能。3.2 迁移脚本让表结构跟着代码走后端开发里有一句老话“代码可以重构数据库不能随便删了重建。”如果表结构是靠人去手动改的那开发、测试、生产三个环境的库结构迟早会不一致——这就是“在我机器上能跑部署上去就报错”的重要源头。解决办法是数据库迁移。简单理解每次表结构的变更都写成一个迁移脚本脚本里面写明“要做什么”和“怎么撤销”。执行顺序固定执行过的脚本会被记录这样无论哪个环境只要顺序执行同一批脚本最终结构一定一致。我用 ORM 自带的迁移工具来管这件事实操步骤如下在项目里初始化迁移配置指定迁移文件存放目录新建迁移给用户表加一个“最后登录时间”字段生成 SQL 前先确认字段名、类型和默认值正确执行迁移完毕后去数据库客户端确认表结构更新数据模型里的实体定义保持代码和库结构同步这里有个关键点迁移脚本一旦提交并被环境执行过就不要再直接编辑它了。你要改就新建一个迁移去改。因为每个环境执行记录里都记着这个脚本的哈希或文件名你改历史脚本环境 A 跑过了、环境 B 还没跑两边就分叉了。这是很多人踩过、还会继续踩的坑。迁移之外种子数据也值得一提。你不可能每次启动项目都手动插一条测试用户。写一个种子脚本把初始账号、默认分类、示例内容一次性灌进去。这样新同事 clone 完项目跑一次就能有一个看起来还算真实的环境而不是对着空库发呆。3.3 索引设计别等慢查询找上门索引这个话题平时 CRUD 写多了真容易忽略。数据量只有几千条时全表扫描也快到了几十万、上百万条没有索引的查询会让人怀疑服务器是不是死了。但索引也不能乱加加多了写入变慢、占用磁盘还可能误导优化器选错执行计划。我的索引设计经验是先想清楚查询场景再谈索引。用户登录要按用户名查那用户名就应该建唯一索引内容列表要按分类和时间排序展示那分类 id 和时间字段的联合索引就比两个独立索引更贴合查询。一个实用的排查技巧任何 SQL 都要能讲清楚它走了哪个索引或者为什么没走索引。你可以在数据库客户端里执行查询计划分析看看扫描行数是多少。我见过一个典型的坑在字符串字段上建了索引但因为查询时没注意字符集或类型转换索引完全没被用上。还有一次某人习惯了写LIKE %关键词%做模糊搜索数据量大时慢得离谱后面改成全文检索方案才解决。4. 业务接口实现从需求到能用的 API4.1 接口设计与参数校验接口设计这件事我最大的体会是先定契约再写实现。前后端并行开发时如果接口文档是模糊的联调环节就会变成一场灾难。虽然现在的接口文档工具能自动生成文档但前提是代码里的注释写到位。设计接口时有几个原则我一直在用URL 用资源名HTTP 方法表达动作。比如获取内容列表是 GET /contents创建内容是 POST /contents。不要出现 GET /delete_content 这种缝合怪。列表接口必须考虑分页。没有分页的列表接口数据量一大就是隐患。我习惯用页码和每页条数来控制超过上限就截断。创建和更新的字段要明确区分。创建时允许传全部字段更新时往往只允许传部分字段接口上要写清楚实现时用对应的 DTO 去接收而不是整个请求体直接透传给数据库。接口返回值不要直接抛数据库的错误信息。数据库报错对用户来说就是天书你应该把它翻译成业务可读的错误码和提示。参数校验我放在路由的处理链里和业务代码完全分开。定义一个校验规则文件声明每个字段的类型、是否必填、长度范围、枚举值路由进来先校验再进控制器。这样做的好处是业务代码里干净了每个函数都只关心自己该关心的事。一个项目里最容易失控的其实不是接口数量而是错误码管理。我见过有人把错误码写在各个文件里查文档都查不全。我的做法是建一个错误码清单模块统一注册、全局只有这一处定义。新增错误码时按模块分配区间注释里写明场景和返回给前端的提示文案。这样无论后端写接口还是前端做提示查一处就够了。4.2 鉴权方案从 Session 到 Token鉴权是后端绕不开的环节这个项目我用了基于 Token 的认证方案。它的逻辑其实很朴素用户登录时校验账号密码通过后签发一个有一定有效期的 Token 给前端前端请求时把 Token 放在请求头里后端写一个中间件每个受保护接口先验 Token 再放行。选 Token 而不是方案 Session 的原因主要是为了前后端分离和未来可能的多端扩展。手机 App、网页端、第三方开放接口只要验签同一个 Token 生成和校验逻辑就都能接入。Session 方案在“浏览器 服务器同域”的传统场景里很顺但一跨端就麻烦。实操中有几个安全细节值得注意Token 中不要放敏感信息比如密码。它能被解码出来只不过有签名保护、改不了内容。一定要设置过期时间。无期限的 Token 等于把大门钥匙永久交给别人泄漏了都没办法收回。登出功能要么前端丢弃 Token要么后端维护一个黑名单把 Token 拉黑。前者实现简单但有延迟后者需要额外存储开销。我这次选择了前者因为项目复杂度还没到需要实时拉黑的级别。密码存储用的是哈希加盐不用可逆加密。可逆加密意味着能解密回明文一旦密钥泄漏等于明文密码全裸奔哈希是单向的验证时对输入重复哈希比对结果是否一致。加盐的目的是防止两个相同密码产出相同哈希降低彩虹表攻击的风险。注意自己实现的加密和签名逻辑即使自我感觉再良好也不要直接用“手写”方案。用成熟的、经过大量审计的库把密钥管理好比发明新算法安全得多。4.3 连接池与事务边界并发场景的定海神针初学者最容易忽略连接池。数据库连接的建立和销毁开销很大如果不复用每次请求新建、请求结束销毁高并发时数据库直接就崩了。连接池的作用就是维护一批已经建立好的连接谁用谁借、用完归还。连接池的几个参数要理解其含义。池的最大连接数、最小空闲连接数、连接的最大空闲时间、获取连接的超时时间。配置太小高峰期请求排队配置太大数据库资源被撑爆。这个值不能照抄网上的模板要结合你的数据库实例规格和业务流量去调。我的参考是先从数据库可承受的连接上限的 1/3 开始通过压测慢慢往上加。事务边界是另一个重灾区。一次业务操作里涉及到多张表的更新时比如“创建内容”同时要“更新作者发布计数”这两步要么一起成功要么一起回滚。把事务开在服务层的方法上而不是数据库客户端里手写 BEGIN/COMMIT用框架的事务注解或封装好的事务方法即可。这里要留心的坑是事务千万别跨远程调用。比如你在事务里调了一个外部 API外部 API 超时了事务就一直挂着数据库连接被占住不放连接池很快就被耗尽。5. 部署上线最后一公里最考验基本功5.1 环境准备与容器化启动总算到了部署环节。在服务器上我一般不用 Node 直接跑而是用进程守护工具来管。为什么因为 Node 服务如果崩溃了直接跑的方式不会自动恢复。单独配 systemd 服务或用进程守护工具才能做到崩溃自动重启、开机自启、日志统一收集。但比直接裸跑更省心的方案是把整个应用包括数据库、缓存、应用进程全部容器化。用容器编排文件把一堆服务串起来一条命令就把整套环境启动好。环境隔离的好处是在本地能跑通的环境服务器上部署也大概率能跑通不再有“系统版本不一样导致装不上依赖”的苦恼。容器编排文件里要定义的资源包括应用服务构建镜像、映射端口、设置环境变量、声明依赖数据库服务数据卷挂载、账号密码环境变量、端口映射缓存服务持久化配置自动重启策略确保容器挂了能自动拉起来我先在本地跑一遍整套编排文件确认所有服务都能起来、接口能通再上服务器。本地没问题之后服务器上只需要把代码拉下来、准备好环境变量文件、执行启动命令即可。5.2 日志与监控出了问题别靠猜服务上线后最怕的问题就是“用户说报错了但你不知道发生了什么”。日志就是你的案发现场。但日志也不是随便打的打少了查不到线索打多了把磁盘塞满、把关键信息淹没。我这次给日志分了等级调试信息写开发环境生产环境只记录业务关键事件和错误堆栈。日志里必须包含的信息有时间戳、请求 ID、请求路径、请求方法、状态码、耗时、错误堆栈。请求 ID 尤其重要。前端报错时如果能带上这个 ID后端顺着一查就能把这一个请求经过的所有日志串起来。监控方面最基础也最重要的是这三件事健康检查接口告诉负载均衡或运维系统“我还活着”基础资源监控CPU、内存、磁盘、网络错误率与耗时统计接口的成功率、平均响应时间、慢接口排名我遇到过最典型的生产事故是服务日志显示内存持续缓慢上涨几天后 OOM 被系统杀掉。排查后发现是一个静态变量往里面存数据、从不清理。这类问题靠眼很难发现必须有资源监控曲线配合才能定位。所以别等出事了才想起来搭监控上线第一天就把这些配好。5.3 常见部署问题速查部署阶段的问题往往是组合式的我整理了一个清单现象可能原因排查方向接口超时但数据库看起来正常连接池耗尽连接没归还检查连接池监控确认事务是否正常释放能访问但登录总是失败Token 签名密钥不一致检查不同环境的密钥环境变量是否统一静态资源加载慢未配置缓存头加一层 Web 缓存层或静态资源服务容器重启后数据丢失数据卷未挂载确认数据库容器配置了卷映射环境变量改了但没生效配置文件有缓存或容器没重建修改后确认服务重启、容器重新创建这里每一条背后都是我或身边同事真踩过的坑。比如容器重启丢数据就是典型的“容器是临时性”的理解不到位。容器本身是“用完即弃”的数据必须写进持久化存储否则重建容器就是一把梭哈重来。6. 写在最后项目之外的一点体会这份笔记能写出来的部分是技术流程但真正有价值的是流程背后那些被迫想清楚的问题。我从零搭完这个项目后最大的变化是看任何框架文档时不再是被动接受“它帮我做了什么”而是主动去辨识“它在哪一层替我干了活出了问题时我应该去查哪一层”。有几个习惯我想特别建议每写一段代码问自己一句“如果这个模块被删掉系统会不会出问题”。会说明它是核心不会说明它可能设计得不够内聚或者根本不该存在。接口和数据库字段的命名花一分钟想清楚比以后全局重命名省几百分钟。我见过太多 user_name 和 userName 混用的代码库了单个文件里看没什么一全局搜索就头疼。遇到查了半小时还解决不了的问题先把代码放一放重新读一遍报错信息。很多时候答案就在最后一行的英文里只不过被前面一堆无关日志带偏了注意力。最后再分享一个对我帮助很大的小技巧写“开发日志”。不是代码注释也不是周报而是用你自己的话把昨天做了哪些决策、为什么这样选、遇到了哪些问题记下来。三个月后你和别人争论某个设计时这份日志就是最有力的论据。这个项目做完之后你完全可以在它的基础上继续加东西比如引入消息队列做异步处理、增加单元测试和接口测试、加上持续集成和持续部署。每加一层都是对之前设计的验证和修正。后端这条路不怕走得慢就怕一直停留在看教程的阶段动手的那一刻才是真正开始的时刻。