用途
当 VTEX IO 服务需要通过 service.json 路由暴露明确的 HTTP 端点,并在 node/ 目录下实现对应的处理程序时,可使用本技能。典型场景包括:构建回调或 webhook 端点;为合作伙伴或后台流程暴露集成端点;组织路由处理程序与中间件链;校验参数、查询字符串、请求头或请求体;统一响应结构与状态码行为。
本技能不适用于:调整或优化服务运行时;在 manifest.json 中决定应用策略;设计 GraphQL API;建模异步事件或 worker 流程。
主要能力
- 在 VTEX IO 中,service.json 声明路由 ID、路径与暴露方式(如 public),Node 入口点在 new Service(...) 中注册 routes 对象,node/routes/index.ts 将各路由 ID 映射到最终处理程序。中间件在代码中组合,而非直接在 service.json 中声明。
- 决策规则:当集成需要明确的 URL 契约、webhook 或回调式请求-响应行为时,使用 HTTP 路由。
- 保持路由处理程序小而明确:路由代码应校验输入、调用领域或集成服务并塑造响应。
- 将校验、请求规范化或共享鉴权等横切关注点放入中间件,避免在各处理程序中重复。
- 尽可能在处理程序边界附近定义路由参数、查询期望与请求体结构。
- 对相似路由族使用一致的状态码与响应结构。
- 对 webhook 或回调端点,遵循调用方文档中关于状态码与错误体的期望,保持响应小而确定,避免歧义重试。
- 对关键路由发出结构化日志或指标,以便在不改变处理程序契约的情况下诊断失败、延迟与集成健康状况。
- 优先按限界域组织显式路由文件,如 routes/orders.ts 或 routes/catalog.ts。
- 将公共路由视为明确的外部契约,未经审查校验、鉴权期望与响应安全性,不得将路由扩展为公共使用。
硬性约束
约束一:路由处理程序必须保持 HTTP 契约显式。每个路由处理程序必须在处理程序边界使请求与响应契约可理解,不得将必需参数、请求体字段或状态码决策隐藏在无关服务深处。若处理程序未经校验必需参数、查询值、请求头或请求体结构就立即委托,应停下并使契约显式化。正确示例:导出 async function getOrder(ctx, next),从 ctx.vtex.route.params 取 id,缺失时返回 400 与 { message: 'Missing route param: id' },否则调用 ctx.clients.partnerApi.getOrder(id) 并返回 200 与订单。错误示例:导出 async function getOrder(ctx) { ctx.body = await handleOrder(ctx) }。
约束二:共享路由关注点必须放在中间件中,而非在每个处理程序中重复。重复的校验、请求规范化或通用鉴权检查应实现为中间件并通过路由链组合。若多个处理程序重复相同的请求体校验、请求头检查或上下文准备,应停下并抽取中间件。正确示例:导出 async function validateSignature(ctx, next),读取 ctx.request.header['x-signature'],缺失时返回 401 与 { message: 'Missing signature' },否则 await next()。
约束三:HTTP 路由不应吸收属于事件或 worker 的异步或批量工作。路由必须保持请求-响应延迟有界。若路由触发昂贵、易重试或面向批量的工作,应将该工作移至异步流程,路由仅作为轻量触发器或确认边界。正确示例:导出 async function triggerImport(ctx) { await ctx.clients.importApi.enqueueImport(ctx.request.body); ctx.status = 202; ctx.body = { accepted: true } }。错误示例:在 triggerImport 中循环逐项导入并返回 200。
使用方式
推荐文件布局:node/ 下含 routes/(index.ts、orders.ts、webhooks.ts)与 middlewares/(validateBody.ts、validateSignature.ts)。
在 VTEX IO 服务中接线路由:service.json 声明路由 ID 与路径,Node 入口点在 new Service(...) 中注册 routes 对象,node/routes/index.ts 将每个路由 ID 映射到最终处理程序。
service.json 示例: { "routes": { "orders-get": { "path": "/_v/orders/:id", "public": false }, "reviews-create": { "path": "/_v/reviews", "public": false } } }
node/index.ts 示例: import type { ClientsConfig, RecorderState, ServiceContext } from '@vtex/api' import { Service } from '@vtex/api' import { Clients } from './clients' import routes from './routes'
const clients: ClientsConfig<Clients> = { implementation: Clients, options: { default: { retries: 2, timeout: 800, }, }, }
declare global { type Context = ServiceContext<Clients, RecorderState> }
export default new Service<Clients, RecorderState>({ clients, routes, })
node/routes/index.ts 示例: import type { RouteHandler } from '@vtex/api' import { createReview } from './reviews' import { getOrder } from './orders'
const routes: Record<string, RouteHandler> = { 'orders-get': getOrder, 'reviews-create': createReview, }
export default routes
node/routes/orders.ts 示例: import { compose } from 'koa-compose' import { validateSignature } from '../middlewares/validateSignature'
async function rawGetOrder(ctx: Context, next: () => Promise<void>) { const { id } = ctx.vtex.route.params
if (!id) { ctx.status = 400 ctx.body = { message: 'Missing route param: id' } return }
const order = await ctx.clients.partnerApi.getOrder(id) ctx.status = 200 ctx.body = order
await next() }
export const getOrder = compose([validateSignature, rawGetOrder])
export async function createReview(ctx: Context, next: () => Promise<void>) { const body = ctx.request.body
if (!body?.productId) { ctx.status = 400 ctx.body = { message: 'Missing productId' } return }
const review = await ctx.clients.reviewApi.createReview(body) ctx.status = 201 ctx.body = review await next() }
将领域逻辑放在服务或集成中,让路由处理程序负责 HTTP 关注点,如校验、状态码、请求头与响应结构。
适用场景
需要在 VTEX IO 服务中暴露明确 HTTP 契约的集成、webhook、回调或请求-响应行为均可应用。典型如订单查询路由、评价创建路由、合作伙伴集成端点、后台流程端点等。
限制
不适用于调整服务运行时、决定 manifest.json 中的应用策略、设计 GraphQL API、建模异步事件或 worker 流程。公共路由不得在未审查校验、鉴权期望与响应安全性的情况下扩展为公共使用。
常见失败模式
将请求校验隐藏在无关服务中而非显式表达路由期望;在多个处理程序中重复相同的鉴权或规范化逻辑而不使用中间件;让 HTTP 处理程序执行长时间运行的异步或批量工作;对相似端点返回不一致的状态码或响应结构;在未审查信任边界的情况下将路由扩展为公共暴露。
审查清单
HTTP 是否为该契约的正确暴露机制?必需参数、请求头、查询值与请求体字段是否在路由边界校验?重复关注点是否已抽取到中间件?处理程序是否保持小而专注于 HTTP 关注点?是否有部分工作应移至异步事件或 worker?
相关技能
vtex-io-events-and-workers:当昂贵或易重试的工作应从 HTTP 处理程序移至异步流程时使用。vtex-io-auth-and-policies:当决定哪些策略或访问规则应保护 HTTP 路由时使用。
参考
Service:路由声明与服务暴露。Node Builder:后端文件布局与路由实现上下文。Using Node Clients:在路由处理程序中使用客户端。