API 路由 | EmDash CMS Everything

插件可以为其管理界面和外部集成暴露 API 路由。路由挂载在 /_emdash/api/plugins/<plugin-id>/<route-name> 下，并在沙盒运行时内执行，使用与 hooks 相同的 PluginContext。

本页面介绍沙盒化（标准格式）插件。原生插件的 API 表面相同；唯一的区别是处理器签名 — 详见原生插件中的说明。

定义路由

在 sandbox-entry.ts 的 definePlugin() 中声明路由：

import { definePlugin } from "emdash";
import type { PluginContext } from "emdash";
import { z } from "astro/zod";

export default definePlugin({
	routes: {
		status: {
			handler: async (_routeCtx, ctx: PluginContext) => {
				return { ok: true, plugin: ctx.plugin.id };
			},
		},

		submissions: {
			input: z.object({
				formId: z.string().optional(),
				limit: z.number().default(50),
				cursor: z.string().optional(),
			}),
			handler: async (routeCtx, ctx: PluginContext) => {
				const { formId, limit, cursor } = routeCtx.input;

				const result = await ctx.storage.submissions.query({
					where: formId ? { formId } : undefined,
					orderBy: { createdAt: "desc" },
					limit,
					cursor,
				});

				return result;
			},
		},
	},
});

标准格式的路由处理器接受两个参数：(routeCtx, ctx)。

routeCtx 携带请求形式的数据：{ input, request, requestMeta }。
ctx 是您在 hooks 内部获得的相同 PluginContext — ctx.storage、ctx.kv、ctx.content、ctx.http、ctx.log 等。

路由 URL

路由挂载在 /_emdash/api/plugins/<plugin-id>/<route-name>。路由名称可以包含斜杠以支持嵌套路径。

插件 ID	路由名称	URL
`forms`	`status`	`/_emdash/api/plugins/forms/status`
`forms`	`submissions`	`/_emdash/api/plugins/forms/submissions`
`seo`	`settings/save`	`/_emdash/api/plugins/seo/settings/save`
`analytics`	`events/recent`	`/_emdash/api/plugins/analytics/events/recent`

认证和 CSRF

插件路由默认经过认证。 调度器在调用您的处理器之前需要会话（或具有 admin 作用域的令牌）：

读取方法（GET、HEAD、OPTIONS）需要 plugins:read 权限。
写入方法（POST、PUT、PATCH、DELETE）需要 plugins:manage。
私有路由上的状态更改方法还需要 X-EmDash-Request: 1 CSRF 头（管理界面的 usePluginAPI() hook 会自动发送；使用 cookie 认证的外部调用者需要自己设置；使用令牌认证的请求则免除）。

要让路由退出认证和 CSRF，标记为 public: true：

routes: {
	track: {
		public: true,
		input: z.object({ event: z.string() }),
		handler: async (routeCtx, ctx) => {
			ctx.log.info("Tracked", { event: routeCtx.input.event });
			return { ok: true };
		},
	},
},

输入验证

input 接受 Zod 模式。调度器解析请求体（POST/PUT/PATCH）或查询字符串（GET/DELETE），验证它，并将类型化的结果作为 routeCtx.input 传递给您的处理器。无效输入在您的处理器运行之前返回 400。

routes: {
	create: {
		input: z.object({
			title: z.string().min(1).max(200),
			email: z.string().email(),
			priority: z.enum(["low", "medium", "high"]).default("medium"),
			tags: z.array(z.string()).optional(),
		}),
		handler: async (routeCtx, ctx) => {
			const { title, email, priority, tags } = routeCtx.input;

			await ctx.storage.items.put(`item_${Date.now()}`, {
				title,
				email,
				priority,
				tags: tags ?? [],
				createdAt: new Date().toISOString(),
			});

			return { success: true };
		},
	},
},

返回值

返回任何 JSON 可序列化的值。调度器将其包装在 EmDash 的标准信封中（{ success: true, data: <你的值> }）并作为 application/json 提供。

return { id: "abc", count: 42 };  // 包装为 { success: true, data: { id, count } }
return [1, 2, 3];                 // 包装为 { success: true, data: [1, 2, 3] }

错误

抛出错误以返回错误响应。任何不是已知插件错误的内容都会返回通用消息 — 内部异常被掩盖而不是泄露堆栈跟踪或数据库错误：

handler: async (routeCtx, ctx) => {
	const item = await ctx.storage.items.get(routeCtx.input.id);
	if (!item) {
		throw new Error("Item not found");
	}
	return item;
},

对于特定状态码，抛出 Response：

handler: async (routeCtx, ctx) => {
	const item = await ctx.storage.items.get(routeCtx.input.id);
	if (!item) {
		throw new Response(JSON.stringify({ error: "Not found" }), {
			status: 404,
			headers: { "Content-Type": "application/json" },
		});
	}
	return item;
},

HTTP 方法

路由响应所有方法。如果需要按方法行为，在 routeCtx.request.method 上分支：

