semtech/mu-dispatcher

mu-dispatcher

镜像概述和主要用途

mu-dispatcher是mu.semte.ch架构中的核心元素之一。该服务根据传入请求的路径将请求分发到其他微服务。您可以通过Docker运行该服务，但通常建议使用http://github.com/mu-semtech/mu-project%E8%BF%9B%E8%A1%8C%E9%85%8D%E7%BD%AE%EF%BC%8C%E4%BB%A5%E5%BA%94%E7%94%A8%E8%87%AA%E5%AE%9A%E4%B9%89%E8%AE%BE%E7%BD%AE%E3%80%82

Dispatcher作为一个应用运行，其中Dispatcher模块可被覆盖。启动时，它期望在/config/dispatcher.ex路径下存在dispatcher.ex文件。

核心功能和特性

• 请求分发：根据请求路径、HTTP方法、主机名和Accept头将请求路由到不同微服务
• 灵活配置：通过Elixir模块定义路由规则，支持复杂的匹配逻辑
• Accept头匹配：基于客户端请求的MIME类型分发到相应服务
• 主机名匹配：支持基于主机名（包括通配符）的路由规则
• ** fallback路由**：配置404页面及其他错误响应
• 响应处理：支持请求转发前的日志记录、头部修改等操作

使用场景和适用范围

• 微服务架构中的API网关，统一入口管理
• 需要根据请求特征（路径、方法、内容类型）动态路由的场景
• 构建多服务协作的应用系统，如内容管理、数据服务等
• 需要统一处理CORS、404响应等跨服务功能的场景

详细使用方法和配置说明

配置

Dispatcher通过https://github.com/mu-semtech/mu-project%E4%B8%AD%E7%9A%84dispatcher.ex%E6%96%87%E4%BB%B6%E8%BF%9B%E8%A1%8C%E9%85%8D%E7%BD%AE%E3%80%82

基本（默认）配置是一个名为Dispatcher的Elixir模块，它使用Matcher功能。需要定义空的接受类型集（define_accept_types []）。

elixir
defmodule Dispatcher do
  use Matcher
  define_accept_types []

  ...
end

支持的API

使用Matcher

use Matcher宏用于设置匹配器，它会导入Matcher、send_resp和forward函数。

HTTP方法

支持以下HTTP方法宏：get、put、post、delete、patch、head、options、match。其中match宏匹配所有方法。

参数：

• path：字符串，可包含变量解构
• options：选项哈希，包含匹配条件：
  • accept：通过define_accept_types定义的接受类型简写
  • last_call：设为true时用于fallback路由（如404页面）
• block：处理和发送请求的代码块

提供变量：

• conn：Plug连接对象，用于转发或响应
• path：当路径定义为"/something/*path"时，包含未使用的路径段

define_accept_types

提供一种将Accept类型映射到可读术语的方式，便于一致匹配。接收一个属性数组，描述每个使用的键及其对应的Accept头，支持通配符。

请求转发

基本转发

可将一个路径代理到另一个路径。例如，将/sessions请求转发到http://sessionsservice/login：

elixir
defmodule Dispatcher do
  use Matcher
  define_accept_types []

  match "/sessions", _ do
    forward conn, [], "http://sessionsservice/login"
  end
end

可在代码块中添加额外逻辑，如日志记录：

elixir
defmodule Dispatcher do
  use Matcher
  define_accept_types []

  match "/sessions", _ do
    IO.inspect(conn, label: "conn for /sessions")
    forward conn, [], "http://sessionsservice/login"
  end
end

路径转发

转发子路由，例如将所有/widgets开头的请求转发到mu-cl-resources服务：

elixir
defmodule Dispatcher do
  use Matcher
  define_accept_types []

  match "/widgets/*path", _ do
    forward conn, path, "http://resource/widgets"
  end
end

基于方法匹配

可显式匹配HTTP方法。例如，仅转发POST请求：

elixir
defmodule Dispatcher do
  use Matcher
  define_accept_types []

  post "/sessions", _ do
    forward conn, [], "http://sessionsservice/login"
  end
