创建动态调度 Worker,将传入请求路由到你的调度命名空间中的用户 Worker。 动态调度 Worker 是一种专门的路由 Worker,将传入请求定向到调度命名空间中的相应用户 Worker。与使用 Workers Routes 不同,调度 Worker 允许你通过代码以编程方式控制请求路由。
- 规模:将请求路由到数百万个主机名对应的不同 Worker,而无需为每个主机名定义 Workers Routes 配置
- 自定义路由逻辑:编写代码以精确确定请求应如何路由。例如:
- 将主机名到 Worker 的映射存储在 Workers KV 中并动态查找
- 根据子域名、路径、标头或其他请求属性路由请求
- 使用附加到自定义主机名的自定义元数据进行路由决策
- 添加平台功能:在路由层构建其他功能:
- 在请求到达用户 Worker 之前运行身份验证检查
- 从传入请求中移除或添加标头或元数据
- 附加有用的上下文,例如用户 ID 或账户信息
- 根据需要转换请求或响应
要允许动态调度 Worker 动态地将请求路由到命名空间中的 Worker,你需要配置调度命名空间绑定(binding)。此绑定使动态调度 Worker 能够使用 env.dispatcher.get() 调用该命名空间中的任何用户 Worker。
{
"dispatch_namespaces": [
{
"binding": "DISPATCHER",
"namespace": "my-dispatch-namespace"
}
]
}[[dispatch_namespaces]]
binding = "DISPATCHER"
namespace = "my-dispatch-namespace"绑定配置完成后,你的动态调度 Worker 可以将请求路由到命名空间中的任何 Worker。以下是你可以在调度器中实现的常见路由模式。
当你的调度 Worker 调用用户 Worker 时,可以随该调用发送额外值。例如,调度 Worker 可以先对请求进行身份验证,再将得到的用户 ID、权限或账户信息发送给用户 Worker。
当上下文应来自你的平台代码、而不是直接来自传入请求时,这种方式很有用。要发送此上下文,请将这些值添加到 env.DISPATCHER.get() 第二个参数中的 props。
在调度 Worker 中,从调度命名空间检索用户 Worker 时传入用户 ID 和权限:
export default {
async fetch(request, env) {
const userId = "user-123";
const permissions = ["read", "write"];
const userWorker = env.DISPATCHER.get("user-worker", {
props: { userId, permissions },
});
return userWorker.fetch(request);
},
};export default {
async fetch(request, env): Promise<Response> {
const userId = "user-123";
const permissions = ["read", "write"];
const userWorker = env.DISPATCHER.get("user-worker", {
props: { userId, permissions },
});
return userWorker.fetch(request);
},
} satisfies ExportedHandler<Cloudflare.Env>;在用户 Worker 中,通过 ctx.props 接收这些值。在 WorkerEntrypoint 中,通过 this.ctx.props 访问它们:
import { WorkerEntrypoint } from "cloudflare:workers";
export default class UserWorker extends WorkerEntrypoint {
async fetch(_request) {
const { userId, permissions } = this.ctx.props;
return Response.json({ userId, permissions });
}
}import { WorkerEntrypoint } from "cloudflare:workers";
interface UserWorkerProps {
userId: string;
permissions: string[];
}
export default class UserWorker extends WorkerEntrypoint<
Cloudflare.Env,
UserWorkerProps
> {
async fetch(_request: Request): Promise<Response> {
const { userId, permissions } = this.ctx.props;
return Response.json({ userId, permissions });
}
}这些数据值对用户代码可见。调度 Worker 可以为每次调用选择不同的 props,而无需更改或重新部署用户 Worker。
你可能不希望用户 Worker 直接访问调度 Worker 中的全部上下文。例如,身份验证数据由你的平台管理,应向用户代码隐藏。
在这种情况下,请传递能力(capability),而不是直接传递数据。能力会暴露用户 Worker 可以调用的特定方法,底层数据、凭据和资源仍保留在调度 Worker 中。Workers 会将该能力作为 RPC stub 传递,并将方法调用转发回你的调度 Worker。
要创建能力,请从调度 Worker 导出一个 WorkerEntrypoint 类。ctx.exports 对象让调度 Worker 可以为该导出类创建 RPC stub,然后再将其传递给用户 Worker。
以下示例展示了这种模式。调度 Worker 使用站点 ID 和访问者 ID 创建 Connector 能力。它通过 props 将该能力传递给用户 Worker,而不会把这些 ID 作为单独的数据值传递。用户 Worker 随后可以调用 Connector 暴露的方法。
在调度 Worker 中定义 Connector 方法,用站点和访问者 ID 配置 connector,再将其传递给用户 Worker:
import { WorkerEntrypoint } from "cloudflare:workers";
export class Connector extends WorkerEntrypoint {
async invoke() {
return `${this.ctx.props.siteId}:${this.ctx.props.visitorId}`;
}
}
export default {
async fetch(request, env, ctx) {
const siteId = "site-123";
const visitorId = "visitor-456";
const connector = ctx.exports.Connector({
// These props configure the Connector stub.
// The user Worker cannot read them directly.
props: { siteId, visitorId },
});
const userWorker = env.DISPATCHER.get("user-worker", {
// The user Worker receives these values through ctx.props.
props: {
CONNECTOR: connector,
},
});
return userWorker.fetch(request);
},
};import { WorkerEntrypoint } from "cloudflare:workers";
interface ConnectorProps {
siteId: string;
visitorId: string;
}
export class Connector extends WorkerEntrypoint<
Cloudflare.Env,
ConnectorProps
> {
async invoke(): Promise<string> {
return `${this.ctx.props.siteId}:${this.ctx.props.visitorId}`;
}
}
export default {
async fetch(request, env, ctx): Promise<Response> {
const siteId = "site-123";
const visitorId = "visitor-456";
const connector = ctx.exports.Connector({
// These props configure the Connector stub.
// The user Worker cannot read them directly.
props: { siteId, visitorId },
});
const userWorker = env.DISPATCHER.get("user-worker", {
// The user Worker receives these values through ctx.props.
props: {
CONNECTOR: connector,
},
});
return userWorker.fetch(request);
},
} satisfies ExportedHandler<Cloudflare.Env>;在用户 Worker 中,通过 this.ctx.props 接收该能力并调用其暴露的方法:
import { WorkerEntrypoint } from "cloudflare:workers";
export default class UserWorker extends WorkerEntrypoint {
async fetch(_request) {
return Response.json({
connector: await this.ctx.props.CONNECTOR.invoke(),
});
}
}import { WorkerEntrypoint } from "cloudflare:workers";
interface Connector {
invoke(): Promise<string>;
}
interface UserWorkerProps {
CONNECTOR: Connector;
}
export default class UserWorker extends WorkerEntrypoint<
Cloudflare.Env,
UserWorkerProps
> {
async fetch(_request: Request): Promise<Response> {
return Response.json({
connector: await this.ctx.props.CONNECTOR.invoke(),
});
}
}要从调度 Worker 向出站 Worker 发送数据,请先在调度命名空间绑定中声明参数名称:
{
"dispatch_namespaces": [
{
"binding": "DISPATCHER",
"namespace": "my-dispatch-namespace",
"outbound": {
"service": "outbound-worker",
"parameters": ["requestContext"]
}
}
]
}[[dispatch_namespaces]]
binding = "DISPATCHER"
namespace = "my-dispatch-namespace"
[dispatch_namespaces.outbound]
service = "outbound-worker"
parameters = [ "requestContext" ]在调度 Worker 中,通过 env.DISPATCHER.get() 第三个参数的 outbound 选项,传递同名的值:
export default {
async fetch(request, env) {
const userId = "user-123";
const userWorker = env.DISPATCHER.get(
"user-worker",
{
props: { userId },
},
{
outbound: {
requestContext: {
userId,
requestId: crypto.randomUUID(),
},
},
},
);
return userWorker.fetch(request);
},
};export default {
async fetch(request, env): Promise<Response> {
const userId = "user-123";
const userWorker = env.DISPATCHER.get(
"user-worker",
{
props: { userId },
},
{
outbound: {
requestContext: {
userId,
requestId: crypto.randomUUID(),
},
},
},
);
return userWorker.fetch(request);
},
} satisfies ExportedHandler<Cloudflare.Env>;在出站 Worker 中,将该值作为环境绑定访问:
export default {
async fetch(request, env) {
console.log(env.requestContext.userId, env.requestContext.requestId);
return fetch(request);
},
};interface Env {
requestContext: {
userId: string;
requestId: string;
};
}
export default {
async fetch(request, env): Promise<Response> {
console.log(env.requestContext.userId, env.requestContext.requestId);
return fetch(request);
},
} satisfies ExportedHandler<Env>;出站 Worker 参数支持 JSON 值。它们独立于第二个参数中的 props,后者会传递给用户 Worker。
将路由映射存储在 Workers KV 中。这样你可以修改路由逻辑,而无需更改或重新部署动态调度 Worker。
export default {
async fetch(request, env) {
try {
const url = new URL(request.url);
// Use hostname, path, or any combination as the routing key
const routingKey = url.hostname;
// Lookup user Worker name from KV store
const userWorkerName = await env.USER_ROUTING.get(routingKey);
if (!userWorkerName) {
return new Response("Route not configured", { status: 404 });
}
// Optional: Cache the KV lookup result
const userWorker = env.DISPATCHER.get(userWorkerName);
return await userWorker.fetch(request);
} catch (e) {
if (e.message.startsWith("Worker not found")) {
return new Response("", { status: 404 });
}
return new Response(e.message, { status: 500 });
}
},
};将子域名路由到相应的 Worker。例如,my-customer.example.com 将路由到调度命名空间中名为 my-customer 的 Worker。
export default {
async fetch(request, env) {
try {
// Extract user Worker name from subdomain
// Example: customer1.example.com -> customer1
const url = new URL(request.url);
const userWorkerName = url.hostname.split(".")[0];
// Get user Worker from dispatch namespace
const userWorker = env.DISPATCHER.get(userWorkerName);
return await userWorker.fetch(request);
} catch (e) {
if (e.message.startsWith("Worker not found")) {
// User Worker doesn't exist in dispatch namespace
return new Response("", { status: 404 });
}
// Could be any other exception from fetch() or from the dispatched Worker
return new Response(e.message, { status: 500 });
}
},
};将 URL 路径路由到相应的 Worker。例如,example.com/customer-1 将路由到调度命名空间中名为 customer-1 的 Worker。
export default {
async fetch(request, env) {
try {
const url = new URL(request.url);
const pathParts = url.pathname.split("/").filter(Boolean);
if (pathParts.length === 0) {
return new Response("Invalid path", { status: 400 });
}
// example.com/customer-1 -> routes to 'customer-1' worker
const userWorkerName = pathParts[0];
const userWorker = env.DISPATCHER.get(userWorkerName);
return await userWorker.fetch(request);
} catch (e) {
if (e.message.startsWith("Worker not found")) {
return new Response("", { status: 404 });
}
return new Response(e.message, { status: 500 });
}
},
};