Rotas & schemas
Uma rota é uma única chamada a defineRoute. Nessa única chamada você declara tudo o que o framework precisa saber sobre um endpoint: seu método HTTP e path, o formato do que entra (in), o formato do que sai (out), uma cadeia opcional de middleware e o handler que faz o trabalho.
A regra principal é que tanto input quanto output são obrigatórios — omita qualquer um e é um erro de TypeScript, não algo que você descobre em produção (ADR-0003). O motivo é que o contrato de uma rota — o que ela aceita e o que ela retorna — nunca deve ser implícito. Ele é escrito, checado por tipos e (como você verá) imposto em runtime em ambas as pontas.
defineRoute vem do seu context, não de um import global. defineContext o retorna já vinculado ao seu registry (veja Context & DI), o que é o que permite que c.get('key') dentro do handler passe na checagem de tipos exatamente para os slots que você declarou.
// src/modules/echo/echo.route.ts
import { defineRoute } from '../../context'
import { EchoBodySchema, EchoResponseSchema } from './echo.schema'
export const echoRoute = defineRoute({
method: 'POST',
path: '/echo',
input: { body: EchoBodySchema },
output: EchoResponseSchema,
handler: (c) => ({ echoed: c.input.body.message }),
})Um arquivo de rota contém chamadas a defineRoute e nada mais. Exporte cada rota como um const nomeado; createApp depois as coleta importando o arquivo .route.ts inteiro como um namespace, para que cada rota exportada seja captada automaticamente.
O formato de defineRoute
Aqui está o objeto completo, com a função de cada campo:
defineRoute({
method, // 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE'
path, // uma string de path do Hono, ex.: '/users/:id'
input, // { params?, query?, body?, headers? } — cada um um schema Zod
output, // um único schema Zod OU um map status→schema
use, // opcional: Middleware[] que roda antes do handler desta rota
handler, // (c) => value | c.json(...) | c.error(...)
})method e path não são apenas strings para o sistema de tipos — eles são inferidos como tipos literais e fluem até o cliente RPC, para que um chamador saiba que este é um POST /echo e nada mais. use assume [] quando você o omite; qualquer middleware de nível de app registrado em createApp roda antes da cadeia use: da própria rota (veja Middleware de app).
Path matching e precedência
Rotas casam em ordem de registro, não por especificidade. createApp percorre modules na ordem do array, e dentro de cada módulo percorre os exports do arquivo de rota na ordem das chaves do objeto; cada rota é registrada no router Hono subjacente nessa sequência exata, e o Hono casa na ordem de registro — um segmento estático não vence :param só por ser mais específico (prioridade de roteamento do Hono).
Isso significa que esta ordenação é um bug esperando para acontecer:
export const getTeamRoute = defineRoute({ method: 'GET', path: '/teams/:id', /* ... */ })
export const getMyTeamRoute = defineRoute({ method: 'GET', path: '/teams/me', /* ... */ })Uma requisição a GET /teams/me casa com getTeamRoute primeiro — :id se liga à string literal "me" — então getMyTeamRoute nunca roda. A mesma regra vale entre módulos: a ordem do array modules em createApp({ modules }) decide qual módulo registra suas rotas primeiro, então um GET /teams/:id adicionado depois por um módulo não relacionado pode sequestrar /teams/me silenciosamente.
A correção é registrar a rota estática mais específica primeiro, no mesmo módulo:
export const getMyTeamRoute = defineRoute({ method: 'GET', path: '/teams/me', /* ... */ })
export const getTeamRoute = defineRoute({ method: 'GET', path: '/teams/:id', /* ... */ })input — as quatro seções
Uma requisição HTTP não chega como uma coisa só. Seus dados vivem em quatro lugares diferentes, e input espelha exatamente esses quatro. Você fornece um schema Zod para cada seção que a rota realmente lê:
type InputSchemas = {
params?: z.ZodTypeAny
query?: z.ZodTypeAny
body?: z.ZodTypeAny
headers?: z.ZodTypeAny
}Você declara apenas as seções que a rota lê. Cada uma mapeia para uma parte da requisição:
| Seção | De onde vem |
|---|---|
params | parâmetros de path (/users/:id) |
query | a query string da URL |
body | o corpo JSON da requisição parseado |
headers | headers da requisição (em minúsculas) |
Chaves de header são minúsculas
Nomes de header HTTP são case-insensitive, então o Kata converte toda chave de header recebida para minúsculas antes de validar. Por isso o seu schema de headers precisa usar chaves em minúsculas — z.object({ authorization: z.string() }), nunca Authorization. Um schema com a chave Authorization nunca casa, e a requisição falha na validação com 422.
Declarar uma seção faz dois trabalhos de uma vez só. Em runtime, o Kata valida essa parte da requisição contra o seu schema antes do handler rodar. Em tempo de compilação, ele tipa o campo correspondente em c.input — então dentro do handler c.input.params.id é uma string conhecida, não any. Uma seção que você não declarou é tipada como undefined em c.input, então ler c.input.query só passa na checagem de tipos quando você realmente declarou um schema query. Um único schema é a fonte da verdade tanto para a checagem em runtime quanto para o tipo estático; eles não podem divergir.
// src/modules/users/users.route.ts
export const getUserRoute = defineRoute({
method: 'GET',
path: '/users/:id',
input: { params: GetUserParamsSchema },
output: { 200: UserSchema, 404: ErrorBodySchema },
handler: async (c) => {
const user = await getUser(c.input.params.id) // string, tipado
if (!user) return c.error('not_found', 'User not found', { status: 404 })
return user
},
})Uma rota que não lê nenhuma das quatro seções ainda declara input — como um objeto vazio:
export const requestIdRoute = defineRoute({
method: 'GET',
path: '/request-id',
input: {},
output: RequestIdResponseSchema,
handler: (c) => ({ requestId: c.requestId }),
})TIP
input: {} não é ruído de boilerplate — é o contrato declarando, em voz alta, "esta rota não lê input". A regra de lint kata/no-route-without-input-schema exige que ele esteja presente e explícito, para que "eu esqueci de pensar no input" e "esta rota genuinamente não tem nenhum" nunca pareçam iguais no código fonte.
(c.input aqui é o objeto de input validado, e c.requestId é um id de correlação por requisição — ambos ficam pendurados no mesmo objeto de contexto c introduzido em Context & DI.)
Filtros opcionais em query: a armadilha do z.coerce.boolean()
Uma rota de listagem com um filtro booleano opcional — GET /todos?completed=true — é uma das formas mais comuns de query, e ela esconde uma armadilha. Uma query string é sempre texto, esteja presente ou não, então um campo booleano opcional precisa converter "true" / "false" em um boolean de verdade — e a forma óbvia de escrever isso está errada:
// Parece certo, não é:
completed: z.coerce.boolean().optional()z.coerce.boolean() executa Boolean(value) por baixo dos panos, e em JavaScript Boolean("false") é true — qualquer string não vazia converte para true, incluindo o texto literal "false". Esse schema trata ?completed=false e ?completed=true como a mesma requisição, e não há erro de validação para pegar isso — simplesmente significa "true" silenciosamente, nos dois casos.
A correção é validar as duas strings literais que a query string pode de fato carregar, e então transformar em boolean, em vez de coagir:
// src/modules/todos/todos.schema.ts
import { z } from 'zod'
export const ListTodosQuerySchema = z.object({
completed: z
.enum(['true', 'false'])
.optional()
.transform((v) => (v === undefined ? undefined : v === 'true')),
})// src/modules/todos/todos.route.ts
import { defineRoute } from '../../context'
import { ListTodosQuerySchema, TodoListSchema } from './todos.schema'
import { listTodos } from './todos.service'
export const listTodosRoute = defineRoute({
method: 'GET',
path: '/todos',
input: { query: ListTodosQuerySchema },
output: TodoListSchema,
handler: (c) => listTodos(c.get('store'), c.input.query.completed),
})c.input.query.completed é tipado como boolean | undefined — omitir ?completed= deixa o filtro desligado, ?completed=true / ?completed=false o definem corretamente, e qualquer outro valor (?completed=yes, ?completed=1) falha na validação de input com o 422 de sempre, em vez de silenciosamente resolver para true.
Isso é comportamento do Zod, não do Kata
z.coerce.boolean() é documentado para funcionar exatamente assim — é coerção via Boolean(...), não um parser de strings truthy/falsy. É uma escolha razoável para um valor que você já confia ser "true"/"false"/ausente (uma flag de config interna, por exemplo), mas uma query string é input do usuário, então prefira o padrão z.enum(...).transform(...) acima sempre que o texto do campo deva ser exatamente "true" ou "false".
output — schema único ou map de status
output descreve o que a rota tem permissão para enviar de volta. Ele assume uma de duas formas:
type OutputMap = { readonly [status: number]: z.ZodTypeAny }
type OutputSpec = z.ZodTypeAny | OutputMapSchema único
A forma de schema único descreve o corpo de sucesso 200 — o caso comum, para uma rota com apenas um formato de caminho feliz:
export const createUserRoute = defineRoute({
method: 'POST',
path: '/users',
input: { body: CreateUserBodySchema },
output: UserSchema,
handler: async (c) => createUser(c.input.body),
})Qualquer schema Zod nomeado é uma entrada válida, inclusive uma lista — output: TodoListSchema acima é exatamente z.array(TodoSchema), com um nome e declarado em <domain>.schema.ts como qualquer outro DTO (ADR-0005). output nunca distingue um schema de objeto de um schema de array; ele apenas valida o valor retornado pelo handler contra o schema que você fornecer.
Map de status para schema
Recorra à forma de map quando uma rota responde a mais de um status e você quer que cada um deles seja tipado e validado — digamos um corpo de sucesso 200 e um envelope de erro 404 (ADR-0011):
import { ErrorBodySchema } from '@katajs-framework/core'
output: { 200: UserSchema, 404: ErrorBodySchema }ErrorBodySchema é exportado de @katajs-framework/core. É o espelho Zod do envelope de erro unificado que c.error(...) produz (veja Erros), o que o torna o schema canônico para colocar atrás de qualquer status 4xx/5xx. Quando quiser um contrato mais apertado, substitua-o por um refinamento mais estrito — por exemplo, travando error em um código literal.
Como o Kata escolhe contra qual status validar
Esta é a regra que liga um valor de retorno a um código de status:
- Um return simples é sempre o corpo
200. O Kata o valida contra o schema único, ou contraoutput[200]em um map. - Todo outro status é um que você define explicitamente, com
c.json(body, status)ouc.error(...).
Então um map do qual você retorna valores simples precisa incluir uma entrada 200. Se não incluir, o tipo de return simples colapsa para never, e o TypeScript força você a retornar um Response em vez disso — o que é exatamente o certo para, digamos, uma rota de criação que só responde 201.
A forma de map é totalmente retrocompatível: uma rota escrita com um único output: Schema compila e se comporta exatamente como antes.
O handler
O handler é a função que roda a requisição. Ele recebe o contexto c e retorna uma de duas coisas — e qual você retorna decide como o Kata constrói a resposta:
- Um valor simples — o caminho de sucesso. O Kata o valida contra o schema de sucesso, aplica quaisquer transforms do Zod e o serializa como uma resposta JSON
200. Este é o caso que você escreverá com mais frequência. - Um
Response— o caminho explícito, para qualquer status além de um simples200. Você o constrói comc.json(value, status?)ouc.error(code, message, extra?).
json<T>(value: T, status?: number): Response
error(code: string, message: string, extra?: ErrorExtra): Responsec.json assume status 200 por padrão. c.error produz o envelope de erro unificado e assume status 400 por padrão; seu terceiro argumento define qualquer outra coisa:
type ErrorExtra = {
status?: number // status HTTP; padrão 400
issues?: FieldIssues // erros de campo estruturados, anexados sob `issues`
}(c.json e c.error são os construtores de resposta em c; o envelope que c.error emite é documentado em detalhes em Erros.)
Validando um Response
Retornar um Response pula o caminho de sucesso de valor simples — então o que acontece com seu corpo depende de qual forma de output você usou:
- Forma de map, e o status da resposta é uma chave declarada → O Kata valida um clone do corpo contra
output[status], depois encaminha seuResponseoriginal inalterado assim que ele passar. - Forma de schema único, ou qualquer status que o map não declare → o
Responsepassa direto sem validação.
Veja ADR-0011 para a semântica exata.
Respostas não-JSON: raw()
Todos os exemplos até aqui respondem com JSON. Uma route que serve outra coisa — um export CSV, um arquivo de texto puro, um download — constrói o Response ela mesma, já que um return simples só produz JSON. Declare esse contrato com raw() em vez de um schema Zod:
import { raw } from '@katajs-framework/core'
export const usersCsvRoute = defineRoute({
method: 'GET',
path: '/users.csv',
input: {},
output: raw('text/csv', UsersCsvSchema), // UsersCsvSchema = z.string()
handler: async () => {
const users = await listUsers()
return new Response(usersToCsv(users), { headers: { 'content-type': 'text/csv' } })
},
})raw(contentType, schema) declara duas coisas: o content-type da resposta e um schema para o corpo em texto (não JSON — o schema.safeParse roda contra a string crua). Só um Response satisfaz uma entrada raw — não existe equivalente de valor simples —, então o RouteHandlerReturn transforma qualquer outro retorno em erro de tsc.
Em runtime, o Kata checa o status declarado do mesmo jeito que checa uma entrada JSON (Validando um Response, acima), com uma diferença no que é checado e quando:
- O header
content-typeé sempre comparado com o declarado (ignorando parâmetros como; charset=utf-8) sempre que a validação de output não estiver emoff— é barato, só uma leitura de header. - O corpo em texto é comparado com o
schemaapenas no modostrict. Checá-lo exige umresponse.clone().text(), que carrega o corpo inteiro na memória — tudo bem para uma resposta pequena em dev/CI, mas não é algo que o Kata vá fazer com um download grande emlog(o padrão de produção). Uma route com uma entradaraw()emite um warning no startup quando o modo resolvido significa que o corpo dela ficará sem validação, para que esse trade-off nunca seja silencioso.
De um jeito ou de outro, um descasamento segue o mesmo modo de validação de output de um descasamento em JSON: strict troca a resposta pelo envelope 500 internal_output_shape_mismatch, log registra e serve a resposta original mesmo assim, off pula as duas checagens por completo.
O raw() também acerta o cliente RPC: o hc<typeof app> lê o outputFormat da entrada declarada, então a resposta do cliente para um endpoint raw() expõe um .text() tipado em vez de .json() — chamar .json() nela é erro de tipo, não surpresa em runtime.
Além dos construtores de resposta, o contexto entrega ao handler c.get(key) para suas dependências registradas (veja Context & DI), c.requestId para o id de correlação, e c.raw — o contexto Hono subjacente, uma escape hatch para a rara coisa que o Kata não encapsula.
204 No Content
output é obrigatório em toda rota (ADR-0003), mas uma resposta 204 não carrega corpo nenhum, por definição — o HTTP proíbe isso. As duas exigências não colidem de fato: declare a forma de map com uma entrada 204 e retorne a resposta sem corpo com c.json, sem precisar de nenhuma mudança no framework.
// src/modules/things/things.schema.ts
export const NoContentSchema = z.void()// src/modules/things/things.route.ts
import { NoContentSchema } from './things.schema'
export const deleteThingRoute = defineRoute({
method: 'DELETE',
path: '/things/:id',
input: { params: DeleteThingParamsSchema },
output: { 204: NoContentSchema },
handler: (c) => {
deleteThing(c.get('store'), c.input.params.id)
return c.json(undefined, 204) // não precisa de cast — veja abaixo
},
})Duas coisas fazem isso funcionar, nenhuma delas um caso especial para 204:
- Sem chave
200, entãoSuccessOutputénever. Assim como o quadro informativo acima diz, um map sem entrada200força o handler a retornar umResponse— não existe atalho de valor simples, nem mesmo para204. c.json(undefined, 204)não envia corpo, e não precisa de cast. O parâmetro de tipo genérico dec.jsonnão tem restrição, entãoundefinedé um argumento válido.JSON.stringify(undefined)avalia para o valorundefined, não para a string"undefined"— e passarundefinedcomo corpo de umResponseé o mesmo que não passar corpo nenhum. Essa distinção importa aqui porque o construtorResponsedo Fetch lança um erro se um corpo de verdade (mesmo'') for combinado comstatus: 204— entãoc.json({ ok: true }, 204)falha no momento da requisição, enquantoc.json(undefined, 204)não falha.
Um schema em 204 documenta intenção — ele não é imposto
O Kata valida o corpo de um Response retornado lendo-o como JSON (response.clone().json()) e comparando o resultado com o schema declarado. Uma resposta 204 não tem nada para ler, então essa chamada lança um erro (Unexpected end of JSON input), e o fallback do Kata para um corpo ilegível — o mesmo que uma resposta em texto puro ou qualquer outra não-JSON aciona — é pular a validação e encaminhar a resposta inalterada. Na prática, output: { 204: NoContentSchema } nunca pode falhar sua checagem de formato, não importa qual schema esteja ali. Declare um mesmo assim: output continua obrigatório, e z.void() diz, no mesmo lugar que todo outro status, "esta resposta não tem nada dentro".
Se uma exclusão deve confirmar o que aconteceu em vez de retornar nada — o id que foi removido, uma flag deleted: true — modele-a como um corpo 200 comum:
export const deleteThingRoute = defineRoute({
method: 'DELETE',
path: '/things/:id',
input: { params: DeleteThingParamsSchema },
output: { 200: DeleteConfirmationSchema }, // z.object({ id: z.string(), deleted: z.literal(true) })
handler: (c) => {
deleteThing(c.get('store'), c.input.params.id)
return { id: c.input.params.id, deleted: true as const }
},
})Ambas as formas são legítimas — 204 serve a um cliente que só precisa do código de status, 200 { id, deleted: true } serve a um que quer confirmação no corpo. Escolha a que os chamadores da sua API precisam; o Kata valida qualquer uma da mesma forma.
Validação, em ambas as pontas
Junte as duas metades e você tem a promessa central do Kata: uma rota é checada na entrada e na saída (ADR-0003).
Na entrada. Se a requisição falhar no seu schema de input, o handler nunca roda. O Kata responde 422 com um envelope fixo: error: "validation_failed", uma message e um objeto issues indexado pela seção que falhou, cada uma contendo um array de issues de campo:
{
"error": "validation_failed",
"message": "Request input validation failed",
"issues": {
"body": [
{ "path": "name", "code": "too_small", "message": "String must contain at least 1 character(s)" },
{ "path": "email", "code": "invalid_string", "message": "Invalid email" }
]
}
}Cada issue de campo é { path, message, code }, com expected / received opcionais para incompatibilidades de tipo. path usa notação de ponto/colchete para campos aninhados (address.zip, tags[0]), de forma que um cliente pode mapear um erro diretamente de volta ao campo que o causou.
Na saída. Se um return simples não corresponde ao seu schema de output, o Kata responde 500 { "error": "internal_output_shape_mismatch" } e loga as issues Zod ofensoras no lado do servidor — o formato errado nunca chega ao cliente. Esse é o comportamento strict (o padrão fora de produção); o modo de validação de output decide se uma incompatibilidade gera 500, loga e serve mesmo assim, ou é ignorada completamente.
Veja Erros para a referência completa do envelope e como retornar seu próprio 4xx.
Schemas vivem em <domain>.schema.ts
Uma regra de layout surge aqui: schemas nunca são declarados inline em um arquivo .route.ts. Os schemas Zod de cada domínio vivem em src/modules/<domain>/<domain>.schema.ts, e rotas os importam pelo nome (ADR-0005). Um z.object(...) inline em um arquivo de rota é um erro de lint (kata/inline-schema).
Isso não é organização apenas por capricho. Puxar schemas para o seu próprio arquivo é o que permite que uma rota e o seu service compartilhem exatamente o mesmo tipo, e mantém cada DTO localizável de duas maneiras: por glob (src/modules/**/*.schema.ts) e por busca exata de símbolo (grep "UserSchema").
// src/modules/users/users.schema.ts
import { z } from 'zod'
export const UserSchema = z.object({
id: z.string(),
name: z.string(),
email: z.string().email(),
})
export const CreateUserBodySchema = z.object({
name: z.string().min(1),
email: z.string().email(),
})
export const GetUserParamsSchema = z.object({
id: z.string(),
})
export type User = z.infer<typeof UserSchema>
export type CreateUserBody = z.infer<typeof CreateUserBodySchema>// src/modules/users/users.route.ts
import { ErrorBodySchema } from '@katajs-framework/core'
import { defineRoute } from '../../context'
import { CreateUserBodySchema, GetUserParamsSchema, UserSchema } from './users.schema'
import { createUser, getUser } from './users.service'Duas convenções de nomenclatura mantêm isso consistente:
*Schemapara os próprios schemas Zod.- Um tipo
*correspondente (ex.:User,CreateUserBody) inferido viaz.infer, declarado logo ao lado do seu schema.
Como o tipo é inferido a partir do schema, os dois nunca podem divergir — e o service permanece uma função pura sobre esses tipos inferidos, sem imports de framework:
// src/modules/users/users.service.ts
import type { CreateUserBody, User } from './users.schema'
export async function createUser(input: CreateUserBody): Promise<User> {
const id = crypto.randomUUID()
const user: User = { id, ...input }
return user
}Veja também
- Erros — os envelopes
422e500, e como retornar seu próprio4xx. - Referência de
defineRoute— a assinatura completa e os tipos. - Context & DI — de onde vêm
defineRouteec.get. - Services — as funções puras que um handler chama.