end

基于主机名匹配

支持基于主机名的分发，支持字符串格式、数组格式和通配符。

匹配特定主机：

elixir
get "/employees", %{ host: "api.redpencil.io" } do
  ...
end

通配符匹配：

elixir
get "/employees", %{ host: "*.redpencil.io" } do
  ...
end

提取子域名：

elixir
get "/employees", %{ host: ["io", "redpencil", subdomain | subsubdomains] } do
  IO.inspect(subdomain, "First subdomain")
  IO.inspect(subsubdomains, "Array of subdomains under subdomain")
  ...
end

基于Accept头匹配

根据客户端请求的MIME类型分发请求。首先通过define_accept_types定义Accept类型简写：

elixir
defmodule Dispatcher do
  use Matcher

  define_accept_types [
    json: ["application/json", "application/vnd.api+json"],
    img: ["image/jpg", "image/jpeg", "image/png"],
    gif: ["image/gif"]
  ]

  get "/images/*path", %{ accept: %{ json: true } } do
    forward conn, path, "http://resource/images"
  end

  get "/images/*path", %{ accept: %{ img: true } } do
    forward conn, path, "http://images/images"
  end

  get "/images/*path", %{ accept: %{ gif: true } } do
    forward conn, path, "http://gifs/images"
  end
end

Fallback路由和404页面

当没有匹配的路由时，应提供404响应。使用last_call: true选项配置fallback路由：

elixir
defmodule Dispatcher do
  use Matcher

  define_accept_types [
    text: ["text/*"],
    html: ["text/html", "application/xhtml+html"],
    json: ["application/json", "application/vnd.api+json"],
    img: ["image/jpg", "image/jpeg", "image/png"],
    gif: ["image/gif"],
    image: ["image/*"]
  ]

  # 其他路由规则...

  get "/*_", %{ last_call: true, accept: %{ json: true } } do
    send_resp(conn, 404, "{ \"error\": { \"code\": 404, \"message\": \"Route not found.  See config/dispatcher.ex\" } }")
  end

  get "/*_", %{ last_call: true, accept: %{ image: true } } do
    forward conn, [], "http://images/404"
  end

  get "/*_", %{ last_call: true, accept: %{ text: true } } do
    send_resp(conn, 404, "404 - page not found\n\nSee config/dispatcher.ex")
  end

  get "/*_", %{ last_call: true, accept: %{ html: true } } do
    send_resp(conn, 404, "<html><head><title>404 - Not Found</title></head><body><h1>404 - Page not found</h1></body></html>")
  end
end

响应处理

可在转发前添加逻辑，如复用配置、日志记录或请求修改：

elixir
defmodule Dispatcher do
  use Matcher

  define_accept_types [
    json: ["application/json", "application/vnd.api+json"]
  ]

  @json %{ accept: %{ json: true } }

  match "/sessions/*path", @json do
    IO.inspect(conn, label: "Connection for sessions service.")
    forward conn, path, "http://sessions/login"
  end

  match "/images/*path", @json do
    forward conn, path, "http://resource/images"
  end

  match "/*_", %{ last_call: true, accept: %{ json: true } } do
    send_resp(conn, 404, "{ \"error\": { \"code\": 404, \"message\": \"Route not found.  See config/dispatcher.ex\" } }")
  end
end

扩展信息

托管EmberJS应用

配置Ember应用路由，优先提供HTML页面，同时处理资产请求：

elixir
defmodule Dispatcher do
  use Matcher

  define_accept_types [
    json: ["application/json", "application/vnd.api+json"],
    html: ["text/html", "application/xhtml+html"],
    any: ["*/*"]
  ]

  @html %{ accept: %{ html: true } }
  @json %{ accept: %{ json: true } }
  @any %{ accept: %{ any: true } }

  # 其他路由规则...

  match "/assets/*path", @any do
    forward conn, path, "http://frontend/assets/"
  end

  match "/*_path", @html do
    forward conn, [], "http://frontend/index.html"
  end

  match "/*_", %{ last_call: true, accept: %{ json: true } } do
    send_resp(conn, 404, "{ \"error\": { \"code\": 404, \"message\": \"Route not found.  See config/dispatcher.ex\" } }")
  end