routes: {
	item: {
		input: z.object({ id: z.string() }),
		handler: async (routeCtx, ctx) => {
			const { id } = routeCtx.input;

			switch (routeCtx.request.method) {
				case "GET":
					return await ctx.storage.items.get(id);
				case "DELETE":
					await ctx.storage.items.delete(id);
					return { deleted: true };
				default:
					throw new Response("Method not allowed", { status: 405 });
			}
		},
	},
},

访问请求

完整的 Request 对象可作为 routeCtx.request 用于头部、原始 body 访问和 URL 解析。routeCtx.requestMeta 携带跨平台标准化的 IP、用户代理和地理数据。

handler: async (routeCtx, ctx) => {
	const { request, requestMeta } = routeCtx;

	const auth = request.headers.get("Authorization");
	const url = new URL(request.url);
	const page = url.searchParams.get("page");

	ctx.log.info("Request", { ip: requestMeta.ip, ua: requestMeta.userAgent });

	if (request.method !== "POST") {
		throw new Response("POST required", { status: 405 });
	}
},

常见模式

通过 KV 的设置

沙盒插件通过 KV 存储读写设置，通常在 settings: 前缀下。自动生成的 settingsSchema 表单仅适用于原生插件 — 对于沙盒插件，通过路由暴露读/写，并在 Block Kit 中渲染表单。

routes: {
	settings: {
		handler: async (_routeCtx, ctx) => {
			const settings = await ctx.kv.list("settings:");
			const result: Record<string, unknown> = {};
			for (const entry of settings) {
				result[entry.key.replace("settings:", "")] = entry.value;
			}
			return result;
		},
	},

	"settings/save": {
		input: z.object({
			enabled: z.boolean().optional(),
			apiKey: z.string().optional(),
			maxItems: z.number().optional(),
		}),
		handler: async (routeCtx, ctx) => {
			for (const [key, value] of Object.entries(routeCtx.input)) {
				if (value !== undefined) {
					await ctx.kv.set(`settings:${key}`, value);
				}
			}
			return { success: true };
		},
	},
},

分页列表

从存储查询返回基于游标的分页 — 响应形状与 EmDash 其余部分使用的匹配：

routes: {
	list: {
		input: z.object({
			limit: z.number().min(1).max(100).default(50),
			cursor: z.string().optional(),
			status: z.string().optional(),
		}),
		handler: async (routeCtx, ctx) => {
			const { limit, cursor, status } = routeCtx.input;

			const result = await ctx.storage.items.query({
				where: status ? { status } : undefined,
				orderBy: { createdAt: "desc" },
				limit,
				cursor,
			});

			return {
				items: result.items.map((item) => ({ id: item.id, ...item.data })),
				cursor: result.cursor,
				hasMore: result.hasMore,
			};
		},
	},
},

外部 API 代理

通过 ctx.http 代理对外部服务的请求（需要 network:request 能力和 allowedHosts 中的条目）：

routes: {
	forecast: {
		input: z.object({ city: z.string() }),
		handler: async (routeCtx, ctx) => {
			if (!ctx.http) throw new Error("Network capability not granted");

			const apiKey = await ctx.kv.get<string>("settings:apiKey");
			if (!apiKey) throw new Error("API key not configured");

			const response = await ctx.http.fetch(
				`https://api.weather.example.com/forecast?city=${routeCtx.input.city}`,
				{ headers: { "X-API-Key": apiKey } },
			);

			if (!response.ok) {
				throw new Error(`Weather API error: ${response.status}`);
			}
			return response.json();
		},
	},
},

从管理界面调用路由

使用 admin 包中的 usePluginAPI() — 它会自动添加 X-EmDash-Request CSRF 头和插件 ID 前缀：

import { usePluginAPI } from "@emdash-cms/admin";

function SettingsPage() {
	const api = usePluginAPI();

	const handleSave = async (settings) => {
		await api.post("settings/save", settings);
	};

	const loadSettings = async () => {
		return api.get("settings");
	};
}

外部调用路由

公共路由可以直接调用：

curl -X POST https://your-site.com/_emdash/api/plugins/forms/track \
  -H "Content-Type: application/json" \
  -d '{"event": "pageview"}'

私有路由需要会话凭据或具有 admin 作用域的 API 令牌：

curl -X POST https://your-site.com/_emdash/api/plugins/forms/create \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{"title": "Hello", "email": "[email protected]"}'

路由上下文参考

// 标准格式处理器作为其两个参数接收的内容

interface StandardRouteContext<TInput = unknown> {
	input: TInput;
	request: Request;
	requestMeta: { ip: string | null; userAgent: string | null; geo?: GeoData };
}

interface PluginContext {
	plugin: { id: string; version: string };
	storage: PluginStorage;
	kv: KVAccess;
	log: LogAccess;
	site: SiteInfo;
	url(path: string): string;
	cron?: CronAccess;
	content?: ContentAccess;       // 当声明 content:read 或 content:write 时
	media?: MediaAccess;           // 当声明 media:read 或 media:write 时
	http?: HttpAccess;             // 当声明 network:request 时
	users?: UserAccess;            // 当声明 users:read 时
	email?: EmailAccess;           // 当声明 email:send 且配置提供程序时
}

原生插件接收一个组合两者的单一 RouteContext 参数 — 如果您走那条路，请参阅创建原生插件。