Acorn
Oak 团队打造、内置 Schema 验证的跨运行时 RESTful JSON 服务框架。
项目概述
Acorn 以一个专注的 Router 覆盖 JSON API 的路由、验证、状态响应与日志需求，可运行在 Deno、Node.js、Bun 和 Cloudflare Workers。
这里的 Acorn 指 Oak 团队维护的 RESTful 服务框架，而不是同名的 JavaScript Parser。它围绕 Router 和 Web 标准 Request/Response 构建，目标是用较少样板代码创建 JSON API。Handler 可以直接返回普通对象，由框架序列化为 JSON；也可以返回 Response，或返回 undefined 表示 204。Acorn 内置路径路由、404/405/OPTIONS 行为、HTTP 错误辅助方法、状态处理器、请求生命周期 Hook、LogTape 日志，以及基于 Valibot 的请求与响应 Schema 验证。同一套 API 可运行在 Deno、Node.js、Bun 和 Cloudflare Workers，适合功能边界清晰的小型 REST 服务和跨运行时 API。
主要特点
Acorn 将 REST Router、JSON 响应、Schema 验证和常见 HTTP 语义集中在一个小型、跨运行时的 TypeScript 包中。
专注 RESTful JSON
框架聚焦 JSON API，不引入模板渲染或完整应用架构，Handler 返回对象即可生成 JSON 响应。
内置 Valibot 验证
可为 Body、Query 和 Response 声明 Schema，在数据进入业务逻辑和离开服务前执行运行时验证。
完整 Router
支持 GET、POST、PUT、PATCH、DELETE、HEAD、OPTIONS、路径参数和 path-to-regexp 模式。
合理的 HTTP 默认值
自动处理 404 Not Found、405 Method Not Allowed 和 OPTIONS，并在 Handler 无返回值时发送 204。
REST 响应辅助方法
Context 提供 created、notFound、conflict、redirect 和 throw 等方法，帮助保持状态码、Location 与错误语义一致。
跨运行时 Context
Context 统一暴露 Request、URL、参数、环境变量、客户端地址、请求 ID、Cookie 和响应 Header。
Hook 与状态处理器
onRequest、onHandled、onNotFound 和 onError 可用于观测生命周期，状态处理器可统一定制特定 HTTP 响应。
集成结构化日志
通过 LogTape 配置控制台日志级别和请求记录，无需从零搭建最基本的 Router 可观测性。
适用场景
适合接口以 JSON CRUD 为主、希望内置运行时验证，并且不需要完整 MVC 或复杂依赖注入体系的服务。
小型 CRUD API
资源路由、JSON 序列化、Schema 和 REST 状态辅助方法可快速覆盖标准增删改查接口。
Webhook 接收服务
在边界验证第三方 JSON Payload，通过 Hook 记录请求耗时，并返回明确的成功或错误状态。
边缘 JSON 接口
Router 可直接作为 Cloudflare Worker 导出，适合轻量配置、查询、鉴权或数据转换端点。
跨运行时微服务
主要业务逻辑围绕标准 Request/Response 编写，可在 Deno、Node.js 和 Bun 部署目标之间复用。
内部工具 API
简单 Router 与内置验证适合管理脚本、自动化平台和低流量内部服务，减少基础样板代码。
REST 原型验证
无需先选择庞大的插件体系即可定义路径、Schema 和响应，适合快速验证接口契约。
优点与注意事项
技术选型不仅要看能力，也要理解它带来的团队成本。
主要优点
Acorn 擅长的地方
- 定位专一，JSON API 所需的核心概念集中且学习成本较低
- 请求和响应 Schema 共用 Valibot，可同时保护输入边界与输出契约
- 普通对象自动序列化，常见 REST Handler 写法简洁
- 内置 404、405、OPTIONS 和状态辅助方法，减少重复 HTTP 样板
- 基于 Web 标准 Request/Response，能够覆盖多种 JavaScript Runtime
- 自带请求 ID、环境访问、生命周期 Hook 和 LogTape 日志入口
需要注意
采用前应考虑的问题
npm 与搜索结果中的 acorn 通常指 JavaScript 解析器；本项目的包名是 @oak/acorn，仓库位于 oakserver/acorn。
专用中间件、教程、问答和生产案例明显少于 Express、Fastify 或 Hono，遇到边缘问题可能需要阅读源码。
当前 JSR 1.1.1 已发布一段时间，新项目应核对仓库活动、依赖状态和安全修复响应是否符合团队要求。
它聚焦 RESTful JSON，不提供模板、完整 MVC、依赖注入、ORM 或 GraphQL 等体系，复杂应用需要自行组合。
WebSocket Upgrade 当前仅支持 Deno 与 Deno Deploy；Cookie、环境变量和网络信息也应在每个目标 Runtime 实测。
Valibot 能验证数据形状，但认证、对象级授权、速率限制和数据库约束仍需独立设计。
ctx.throw 和 Hook 虽能集中处理异常，生产环境仍应避免把内部堆栈、数据库信息或敏感 Payload 返回客户端。
快速开始
使用 Deno、JSR、Acorn Router 和内置 Valibot Schema 创建可在多个运行时复用的任务 API。
bashmkdir acorn-tasks
cd acorn-tasks
deno init
deno add jsr:@oak/acorntypescriptimport { Router, Status, v } from "@oak/acorn";
const CreateTask = v.object({
title: v.string(),
});
const Task = v.object({
id: v.string(),
title: v.string(),
completed: v.boolean(),
});
const tasks = new Map<string, {
id: string;
title: string;
completed: boolean;
}>();
export const router = new Router({ logger: true });
router.get("/health", () => ({ status: "ok" }));
router.get("/tasks/:id", (ctx) => {
const task = tasks.get(ctx.params.id);
if (!task) {
ctx.throw(Status.NotFound, "Task not found");
}
return task;
}, {
schema: { response: Task },
});
router.post("/tasks", async (ctx) => {
const input = await ctx.body();
const task = {
id: crypto.randomUUID(),
title: input.title.trim(),
completed: false,
};
if (!task.title || task.title.length > 120) {
ctx.throw(Status.UnprocessableEntity, "Invalid title");
}
tasks.set(task.id, task);
return ctx.created(task, {
location: `/tasks/${task.id}`,
});
}, {
schema: {
body: CreateTask,
response: Task,
},
});typescriptimport { Status } from "@oak/acorn";
import { router } from "./router.ts";
router.on(Status.NotFound, () => {
return Response.json(
{
error: "Not Found",
status: Status.NotFound,
},
{
status: Status.NotFound,
},
);
});typescriptimport { router } from "./router.ts";
await router.listen({
hostname: "127.0.0.1",
port: 3000,
});typescriptimport { Router } from "@oak/acorn";
const router = new Router();
router.get("/health", () => ({
status: "ok",
runtime: "cloudflare-workers",
}));
export default router;下一步：Acorn 与著名的 JavaScript 解析器同名，搜索依赖和文档时应使用完整包名 @oak/acorn；生产采用前还应评估其维护节奏、社区规模和目标运行时兼容性。
类似项目
这些框架同样用于 TypeScript API、轻量 Router 或跨运行时服务，但在生态规模、扩展模型和默认能力上有所不同。
Oak
受 Koa 启发、支持 Deno、Node.js、Bun 与 Cloudflare Workers 的 TypeScript 中间件框架。
查看项目Hono
基于 Web 标准、轻量快速且可运行于多种 JavaScript 环境的 Web 框架。
查看项目Elysia
为 Bun 深度优化、强调端到端类型安全与优秀开发体验的 TypeScript 后端框架。
查看项目Fastify
面向 Node.js 的高性能低开销 Web 框架，拥有成熟的插件与 JSON Schema 生态。
查看项目itty-router
面向 Fetch API 与 Cloudflare Workers 的小型 Router，强调极低抽象和包体积。
访问官网Restify
专注构建语义清晰、可观测 REST 服务的 Node.js 框架。
访问官网Acorn vs Oak
Acorn 与 Oak 由同一团队维护并共享跨运行时方向，但抽象层级不同。Acorn 专注结构化 RESTful JSON API，并内置 Valibot Schema；Oak 是更通用的中间件框架，可处理页面、静态文件、流式响应和自定义 Web 栈。
| 比较维度 | Acorn | Oak |
|---|---|---|
| 核心定位 | 专注 RESTful JSON 服务的 Router | 通用 HTTP Application 与中间件框架 |
| 处理模型 | 路由 Handler 返回对象或 Response | Application 中组合 async 洋葱中间件 |
| Schema 验证 | 内置 Valibot Body、Query、Response Schema | 不绑定验证库，由应用自行组合 |
| 默认 HTTP 行为 | 内置 404、405、OPTIONS 与 REST 辅助方法 | Router 与中间件提供更通用的响应控制 |
| 响应类型 | 主要面向 JSON、Response 与 204 | HTML、JSON、文件、Stream、SSE 等更广 |
| 扩展机制 | Route、Hook、Status Handler 与 Schema | Middleware、Context、Router 与应用状态 |
| 运行环境 | Deno、Node.js、Bun、Cloudflare Workers | Deno、Node.js、Bun、Cloudflare Workers |
| 更适合 | 小型契约化 REST API 与边缘 JSON 接口 | 定制 Web 栈、页面与多种响应类型 |
如果服务几乎全部是 JSON CRUD，并希望 Router 直接提供 Schema、状态码和 REST 辅助方法，Acorn 的范围更聚焦；如果需要中间件编排、HTML、静态文件、复杂响应或更自由的请求生命周期，Oak 更合适。由于 Acorn 的社区和更新频率较低，生产选型还应与 Hono、Fastify 等活跃框架一起评估。
资料核验
版本、维护信息与本页采用的官方资料来源。
本次核验覆盖 Acorn 的核心定位、主要能力、官方入口与开源许可。项目版本持续更新，具体补丁版本、兼容性和迁移要求请在采用前继续核对官方发布记录。
官方仓库未归档，但核验时最近可见的代码活动停留在 2024 年 11 月 11 日，且未发现近期正式发布。采用前应进一步确认维护响应、依赖兼容性和替代方案。