路由機制
配置鏈接URL到Erlang模塊(處理對應請求的模塊)的映射就是路由腺阳。
當 Cowboy接收到一個請求時沽一,它會嘗試在給定的分發(fā)規(guī)則中匹配 域名 到對應的資源路徑。如果匹配成功帆阳,那么對應的Erlang 模塊就會被執(zhí)行嗤形。
Cowboy首先會匹配域名,接著嘗試找到匹配的資源路徑岛啸。
Cowboy會將路由規(guī)則編譯后钓觉,再使用。
結構
通用的路由結構是這樣定義的:
Routes= [Host1, Host2, ... HostN].
每一個域名的匹配規(guī)則 包含了 對連接路徑的選項約束和路徑部件的列表坚踩。
Host1= {HostMatch, PathsList}.
Host2= {HostMatch, Constraints, PathsList}.
路徑部件的定義如下:
PathsList= [Path1, Path2, ... PathN].
最后荡灾,每一路徑包含了該路徑自身的匹配規(guī)則以及對應的處理模塊
Path1= {PathMatch, Handler, Opts}.
Path2= {PathMatch, Constraints, Handler, Opts}.
匹配規(guī)則語法
匹配語法規(guī)則用于標識 域名到路徑間的處理handlers。
域名的語法規(guī)則:
HostMatch1= "cowboy.example.org".
HostMatch2= "cowboy.example.org.".
HostMatch3= ".cowboy.example.org".
路徑的語法規(guī)則:
PathMatch= "/hats/:name/prices".
HostMatch= ":subdomain.example.org".
此外,還可以將域名的某一字段保存到Req對象中批幌,再后續(xù)可以使用础锐,這就是值綁定。
PathMatch= "/hats/:name/prices".
HostMatch= ":subdomain.example.org".
比如荧缘,http://test.example.org/hats/wild_cowboy_legendary/prices 將會
把test綁定到subdomain皆警,而wild_cowboy_legendary就會綁定到name,它們可以被cow_req:binding/{2,3}中檢索截粗,綁定的名字必須是一個atom
'_':表示匹配任何內容
約束
匹配域名和路徑完成后信姓,就會檢測是否滿足可選的約束,約束如下:
{Name, function, fun ((Value) -> true | {true, NewValue} | false)}```
int 約束將會檢查 綁定的二進制串是一個int绸罗,或可被轉化成一個int
function約束意推,將會調用給定的約束函數并且返回結果,給定函數必須自己保證不會崩潰的珊蟀。
為了保存Cowboy可以更高效地查找正確的handler模塊菊值,Cowboy會編譯定義好的路由分發(fā)規(guī)則。
編譯的方法是:```cowboy_router:compile/1```
```erlang
Dispatch= cowboy_router:compile([
%% {HostMatch, list({PathMatch, Handler, Opts})}
{'_', [{'_', my_handler, []}]}]),
%% Name, NbAcceptors, TransOpts, ProtoOpts
cowboy:start_http(my_http_listener, 100, [{port, 8080}], [{env, [{dispatch, Dispatch}]}]
).
如果定義好的路由分發(fā)規(guī)則有錯誤育灸,cowboy_router:compile/1
將會返回{error, badarg}
在線更新路由規(guī)則
通過 cowboy:set_env/3
更新路由的分發(fā)規(guī)則腻窒,連接監(jiān)聽模塊接受新的連接時就會使用新的路由分發(fā)規(guī)則。
cowboy:set_env(my_http_listener, dispatch, cowboy_router:compile(Dispatch)).