Stanza：自然语言秒变状态化Mock API

什么是 Stanza

Stanza 是一个生产就绪的开源开发者工具，能将自然语言描述即时转化为可用的、带状态的模拟 REST API 端点。你只需输入类似“生成 20 个在线用户，包含 id、姓名、头像和最后活跃时间”的描述，Stanza 就会解析提示词、生成定制化的数据结构蓝图，并动态提供一个实时可调用的接口。

Stanza 项目截图

这个工具面向前端开发者和独立黑客，帮助他们在真实后端尚未就绪时快速原型化应用。据其作者介绍，Stanza 支持完整的 CRUD 操作（GET、POST、PUT、DELETE），并允许通过查询参数模拟人工延迟（如 ?delay=5000）和自定义状态码（如 ?status=500），让前端开发更贴近真实环境。

核心功能：不只是静态 Mock

Stanza 定位为“状态化”的 mock 服务，意味着它生成的数据并非一次性快照，而是可以持续交互的。你可以对生成的资源执行增删改查，数据会随之变化。这对于需要演示多步骤流程、测试分页逻辑或验证错误处理的前端项目尤为实用。

其内置的数据模拟能力也值得关注。据项目说明，Stanza 结合了 @faker-js/faker 和递归模式生成器，能够填充深层嵌套的 JSON 结构、子对象和数组，而无需依赖封闭 API 的令牌配额。这意味着开发者可以一次性生成包含复杂关联关系的数据集，例如带嵌套聊天记录和参与者数组的用户资料。

状态化（Stateful）Mock 与无状态 Mock 的区别：无状态 mock 每次请求返回相同或随机生成的数据，适合验证 UI 渲染，但无法模拟“创建后能查到”“删除后 ID 失效”等真实业务链路。状态化 mock 则在内存或数据库中维护一份可变的数据集合，POST 新增的记录会被后续 GET 读取，PUT 修改会持久反映在响应中。Stanza 正是把生成的数据存入 MongoDB 集合，因此跨请求的状态是一致的。这使得它可用于测试分页游标推进、乐观更新回滚、幂等性等依赖前后序列状态的逻辑，而这类测试通常只能等真实后端或搭建完整 mock server 才能进行。

@faker-js/faker 是一个纯 JavaScript/TypeScript 的假数据生成库，是经典 faker.js 的社区维护分支。它提供姓名、地址、邮箱、URL、UUID、公司名、日期等数十类生成器，支持多语言 locale 和可复现的随机种子。与调用外部数据 API 相比，faker 在本地同步生成，没有网络往返和配额限制，因此适合在一次请求中批量填充成千上万条记录。当它与递归模式生成器结合时，可以按照 JSON Schema 的层级逐层生成对象与数组，从而构造出深层嵌套的结构。

技术架构解析

Stanza 的技术栈围绕性能和零成本扩展进行设计，几个关键决策体现了作者的工程取舍。

AI 蓝图引擎

Stanza 使用开放权重模型（如 qwen/qwen3.8-27b）通过 Groq 进行推理，并强制 JSON 输出模式，从自然语言提示中提取精确的模式结构和记录数量。这种设计保证了高频、低延迟的 JSON 抽取，同时避免了对单一闭源 API 的依赖。作者在原文中强调，开放权重模型提供了完整的架构控制权、零供应商锁定，并且可以构建本地回退启发式层，确保外部 AI 节点出现限流或冷启动时应用不会崩溃。

开放权重模型（Open-weight Model）与开源模型不完全等同：开放权重指模型参数可以公开下载并自行部署，但训练数据、训练代码或许可证可能并不完全开放。对开发者工具而言，关键收益是推理可以在自托管或第三方托管商之间迁移，不被单一 API 供应商绑定。文中提到通过 Groq 推理，Groq 是一家以 LPU 硬件提供极低延迟推理的服务商，其优势在于首 token 延迟和每秒输出 token 数，恰好契合“把一句自然语言快速转成 JSON 模式”这种短输入短输出的高频调用。

