极简后端骨架SIMPL：唯一入口、隐式布局与最小依赖

做基础架构这行十来年，我经手过不少“极简框架”，大多数最后都变成了“极简到只有作者自己会用”。所以第一次看到 SIMPL 这个名字的时候，我是带着偏见的——又是个把 Simple 少写一个 e 就想上热搜的项目。真正让我改变看法的是它解决的问题很具体：当团队从 3 个人涨到 12 个人，当项目从单体拆到 6 个服务，原本那套“约定俗成”的东西会迅速失效，每个人都在自己的分支上发明目录结构、发明配置加载顺序、发明错误码规范。SIMPL 想干的事情就是把这类“发明权”收回，用一套最小但不可协商的约定，把项目骨架固定下来，让新人第一天就能猜到代码在哪、配置从哪读、请求怎么进来又怎么出去。这套东西适合两类人：一是正在维护一个“人人都能改、没人敢删”的老项目、想找机会收敛结构的人；二是准备起一个新服务、不想再重复搭脚手架的人。下面我按自己落地一遍的完整过程来讲，包括设计取舍、核心实现、参数计算和踩过的坑，你可以直接照着抄，也可以只挑其中一两块用。

1. 为什么我要重做一套叫 SIMPL 的骨架

1.1 三次重构失败换来的教训

先说动机，不然讲实现就是耍流氓。我上一个项目的脚手架经历过三次“重构”，每次都以失败告终。第一次是加了一层“通用配置中心”，结果所有配置都往一个 800 行的 YAML 里塞，改一行要跑一遍全量回归；第二次是引入依赖注入容器，容器本身很强大，但团队里一半人搞不清生命周期，查一个“为什么这个对象是旧的”能查一下午；第三次最离谱，我们做了一套“插件化自动注册”，靠扫描目录加装饰器实现，结果构建产物从 400KB 涨到 3.2MB，冷启动从 300ms 涨到 2.1 秒，最后被运维直接打回。

三次失败有个共同点：我们都在做加法。每次遇到问题，第一反应是“加一个抽象层把它包起来”，但抽象层本身也是要维护的代码，而且抽象层越多，理解成本越高。SIMPL 的第一条设计原则就是从这来的：任何为“未来可能的需求”预留的扩展点，一律不做。听起来很激进，但实测下来，我们这套骨架从立项到能跑通完整业务链路，只用了 9 个源文件、约 700 行核心代码，新人上手平均 40 分钟。

这里有个判断标准值得分享。当一个“扩展点”被提出时，我会问三个问题：现在有几个地方真的需要它？如果只有一个，就写成普通函数；半年内会不会出现第二个？答不上来就先不做；做了之后如果不用，删掉要多久？如果要改 5 个文件才能删，那它就不该存在。这三个问题帮我砍掉了八成“看起来很专业”的设计。

1.2 SIMPL 的三条不可协商底线

SIMPL 这个名字是我硬凑的，但拆开正好对应三条底线：Single entry（唯一入口）、Implicit layout（隐式布局）、Minimal deps（最小依赖）。这三条是不能商量的，其他都可以谈。

唯一入口的意思是整个应用只有一个启动文件，所有初始化动作——加载配置、注册路由、装配依赖、挂载中间件、启动监听——都在这一个文件里按固定顺序发生，不允许在别的地方偷偷init。好处很直接：排查“服务为什么起不来”的时候，你只需要看一个文件，不用满仓库找谁先执行了谁。

隐式布局的意思是目录即约定，文件路径即路由/模块标识。比如src/api/user/detail.ts就自动映射到/api/user/detail，不需要额外写注册代码。这一条牺牲了一点点灵活性（比如你想让 URL 和文件路径不一致，就得在文件里显式覆盖），换来的是“找代码不用问人”。

最小依赖的意思是核心运行时只允许引入零个第三方运行时包，工具链侧（构建、测试）可以放宽。这条是最多人反对的，理由通常是“自己写不如用现成的稳”。我的回应是：核心链路自己写，出问题你能修；第三方库出问题你只能等。实测我们最终的核心运行时依赖数为 0，构建产物 gzip 后 38KB，容器镜像从 620MB 降到 78MB。

