semtech/mu-dispatcher Docker Image Overview

semtech/mu-dispatcher

自动构建

semtech

用于将请求分发到首选微服务的核心微服务，是mu.semte.ch架构的核心元素之一，可根据请求路径将请求路由到其他微服务，需通过/config/dispatcher.ex配置。

3 次收藏下载次数: 0状态：自动构建维护者：semtech仓库类型：镜像最近更新：14 天前

轩辕镜像，不浪费每一次拉取。点击查看

中文简介版本下载

轩辕镜像，不浪费每一次拉取。点击查看

mu-dispatcher

镜像概述和主要用途

mu-dispatcher是mu.semte.ch架构中的核心元素之一。该服务根据传入请求的路径将请求分发到其他微服务。您可以通过Docker运行该服务，但通常建议使用mu-project进行配置，以应用自定义设置。

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

核心功能和特性

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

使用场景和适用范围

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

详细使用方法和配置说明

配置

Dispatcher通过mu-project中的dispatcher.ex文件进行配置。

基本（默认）配置是一个名为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请求转发到[***]：

elixir
defmodule Dispatcher do
  use Matcher
  define_accept_types []

  match "/sessions", _ do
    forward conn, [], "[***]"
  end
end

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

elixir
defmodule Dispatcher do
  use Matcher
  define_accept_types []

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

路径转发

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

elixir
defmodule Dispatcher do
  use Matcher
  define_accept_types []

  match "/widgets/*path", _ do
    forward conn, path, "[***]"
  end
end

基于方法匹配

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

elixir
defmodule Dispatcher do
  use Matcher
  define_accept_types []

  post "/sessions", _ do
    forward conn, [], "[***]"
  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, "[***]"
  end

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

  get "/images/*path", %{ accept: %{ gif: true } } do
    forward conn, path, "[***]"
  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, [], "[***]"
  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, "[***]"
  end

  match "/images/*path", @json do
    forward conn, path, "[***]"
  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, "[***]"
  end

  match "/*_path", @html do
    forward conn, [], "[***]"
  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, [], "[***]"
  end

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

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