强制 JSON 输出模式（Structured Output / JSON Mode） 是让模型保证返回合法 JSON 的机制，通常通过约束解码（constrained decoding）实现：在每一步采样时屏蔽掉会破坏 JSON 语法的 token。相比在提示词里写“请只返回 JSON”再事后解析，约束解码能避免模型输出解释性文字或多余逗号导致解析失败，对需要程序化消费模型输出的管道至关重要。这也是 Stanza 能把自然语言稳定映射为字段结构的前提。

回退启发式层（Fallback Heuristic） 指当主 AI 调用失败、限流或超时时，用规则化的本地逻辑兜底，例如基于关键词匹配常见字段名（id、name、avatar）或套用默认模板生成模式。它牺牲一定的语义理解能力，换取可用性，避免整个工具因外部依赖抖动而不可用。

本地数据填充与数据库层

生成数据填充由本地库完成，而非调用外部 API，这显著降低了使用成本。数据库层使用 MongoDB Atlas，采用单文档收集策略并利用 TTL 索引（expiresAt）自动过期和清理临时 mock 端点。每个 mock 端点的生命周期可从几分钟到 48 小时不等，这既避免了免费套餐的集合数量限制，也保持了资源使用的洁净。

MongoDB TTL 索引 是一种特殊索引，可在文档的某个日期字段到达指定时间后由后台线程自动删除该文档。创建时需在 expiresAt 字段上建立 expireAfterSeconds: 0 的 TTL 索引，文档便会在该时间点过后被清理。需注意 TTL 后台任务通常每 60 秒左右运行一次，因此删除并非精确到秒，但这对于临时 mock 端点已足够。相比自己写定时任务扫描并删除，TTL 索引把清理责任交给数据库，减少了应用侧的状态管理。

单文档收集策略（Single-Collection Strategy） 指不为每个 mock 端点新建一个集合，而是把所有端点的记录放在同一集合中，用类似 endpointId 的字段区分。这样做的好处是绕开 MongoDB Atlas 免费层对集合数量的限制，同时避免大量小集合带来的元数据开销；代价是查询必须始终带上端点标识，且需要为常用过滤字段建立复合索引。配合 TTL 索引按 expiresAt 清理，整个临时数据的生命周期就形成了闭环。

模拟基础设施中间件

内置的中间件处理器负责响应延迟钳制和动态 HTTP 状态码覆盖。这两项功能看似简单，却能让前端开发者轻松测试加载状态、超时处理和错误边界，而这些场景在真实后端开发中往往难以快速复现。

开源模型为何是关键

Stanza 的作者专门讨论了开放创新对项目的意义。构建一个从提示到模式的翻译引擎，需要高频、低延迟的 JSON 提取，开放权重模型让团队能够完全掌控解析管道的细节。如果使用闭源 API，不仅会受到定制化限制，还会为这样一个开发者工具带来沉重的经常性成本。

这背后反映了一个更广泛的趋势：AI 原生工具开始将开放模型作为默认选择，尤其是在需要大量重复调用且对成本敏感的开发者工具领域。Stanza 通过本地回退启发式层进一步增强了鲁棒性，这种“开放模型 + 本地兜底”的架构模式，或许会成为小型 AI 工具的常见范式。

使用场景与获取方式

Stanza 适合以下场景：前端原型开发、API 契约测试、演示环境搭建、教学示例创建。项目已部署在 Vercel 上，代码以 AGPL-3.0 许可证开源。

一个快速测试示例是：生成“20 个在线用户，包含 id、姓名、头像和最后活跃时间”的 mock 端点，然后通过 ?delay=2000&status=200 调用它，观察延迟和状态码的模拟效果。开发者可以访问 GitHub 仓库获取完整代码，或直接使用在线演示版本体验。