2. SIMPL 的整体结构与请求生命周期

2.1 目录结构：把“猜”这件事从协作里删掉

目录长这样，一共四层，不允许再加第五层：

src/ main.ts 唯一入口 config/ default.json 默认配置 pipeline/ 中间件，按文件名排序执行 api/ 路由，路径即 URL user/ detail.ts list.ts core/ 框架自身，业务代码禁止 import router.ts container.ts context.ts

关键点在于core/这个目录业务代码不能直接引。我加了一条 lint 规则做强制：src/api/**和src/pipeline/**里出现对core/的直接导入就报错，必须通过main.ts注入进来的ctx间接使用。这条规则拦住了大量“某个业务文件为图省事直接调底层工具”的写法，保证了核心层可以独立替换。

还有一个细节：pipeline/的中间件按文件名排序执行，所以我强制文件名带两位数字前缀，比如10-trace.ts、20-auth.ts、30-validate.ts、90-error.ts。这个设计是我从一次线上事故里学的——当时两个中间件的执行顺序依赖import的书写顺序，有人调整了一下 import 顺序做代码格式化，鉴权就跑到了日志前面，出问题时日志里完全看不到被拒绝的请求。用文件名排序之后，顺序变成了可见的、可 diff 的、写在纸面上的东西。

2.2 一次请求在 SIMPL 里经过的五个站点

很多人写框架文档喜欢画图，我这儿没有图，直接列五个站点，每个站点的职责和你能插手的地方说清楚：

站点一，入口解析。请求进来先过context.ts，把原始请求包装成一个ctx对象，里面放method、path、query、params、body、traceId、state。state是个空对象，专门给中间件之间传值用，比如鉴权中间件把用户信息塞进ctx.state.user，后面业务代码直接读。这一步不做任何校验，纯包装，耗时控制在 0.05ms 以内。

站点二，管道执行。按文件名顺序跑中间件，洋葱模型，每个中间件可以决定是await next()继续往下，还是直接返回结束。这里有个我踩过的坑：洋葱模型下，next()之后写的代码是在响应返回后执行的，很多人会在这里改ctx.body，改不动，因为响应已经发出去了。我在ctx上加了一个committed标记，试图在提交后改 body 会直接抛错，把这种隐性 bug 变成显性报错。

站点三，路由匹配。匹配靠一张预编译的路由表，启动时由router.ts扫描api/目录生成。支持静态段、[id]动态段、[...rest]通配段三种，优先级是静态 > 动态 > 通配。路由表匹配用的是逐段比对加首段哈希索引，实测 200 条路由下平均匹配耗时 3μs 左右。

站点四，处理器执行。业务函数签名固定为(ctx) => Promise<void>，返回值忽略，所有输出必须写ctx.body。这一条是为了避免“有人 return 对象、有人 return Response”的混乱。处理器内部抛出的任何错误都会被管道最外层的错误中间件接住。

站点五，响应序列化。根据ctx.type走不同的序列化器，默认 JSON。序列化器可替换，但我们只内置了 JSON 和文本两种，别的自己写。

2.3 配置三层覆盖与优先级计算

配置这块我设计了三层：default.json打底，env/{NODE_ENV}.json覆盖，local.json最后覆盖（且必须 gitignore）。合并是深合并，数组不合并直接替换——这条我犹豫过，最后选替换是因为数组深合并的行为几乎没人能预测对，尤其是对象数组，合并出来往往是四不像。

优先级规则简单说就是后加载的赢。但有个例外：任何以__开头的键不参与合并，只能在local.json里出现，主要用于本地调试开关。这样做是为了防止有人把本地调试开关不小心提交到env/里带到线上。

配置读取走一个get(path, fallback)函数，路径用点号分隔，比如get('db.pool.max')。这里有个性能细节：每次get都做字符串切分和对象遍历，热路径上调用多了会有点开销。我的做法是在启动时把整份配置扁平化成一张Map<string, value>，get直接查 Map，实测 10 万次调用从 42ms 降到 6ms。扁平化之后丢掉的是“引用语义”，也就是你拿到的是值的拷贝，改它不会影响原配置——这恰好也是我想要的，防止某个业务模块偷偷改全局配置。

3. 核心环节实现：从空目录到能接流量

3.1 唯一入口的初始化顺序

main.ts的初始化顺序是写死的，不允许调换，顺序如下：加载配置 → 初始化日志 → 建容器 → 注册路由 → 装配管道 → 启动监听 → 注册退出钩子。为什么顺序不能换？举个具体的：日志必须在容器之前初始化，因为容器在装配依赖时如果某个依赖构造失败，得能打日志出来；路由必须在管道之前，因为管道里有些中间件需要读路由元信息（比如鉴权要知道这个路由需要什么权限级别）。

// src/main.ts import { loadConfig } from './core/config' import { createLogger } from './core/logger' import { createContainer } from './core/container' import { buildRouter } from './core/router' import { buildPipeline } from './core/pipeline' import { createServer } from './core/server' async function bootstrap() { const config = loadConfig(process.env.NODE_ENV ?? 'dev') const logger = createLogger(config.get('log.level')) const container = createContainer({ config, logger }) const router = await buildRouter('./src/api', container) const pipeline = await buildPipeline('./src/pipeline', container) const server = createServer({ config, logger, router, pipeline }) await server.listen(config.get('server.port')) logger.info('server.started', { port: config.get('server.port') }) const shutdown = async (signal: string) => { logger.info('server.stopping', { signal }) await server.close({ timeoutMs: 10000 }) process.exit(0) } process.on('SIGTERM', () => shutdown('SIGTERM')) process.on('SIGINT', () => shutdown('SIGINT')) } bootstrap().catch((err) => { console.error('bootstrap.failed', err) process.exit(1) })

注意server.close我给了 10 秒超时。这个值不是拍脑袋来的：我们的长请求 P99 在 3.2 秒左右，10 秒大约留了 3 倍余量，既能等大部分请求跑完，又不至于让滚动发布卡太久。如果你的服务里有耗时更长的任务，比如导出报表，那就得把这个值往上调，或者干脆把长任务挪到异步队列里，别让 HTTP 进程背着。

3.2 四十行依赖容器够不够用

容器我只实现了三个能力：注册单例、按 token 取实例、构造函数注入。没有作用域，没有懒加载代理，没有循环依赖检测（检测靠启动时一次性全量解析，解析不出来直接崩，反而更早暴露问题）。

// src/core/container.ts type Factory<T> = (c: Container) => T | Promise<T> export function createContainer(seed: Record<string, unknown> = {}) { const factories = new Map<string, Factory<unknown>>() const instances = new Map<string, unknown>() const container = { register<T>(token: string, factory: Factory<T>) { if (factories.has(token) || instances.has(token)) { throw new Error(`duplicate registration: ${token}`) } factories.set(token, factory as Factory<unknown>) return container }, async resolve<T>(token: string): Promise<T> { if (instances.has(token)) return instances.get(token) as T const factory = factories.get(token) if (!factory) throw new Error(`unknown token: ${token}`) const value = await factory(container) instances.set(token, value) return value as T }, has(token: string) { return factories.has(token) || instances.has(token) }, } for (const [k, v] of Object.entries(seed)) instances.set(k, v) return container }

重名注册直接抛错这一条很关键。早期版本是“后注册的覆盖前面的”，结果有次两个模块都注册了cache，后注册的把前面那个带 10 分钟 TTL 的缓存顶掉了，换成了一个默认 60 秒的，线上缓存命中率从 94% 掉到 61%，查了三个小时。改成抛错之后，这种问题在启动阶段就炸了，一秒钟定位。

还有resolve是异步的，因为有些依赖（数据库连接池）需要 await。代价是所有取依赖的地方都要await。我权衡过要不要做同步容器，最后放弃了，因为同步容器意味着依赖构造不能有 IO，而现实里几乎不可能。

3.3 中间件管道与状态传递

管道实现本身很短，难的是约定。我的约定是：中间件只能通过ctx.state传值，不允许用模块级变量。这条听起来废话，但真有人这么干——之前有个中间件把解析出来的用户信息存在一个模块级let currentUser里，单测全过，一上并发就串号，查了两天才发现。

// src/core/pipeline.ts export type Middleware = (ctx: Ctx, next: () => Promise<void>) => Promise<void> export function compose(middlewares: Middleware[]) { return function run(ctx: Ctx): Promise<void> { let index = -1 const dispatch = async (i: number): Promise<void> => { if (i <= index) throw new Error('next() called multiple times') index = i const fn = middlewares[i] if (!fn) return await fn(ctx, () => dispatch(i + 1)) } return dispatch(0) } }

next()被调用两次就抛错，这个检查帮我抓到过两次手误。还有个细节是dispatch用的是递归而不是循环，中间件数量多的时候（我们最多挂过 14 个）会不会栈溢出？实测不会，14 层嵌套对 V8 来说毫无压力，几百层才有风险，而正常项目不会挂几百个中间件。

写中间件有个我总结的经验：能写成处理器内部函数的，就别写成中间件。中间件适合三类事——横切所有路由的（日志、traceId、错误捕获）、需要提前中断的（鉴权、限流）、需要修改响应的（压缩、CORS）。业务逻辑塞中间件是最常见的滥用，比如“给订单接口加个参数校验”，这就该写在处理器里，写成中间件之后下一个接口要复用你还得想办法把它绕过去。

3.4 错误处理：把错误码变成可搜索的东西

错误对象我定了一个最小结构：{ code, message, status, traceId, detail? }。code用大写下划线字符串，比如USER_NOT_FOUND，不用数字。理由是数字错误码在日志里 grep 的时候，很容易和业务 ID、时间戳混在一起，字符串码可搜索性好得多。

错误中间件放在管道最后（文件名90-error.ts），捕获所有下游抛出的异常，做三件事：如果是已知的业务错误，原样序列化；如果是未知异常，包成INTERNAL_ERROR并把原始堆栈打到日志；无论哪种，都带上traceId返回，方便用户报障时直接给这个 ID。

这里有个实用技巧：traceId我是在最外层生成的，用时间戳 + 随机数，然后通过响应头X-Trace-Id返回。前端同学报障时只要贴这个头，我就能在日志里精确定位到那一次请求的全部日志。这个改动看着小，实际把我们的平均排障时间从 25 分钟压到了 6 分钟左右。

还有个坑要提醒：错误中间件必须能处理“响应已提交”的情况。比如处理器已经写了一部分响应，然后抛错了，这时候你再往里写 JSON 就会报headers already sent。我的做法是判断ctx.committed，已提交就只记日志不写响应，同时主动断开连接，让客户端感知到异常。

3.5 构建与产物裁剪

构建用的是 esbuild，配置里最值得说的两件事：一是external要精确列出原生模块，漏一个就会在打包时报错，多列一个就会在运行时找不到；二是treeShaking要有意识地配合代码写法，比如避免在模块顶层做副作用操作，否则整个模块都摇不掉。

// build.mjs import { build } from 'esbuild' await build({ entryPoints: ['src/main.ts'], bundle: true, platform: 'node', target: 'node20', format: 'esm', outfile: 'dist/main.mjs', minify: true, sourcemap: true, external: ['pg-native', 'bufferutil', 'utf-8-validate'], metafile: true, logLevel: 'info', })

metafile: true这个开关建议一直开着，它会在构建时产出每个模块的体积明细。我们靠它发现有个工具函数文件因为一行console.log在顶层，导致整个 210KB 的工具库都被打进产物。删掉那行之后产物直接掉了 180KB。这种事不看明细根本发现不了，因为代码里你完全看不出那行console.log有什么问题。

镜像这块我的做法是多阶段构建，构建阶段装全量依赖，运行阶段只拷dist/和node_modules里运行时真正需要的部分。因为我们核心运行时零依赖，最终镜像只有基础层加 200KB 代码，78MB。冷启动从 2.1 秒降到 280ms，主要省的就是模块加载和文件系统扫描。

4. 实操：把 SIMPL 套到一个真实的小服务上

4.1 初始化和第一条路由

假设我要做一个“短链服务”，四个接口：创建短链、跳转、查统计、删短链。按 SIMPL 的约定，目录直接长成这样：

src/api/link/ create.ts POST /api/link/create [code].ts GET /api/link/:code [code]/ stats.ts GET /api/link/:code/stats delete.ts DELETE /api/link/:code/delete

注意[code].ts和[code]/目录可以共存，前者匹配单段，后者匹配子路径。这个规则一开始团队里有人搞混，我加了启动时的路由表打印，log.level=debug时会打出完整路由表，一眼就能看出映射对不对。

路由文件必须导出一个meta和一个默认处理器：

// src/api/link/create.ts export const meta = { auth: 'required', rateLimit: { window: 60, max: 30 }, } export default async function createLink(ctx: Ctx) { const { url, ttlDays = 7 } = ctx.body ?? {} if (typeof url !== 'string' || !/^https?:\/\//i.test(url)) { throw businessError('INVALID_URL', 400, 'url must start with http(s)') } const code = await ctx.state.linkService.create(url, ttlDays) ctx.status = 201 ctx.body = { code, shortUrl: `${ctx.state.origin}/api/link/${code}` } }

meta是给中间件读的，鉴权中间件读auth，限流中间件读rateLimit。这样写的妙处是：一个接口需要什么权限、限流多少，全部写在接口文件里，review 的时候一眼能看到，不用去翻中间件配置。之前那种集中式配置的做法，加一个新接口经常忘了加限流，事后完全看不出来。

4.2 限流参数是怎么算出来的

限流这块我算得比较细，因为上线第一周就被刷过。我们的场景是创建接口，正常用户一分钟最多建 3 到 5 条，异常流量能到每分钟 2000 次。

先定窗口和阈值。窗口选 60 秒是因为太短容易被突发流量误伤，太长则响应不及时。阈值我按“正常峰值 × 6”来定：正常峰值假设 5 次/分钟，乘以 6 得 30。为什么是 6 而不是 3 或 10？因为我们观察到正常用户里最活跃的那批（做运营批量导入的）大概在 15 到 18 次/分钟，30 给了他们接近 2 倍的余量，而恶意刷单是千级别，30 和 300 对它们的拦截效果没差别，索性定低一点。

再算存储成本。限流用滑动窗口，每个 key 存一个时间戳数组。假设日活 5 万，每人平均 8 次请求，一天 40 万个 key，每个 key 平均存 3 个时间戳（8 字节），加上 key 本身约 32 字节，总内存约 40 万 × 56 字节 ≈ 22MB。这个量级单机内存完全扛得住，不需要引入外部存储。如果日活涨到 500 万，内存会到 2.2GB，那时候就得上 Redis 了——我把这个阈值写进了代码注释，方便后面的人知道什么时候该换方案。

实测压测数据：单实例、4 核、限流中间件全开的情况下，纯跳转接口 QPS 3200，P99 12ms；创建接口因为要写库，QPS 780，P99 28ms。这个数据是用 50 并发、持续 30 秒测出来的，测试期间 CPU 峰值 68%，内存稳定在 96MB，没有明显抖动。50 并发这个值是根据我们预估的峰值流量反推的：预估峰值 QPS 600，按单请求平均耗时 30ms 算，需要的并发数是 600 × 0.03 = 18，取 50 是留了接近 3 倍余量。

4.3 上线前做的三件小事

第一件是加了启动自检。main.ts里在listen之前跑一遍自检：配置必填项是否齐全、路由表是否为空、容器里关键 token 是否都能解析出来。自检失败直接退出，不让进程带病启动。这一步拦住的典型问题是“配置文件漏了个字段，服务起来了但第一次请求才炸”，那种问题在滚动发布时特别难定位，因为老实例还是好的，新实例偶发失败。

第二件是把所有console.log换成了结构化日志。日志字段固定为ts、level、event、traceId、extra。event用点号命名，比如link.created、link.redirect.hit。结构化之后，日志平台上的聚合查询就好写了，比如“过去一小时link.redirect.hit的数量按 code 分组取 Top 10”，直接出结果，不用写正则。

第三件是准备了一份回滚清单。因为我们是滚动发布，回滚不是简单地把镜像换回去，还要考虑数据兼容。清单里写了：新版本加了哪些字段、这些字段是否可为空、旧版本读到新字段会不会崩。这份清单逼着我们在设计时就想清楚向前兼容，而不是上线后再补。

5. 常见问题与排查实录

5.1 问题速查表

下面这张表是我们团队三个月里真实遇到并记录下来的，按出现频率排序：

5.2 三个印象最深的坑

第一个坑是 JSON 配置里的数字精度。我们在配置里写了一个idBase: 9007199254740993，JSON.parse 之后变成了9007199254740992，因为超出了安全整数范围。这个 bug 极其隐蔽，因为配置读出来是个数字，看起来完全正常，只是末位差 1。最后是把所有可能超范围的大整数配置项统一改成字符串，用的时候再BigInt()。教训是：JSON 不是万能的配置格式，涉及大整数、日期、正则的场景，要么用字符串，要么换个格式。

第二个坑是中间件里的异步错误没被捕获。有个中间件这么写：setTimeout(() => { throw new Error('x') }, 0)，这个错误抛在了 Promise 链之外，错误中间件根本接不住，直接导致进程崩溃。后来我们在入口加了process.on('unhandledRejection')和uncaughtException兜底，只记日志不退出（因为我们的服务是无状态的，重启代价低，但保留现场更重要）。同时定了一条规矩：中间件里禁止裸用setTimeout，需要延迟执行就用await sleep()。

第三个坑是优雅退出时的连接泄漏。我们用了数据库连接池，server.close()只关了 HTTP 监听，连接池没关，进程挂着不退出，容器编排那边等超时之后强杀，导致正在执行的写操作被中断。修法是退出流程里加了一步：先停止接收新请求，等存量请求跑完，再依次关闭连接池、关闭日志、退出进程。顺序不能乱，日志必须最后关，不然前面的关闭过程就没日志可看了。

5.3 几条不太容易想到的经验

不要给路由加版本号前缀然后复制一整套代码。我们最早的方案是/api/v1/和/api/v2/两套目录，结果改一个 bug 要改两遍，还经常漏。后来改成在处理器内部做分支判断，路由只有一套，靠meta.version和请求头里的版本标识分流。代码量少了一半，漏改的问题也消失了。

不要在容器里注册“配置对象”这种大而全的东西。早期我把整份配置注册成configtoken，结果每个模块都去config.get('xxx')，依赖关系完全看不见。后来改成按模块注册细粒度依赖，比如dbPool、cacheClient、linkService，每个依赖内部自己去读它需要的配置。这样一看构造函数参数就知道这个模块依赖什么，比读代码强。

不要迷信“零依赖”到走火入魔。我们砍到零依赖之后，发现有两个地方自己写反而更麻烦：一个是 HTTP 服务器本身，一个是 JSON 序列化。前者我们最后用了平台内置的能力，后者用了JSON.stringify。真正被我们砍掉的是那些“只用一两个函数却带进来一堆传递依赖”的库。判断标准很简单：如果你只需要那个库 5% 的功能，就自己写那 5%。

这个项目后续如果继续演进，我大概会往两个方向走：一是把自检做得更细，做成可插拔的检查项，让每个业务模块自己声明需要检查什么；二是把路由表做成可视化输出，启动时生成一份静态 HTML，方便新人快速了解整个服务的接口全貌。这两件事都不急，因为现在这套东西已经够用，而够用的东西就不该动。

我在实际落地里最深的一点体会是：极简不是少写代码，而是让每一行代码的存在理由都清楚。一个 700 行的骨架比一个 7000 行的框架难写得多，因为你必须对每一个“要不要加”说不。真正让团队效率提升的从来不是功能多，而是所有人对同一件事的理解一致——文件在哪、配置怎么读、错误怎么抛，这些事一旦不需要讨论，省下来的时间才是实打实的。