end

外部API CORS头

处理跨域请求的OPTIONS预检请求：

elixir
defmodule Dispatcher do
  use Matcher
  define_accept_types []

  options "*path", _ do
    conn
    |> Plug.Conn.put_resp_header("access-control-allow-headers", "content-type,accept")
    |> Plug.Conn.put_resp_header("access-control-allow-methods", "*")
    |> send_resp(200, "{ \"message\": \"ok\" }")
  end
end

提供多类型404页面

为不同Accept类型提供404响应：

elixir
defmodule Dispatcher do
  use Matcher

  define_accept_types [
    text: ["text/*"],
    html: ["text/html", "application/xhtml+html"],
    json: ["application/json", "application/vnd.api+json"],
    jpeg: ["image/jpg", "image/jpeg"],
    png: ["image/png"],
    gif: ["image/gif"],
  ]

  # 其他路由规则...

  get "/*_", %{ last_call: true, accept: %{ json: true } } do
    send_resp(conn, 404, "{ \"error\": { \"code\": 404, \"message\": \"Route not found.  See config/dispatcher.ex\" } }")
  end

  get "/*_", %{ last_call: true, accept: %{ text: true } } do
    send_resp(conn, 404, "404 - page not found\n\nSee config/dispatcher.ex")
  end

  get "/*_", %{ last_call: true, accept: %{ html: true } } do
    send_resp(conn, 404, "<html><head><title>404 - Not Found</title></head><body><h1>404 - Page not found</h1></body></html>")
  end

  get "/*_", %{ last_call: true, accept: %{ jpeg: true } } do
    forward conn, [], "http://static/404.jpeg"
  end

  get "/*_", %{ last_call: true, accept: %{ png: true } } do
    forward conn, [], "http://static/404.png"
  end

  get "/*_", %{ last_call: true, accept: %{ gif: true } } do
    forward conn, [], "http://static/404.gif"
  end
end

架构

转发连接

转发功能基于plug_mint_proxy构建，使用Mint库创建高效请求。请求接收基于Cowboy 2，支持HTTP/2。

与Plug集成

https://github.com/elixir-plug/plug%E9%80%9A%E8%BF%87%E8%87%AA%E8%BA%AB%E7%9A%84%E5%8C%B9%E9%85%8D%E5%99%A8%E5%92%8C%E5%88%86%E5%8F%91%E5%99%A8%E5%8C%B9%E9%85%8D%E8%B0%83%E7%94%A8%E3%80%82%E6%9C%AC%E5%BA%93%E5%9C%A8plug_router_dispatcher.ex%E4%B8%AD%E6%8F%90%E4%BE%9B%E4%BA%86%E9%A2%9D%E5%A4%96%E6%94%AF%E6%8C%81%EF%BC%8C%E5%B0%86%E8%AF%B7%E6%B1%82%E5%88%86%E5%8F%91%E5%88%B0%E8%87%AA%E5%AE%9A%E4%B9%89%E5%8C%B9%E9%85%8D%E5%99%A8%E3%80%82

头部操作

Dispatcher支持以下头部操作，通过plug_mint_proxy的操作器配置：

• AddXRewriteUrlHeader：设置x-rewrite-url头，供后端服务获取原始请求信息
• RemoveAcceptEncodingHeader：移除accept_encoding头，因为加密由标识符处理，不应由后端服务处理
• AddVaryHeader：添加vary头，值为"accept, cookie"，确保缓存考虑这些因素

匹配器

Matcher模块包含核心逻辑，解析请求Accept头和定义的接受类型，寻找最佳分发方案。分发流程如下：

1. 解析Accept头
2. 对Accept头的每个分数分组（A）
3. 将（A）与define_accept_types中定义的类型匹配（支持通配符），得到（B）
4. 为每个（B）尝试寻找匹配的路由规则
5. 找到则返回匹配结果
6. 未找到则尝试使用last_call: true选项寻找fallback路由