企业官网建设流程全解析

Unleash架构拆解：Express+TypeScript+PostgreSQL后端是如何构建的

【免费下载链接】unleashOpen-source feature management platform项目地址: https://gitcode.com/GitHub_Trending/un/unleash

Unleash 是一款广受欢迎的开源特性管理（Feature Flag）平台，它的后端完全由Express + TypeScript + PostgreSQL构建。本文将带你从零拆解这套后端架构：启动流程、中间件链、Controller → Service → Store 三层设计，以及数据库迁移机制，帮助新手快速理解这个生产级 Node.js 项目是如何搭建的 🚀

一、整体架构一览：先看清全貌

在深入代码之前，先看一张官方架构图。Unleash 的云端 API 同时对外提供三套接口：ADMIN API（管理界面调用）、CLIENT API（后端 SDK 拉取配置）和FRONTEND API（浏览器/移动端 SDK 调用），评估逻辑都在客户端本地完成，用户数据不会回传给 Unleash 实例 🔒

整个后端源码集中在src/目录，其中src/lib/是核心，包含routes/（路由）、services/（业务）、db/（数据访问）、middleware/（中间件）等模块，目录即架构。

二、启动流程拆解：从一行代码到完整服务

2.1 入口文件：小到不能再小

服务入口 src/server.ts 只有寥寥数行——它只做一件事：调用start()并捕获错误。所有"重活"都委托给了 src/lib/server-impl.ts。

2.2 start()：迁移优先，应用在后

在 src/lib/server-impl.ts 中，start()的执行顺序非常清晰：

1. 创建配置：createConfig(opts)把环境变量、数据库连接等整理成统一的IUnleashConfig对象（见 src/lib/create-config.ts）
2. 等待特性解析器就绪：Unleash 用 Feature Flag 管理自己（dogfooding）
3. 执行数据库迁移：调用 src/migrator.ts 中的migrateDb()，多实例部署时还会通过withDbLock加数据库锁，防止并发迁移冲突
4. 构建应用：createApp()按固定顺序组装——createDb→createStores→createServices→getApp
5. 优雅关闭：通过stoppable包装 HTTP 服务器，关闭时依次停止调度器、销毁连接池

这套"工厂方法 + 依赖注入"的写法还带来一个好处：测试时可以整体替换createDb、createStores等工厂，注入内存版的 Fake Store，无需真实数据库。

三、Express 中间件链：请求是如何被层层过滤的

getApp()在 src/lib/app.ts 中构建 Express 应用。它的中间件顺序本身就是安全设计的说明书：

这些中间件全部位于 src/lib/middleware/，认证方式（开源版、企业版、自定义、Demo）通过switch分支挂载不同实现，扩展性很强。

路由聚合在 src/lib/routes/index.ts，四类 API 一目了然：

• /api/admin—— 管理端接口（AdminApi）
• /api/client—— 后端 SDK 接口（ClientApi）
• /api/frontend—— 前端 SDK 接口
• /edge—— 边缘节点同步接口

最后还有一个 SPA 兜底路由：所有非 API 路径都返回前端index.html，让 React 路由接管前端跳转。

四、三层架构：Controller → Service → Store

官方在后端概览 contributing/backend/overview.md 中明确了后端遵循CSR 模式（Controller、Service、Repository/Store），这也是整个项目最值得学习的设计：

1. Controller（路由层）：负责解析请求参数、校验入参（基于 AJV Schema）、调用 Service、组装响应，本身不写业务逻辑
2. Service（业务层）：位于 src/lib/services/，处理权限检查、业务规则、事件发布（通过 eventBus 广播审计事件）
3. Store（数据层）：位于 src/lib/db/，是唯一直接接触 SQL 的地方

Store 的集中工厂在 src/lib/db/index.ts——createStores()一次性实例化 70 多个 Store（FeatureToggleStore、ProjectStore、SegmentStore、AccessStore……），统一注入db（Knex 实例）和eventBus，再整体交给 Service 层使用。这种"读模型（ReadModel）+ 写模型（Store）分离"的做法在 contributing/ADRs/back-end/write-model-vs-read-models.md 中有专门讨论，复杂查询走只读模型，避免读写互相干扰。

五、PostgreSQL 数据层：Knex 连接池 + db-migrate 迁移

5.1 数据库连接：Knex 托管连接池

连接池封装在 src/lib/db/db-pool.ts，仅十几行代码：以pg为客户端创建 Knex 实例，把日志接入 Unleash 的 Logger，并支持自定义searchPath（schema）。所有 Store 共享这一个连接池，事务由 src/lib/db/transaction.ts 提供的withTransactional/withRollbackTransaction统一封装。

5.2 数据库迁移：100+ 个迁移文件讲述项目历史

contributing/backend/overview.md 要求PostgreSQL 14.0+和Node.js 22.0+。所有表结构变更都在 src/migrations/ 目录下以db-migrate文件记录，从 2014 年的20141020151056-initial-schema.js一直到最新的 API Token v2、Safeguards 等，超过100 个迁移文件——翻一翻这些文件名，等于读了一遍 Unleash 的产品演进史 📜

开发规范也很严格：已合并的迁移绝不修改，需要回滚时只能写一个新迁移来"反转 + 重建"，保证了多版本实例混跑时的数据库兼容性。本地可用 docker/local-postgres/ 下的一键 Docker 配置快速起库。

5.3 管理界面：三层架构的最终呈现

前端 SPA 通过/api/admin调用后端，最终呈现为这样一个特性列表管理界面——项目、环境、策略、版本控制都在这里闭环：

六、快速上手：本地跑通 Unleash 后端

只需三步就能把这套 Express + PostgreSQL 后端跑起来 🏃

1. 用docker compose -f docker-compose.postgres.yml up -d启动本地 PostgreSQL 14
2. 执行pnpm install安装依赖（项目使用 pnpm 工作区管理）
3. 运行pnpm dev，访问http://localhost:3000即可看到管理界面，API 位于/api/下

想继续深挖？推荐按顺序阅读：contributing/developer-guide.md 了解开发约定，contributing/ADRs/back-end/ 下的 ADR（架构决策记录）解释"为什么这么设计"，比如命名规范、REST API 指南和 SQL 编写标准。

写在最后

回顾一下 Unleash 后端的架构精髓：入口极简、启动时迁移优先、中间件链即安全策略、CSR 三层解耦、Store 工厂集中管理数据访问、db-migrate 守护数据库演进。这是一个"小而美"却高度规范的生产级 Express + TypeScript + PostgreSQL 项目，非常适合作为学习现代 Node.js 后端架构的样板。

【免费下载链接】unleashOpen-source feature management platform项目地址: https://gitcode.com/GitHub_Trending/un/unleash