Configurar Redirecionamentos e Reescritas

Orbit tem um motor integrado de redirecionamento e reescrita que é executado antes de qualquer pedido ao seu projeto, configurado no KPanel ou como um ficheiro no seu repositório. Este guia cobre ambos, a sintaxe de padrões e as suas capturas, como as regras são ordenadas, os limites e o comportamento que apanha as pessoas de surpresa.

Onde Configurar Regras

Existem dois locais, e são avaliados numa ordem fixa.

1. No KPanel. Abra o seu projeto em Orbit, vá a Settings, e desloque-se até à secção redirects and rewrites do ambiente. Cada ambiente tem o seu próprio conjunto independente de regras, pelo que produção e staging são configurados separadamente.
2. No seu repositório, como um ficheiro kaps.json. Isto é abordado mais adiante.

As regras do painel são avaliadas primeiro. Se nenhuma delas corresponder, as regras kaps.json são testadas.

Adicionar uma Regra no KPanel

1. Clique em Add rule.
2. Preencha a source, o padrão de caminho para corresponder contra pedidos recebidos. O marcador de posição mostra as duas formas que espera: /old-path or /blog/:slug.
3. Preencha o destination. O marcador de posição mostra /new-path or https://..., portanto tanto um caminho local como um URL externo completo são válidos.
4. Escolha o tipo de regra:
   • 301 Permanent: o URL deslocou-se permanentemente. Os navegadores e motores de busca colocam isto em cache.
   • 302 Temporary: deslocado por agora, não colocado em cache. Utilize para campanhas e experimentos.
   • Rewrite: serve o caminho de destino sem alterar o URL na barra de endereços do navegador.
5. Clique em Save rules.

Padrões de Caminho de Origem

A diferença entre :id e :rest* é a importante. Um parâmetro nomeado corresponde a um segmento único e para na barra seguinte. Um splat corresponde a tudo o que resta, incluindo barras.

Utilizar Capturas no Destino

Referencie um parâmetro nomeado pelo nome, e um wildcard simples como *:

Ordem das Regras

As regras são testadas de cima para baixo da lista e a primeira correspondência vence. Uma vez que uma regra corresponde, nenhuma regra posterior é considerada. O painel diz isto sob a lista: "Rules are tested in order. First match wins."

Se nenhuma regra corresponder, o pedido é servido normalmente.

Casos de Uso Comuns

Renomear uma Página

Renomeou /about-us para /about e deseja que as ligações antigas continuem a funcionar.

• Origem: /about-us
• Destino: /about
• Tipo: 301 Permanent

Deslocar uma Secção Inteira

O seu blogue deslocou-se de /news/:slug para /blog/:slug.

• Origem: /news/:slug
• Destino: /blog/:slug
• Tipo: 301 Permanent

Fazer Proxy de um Caminho de API Silenciosamente

Deseja que /api/v1/* seja servido a partir de um caminho interno diferente sem expor a alteração.

• Origem: /api/v1/:path*
• Destino: /api/internal/:path*
• Tipo: Rewrite

Uma Página de Espera Temporária

• Origem: /checkout
• Destino: /maintenance
• Tipo: 302 Temporary

Enviar Tráfego Para Outro Domínio

O destino pode ser um URL absoluto, portanto uma regra pode apontar para um site completamente diferente.

• Origem: /shop/:rest*
• Destino: https://shop.example.com/:rest*
• Tipo: 301 Permanent

Configuração Como Código Com kaps.json

As regras podem viver no seu repositório em vez do painel. Adicione um ficheiro kaps.json, e certifique-se de que a sua compilação o copia para o seu output directory, porque Orbit lê-o a partir da raiz do artefato construído em vez da raiz do repositório.

{
  "redirects": [
    { "source": "/about-us", "destination": "/about", "permanent": true },
    { "source": "/news/:slug", "destination": "/blog/:slug", "permanent": true },
    { "source": "/promo", "destination": "/spring-sale", "permanent": false }
  ],
  "rewrites": [
    { "source": "/api/v1/:path*", "destination": "/api/internal/:path*" }
  ],
  "headers": [
    {
      "source": "/*",
      "headers": [
        { "key": "X-Frame-Options", "value": "DENY" },
        { "key": "X-Content-Type-Options", "value": "nosniff" }
      ]
    }
  ]
}

permanent: true produz um 301 e permanent: false um 302. Omiti-lo dá um 301.

Limites

• Até 100 regras de redirecionamento e reescrita por ambiente, e 100 num kaps.json.
• Até 200 regras de cabeçalhos personalizados por ambiente.

As regras para além do limite são descartadas silenciosamente em vez de gerar um erro, portanto mantenha-se bem abaixo.

Cabeçalhos de Resposta Personalizados

Juntamente com redirecionamentos, cada ambiente tem uma secção de cabeçalhos de resposta em Settings para injetar cabeçalhos HTTP em caminhos correspondentes. Utiliza a mesma sintaxe de padrão de caminho, e há predefinições de adição rápida para HSTS, CSP, no-embed, no-sniff, política de referrer e CORS.

Ao contrário dos redirecionamentos, todas as regras de cabeçalho correspondentes são aplicadas, não apenas a primeira, e uma regra posterior substitui uma anterior quando definem o mesmo cabeçalho. Content-Length, Transfer-Encoding e Connection são bloqueados, porque defini-los corromperia a resposta.

Comportamento Digno de Conhecer Antes de Depender Dele

• As regras correspondem apenas ao caminho. Fragmentos (#section) nunca chegam ao servidor; o navegador reanexa-os após um redirecionamento.
• Um rewrite para um caminho que não existe produz um 404, em vez de cair silenciosamente para o caminho original. Os destinos de rewrite devem existir no seu resultado de compilação.
• As regras são executadas antes de qualquer coisa ser pedida ao seu projeto, portanto aplicam-se a ficheiros estáticos e a pedidos de modo de servidor igualmente.
• Cada ambiente é independente. As regras na produção não se aplicam a staging ou pré-visualizações. Copie-as deliberadamente.

Apagar uma Regra

Clique no ícone de lixeira na linha de regra, depois clique em Save rules para aplicar a alteração. Como com adicionar uma, a alteração entra em vigor na próxima implementação.

Quando Utilizar uma Função de Borda Em Vez Disso

O motor de redirecionamento processa regras de caminho para caminho. Recorra a uma função de borda quando precisa de lógica que o motor de regras não pode expressar: ramificação num cabeçalho ou cookie, preservação ou reescrita de parâmetros de consulta, encaminhamento A/B ponderado, ou qualquer coisa condicional.

Leitura Relacionada

• Funções de Borda
• Adicionar um Domínio Personalizado ao Seu Projeto
• Implementar o Seu Projeto