dgate：an API Gateway based on Vert.x
是基于Vertx的API Gateway。运行dgate的命令如下：
java -jar dgate-version-fat.jar -Dconf=conf
其中的conf属性用来指定运行所需的配置文件。
conf的文件格式
在说明格式之前，先看一个例子：
apiGateway1 { port = 7000 login = "/login" urls { "/login" { required = ["sub", "password"] methods = [HttpMethod.GET, HttpMethod.POST] upstreamURLs = [ [ host: 'localhost', port: 8080, url: '/login', after: { simpleResponse -> Map payload = [ sub: simpleResponse.payload.getString("sub"), name: simpleResponse.payload.getString("name"), role: simpleResponse.payload.getString("role") ] simpleResponse.payload.put('token', delegate.tokenGenerator.token(payload, 5)) simpleResponse } ] ] } "/summary" { expected { statusCode = 200 payload { eqLocations = [] opRateInLast30Days = [] myOrgs = [ ["name": "org1", "admin": false] ] } } } "/forward" { required = ['param1', 'param2'] methods = ['GET', 'POST'] upstreamURLs = [ [host: 'localhost', port: 8080, url: '/test'] ] } "/composite" { required = ['param1', 'param2'] methods = ['GET', 'POST'] upstreamURLs = [ [host: 'localhost', port: 8080, url: '/test1'], [host: 'localhost', port: 8080, url: '/test2'] ] } }}apiGateway2 { port = 7001 host = 'localhost' urls { "/mock" { expected { statusCode = 200 payload = [test: true] } } }} dgate采用解析conf文件，因此其文件的语法实际上是Groovy语法。
conf文件由多个Api Gateway的定义组成，对于每个Gateway定义如下：
apiGatewayName { port //端口 host //绑定的ip或主机名,默认0.0.0.0 login //后端login服务的配置 urls { URL配置（UrlConfig）列表 } //dgate暴露的url列表} 对于每个URL配置，其结构如下：
url { required //必需参数列表 methods //支持的HTTP Method upstreamURLs { 上游URL列表（UpStreamURL） } expected //期望返回值} 其中：
-
required支持两种格式：List和Map。前者适用于不区分HttpMethod时的参数验证，后者则可以针对不同的HttpMethod分别进行设置。
- List，如：required = ["sub", "password"]
- Map，如：required = [get: ['param1'], post: ['param2'], delete: ['param3']]
- expected和upStreamURLs两个属性不能并存
- expected主要用于mock模式，其目的是为了便于依赖dgate的访问层可以自行mock所需的响应，使得它们的开发进度受dgate开发进度的影响最小化。
-
对于expected的内容：
- statusCode和payload至少有一个
- 或针对具体的HTTP METHOD的返回值
- 对于每个上游URL，有3个属性：host、port和url，其中url必需以"/"开始
不同类型的API Gateway请求
API Gateway的目的是作为后端Service的一个统一集中点，简化访问层与后端Service的交互。说得更简单点，其作用非常类似Facade。
因此，API Gateway的主要作用就是：
- 接受访问层的请求
- 将请求转发到对应的后端服务
- 收集后端响应，统一组装成response，然后返回给访问层
从大的方面讲，发给API Gateway的请求分成两类：
- 转发给一个上游URL，即上面的forward
- 转发给多个上游URL，即上面的Composite
这便是为何upStreamURLs是一个列表的主要原因。对于每种请求：
-
forward
- 访问层的request parameter直接转发给后端service
- 后端service的response直接转发给访问层
-
composite
- 访问层的request parameter会直接（并发）转发给每个后端服务
- 后端服务的response会merge在一起后再发给访问层
对于每个发往后端的请求，dgate会采用Circuit Breaker来防护，防止出现由于某个后端service的失效导致整个系统雪崩。同时，为了简单起见，dgate和后端service之间只通过JSON进行交互：
- 对于发往dgate的请求，dgate会将：request parameters、form变量、request body合并为一体，统一作为request body发往后端
- 对于后端响应，dgate只接受json格式
UpStreamURL的扩展点
如上节所说，API Gateway具备两个职责：转发请求和转发响应。由于每个后端服务所需的request参数和产生的response不同，在这两个阶段，都需要对访问层传来的request和后端服务传回的response进行定制：
- 需要将访问层的request适配成后端service所需的request，这就面临着一些格式转换，如参数改名、增减对应的参数等。
- 需要对后端服务的response适配成访问层所需的response，采用类似的格式转换的动作。
针对这个需求，每个UpStreamURL都有两个可选属性可以利用。
before闭包
upstreamURLs = [ [ host: 'localhost', port: 8080, url: '/test', before: { params -> ... } ]] before闭包的参数为访问层所发来的request parameters，其类型是一个JsonObject。开发者可以通过调用相关的方法来对其内容进行增减，dgate会将before闭包的返回值作为参数发给对应的上游URL。故，在此处非常适合将多余的request params过滤掉。
请注意：before闭包的返回值必需是JsonObject。最简单的before闭包如下：
before: { params -> params } after闭包
upstreamURLs = [ [ host: 'localhost', port: 8080, url: '/test', after: { simpleResponse -> ... } ]] after闭包的参数为后端服务所发来的response,其类型是SimpleResponse。开发者可以利用相关方法来自定义其内容，dgate会将after闭包的返回值作为最终结果与其他后端服务的响应合并，然后返回给访问层。故，此处适合对响应进行自定义。
请注意：after闭包的返回值必需是SimpleResponse。最简单的after闭包如下：
after: { simpleResponse -> simpleResponse } 给before/after闭包传入工具类
由于Groovy闭包的特性，我们可以给before/after传入工具类实例，供开发者使用。典型的例子如下：
"/login" { required = ["sub", "password"] methods = [HttpMethod.GET, HttpMethod.POST] upstreamURLs = [ [ host: 'localhost', port: 8080, url: '/login', after: { simpleResponse -> simpleResponse.put(tokenGenerator.token(["sub": "13572209183", "name": "foxgem", "role": "normal"], 2)) simpleResponse } ] ]} 其中的tokenGenerator就是利用这个特性完成的，具体实现可以参见LoginHandler。注意，上述代码中的2表示token的超时时间，单位为秒。
url path parameters
UpStreamURL除了支持一般的url格式，还支持url path parameters，格式如下：
- '/:x'
- '/y/:x?'
- '/:x?/test/:y?'
所有的参数以":"开始，以"?"结束的为可选参数，规定如下：
- 当url中有且仅有一个可选参数时，它必需为最后一个参数
-
当url中有多个可选参数时，则只能从后向前不出现在url中，即：对于/:x?/:y?/:z?
- /x/y/z，合法
- /x/y，合法
- /x，合法
- /x/z，非法，它将解析对应成：/x/y
Mock请求
最简单的mock请求的书写如下：
"/mock" { expected { statusCode = 200 payload = [test: true] }} 若statusCode或payload本身是一个闭包，则dgate会将它们的返回值作为结果返回，这在excepted为一个动态值时非常有用，参见下面【Mock JWT Token】的例子。
上面的形式对于任何Http Method不加区分地返回同一个内容。但在Restful URL中，往往会有一个URL要为不同的Http Method服务，执行不同动作（如CRUD），返回不同响应体的情形。在dgate中可以以如下形式书写：
"/mock" { expected { get { statusCode = 200 payload = [method: 'get'] } post { statusCode = 200 payload = [method: 'post'] } delete { statusCode = 200 payload = [method: 'delete'] } }} 即对于每一种HTTP method，都有各自响应体，每个响应体的格式都是由statusCode和payload组成。
安全
dgate支持JWT Token来认证每个访问层请求，当配置中出现login时，安全机制即被触发。
Login的配置
若conf中没有login配置，则所有url都是公共可访问的。
若要对所有url都要求先登录，则配置如下：
login = "/login"
若要忽略某些url，则配置如下：
login { url = "/login" ignore = [ 被忽略的url ]} 若只有部分url是需要访问控制的，则配置如下：
login { url = "/login" only = [ 被控制的url ]} 注意：ignore和only不能同时存在。
JWT Token
dgate使用JWT Token来认证每个访问层请求，故每个请求必需先请求获得jwt token，然后将每个token放入后续每个request的"Authorization"头，这样每个后续的request才会被认为是有效请求，否则将返回401。
如何产生jwt token的职责由开发者来完成，它必需放入login配置部分，上面的例子给出了一个参考实现。
对于发往后端服务的每个请求，dgate会将前端请求Authorization头中的jwt token附到请求的参数内，可以通过token来获取，此时它已经被解码成一个JSON对象。
产生JWT Token的密钥由下面的三个环境变量决定，故一旦配置中包含login，则需要在启动dgate之前先设置这3个环境变量：
- dgate_key_store，keystore文件路径
- dgate_key_type，keystore文件类型
- dgate_key_password，keystore的密钥，至少6位
下面是一个配置的例子
export dgate_key_store=./test1.jceksexport dgate_key_type=jceksexport dgate_key_password=test123
使用keytool来产生文件，例子如下：
keytool -genseckey -keystore test1.jceks -storetype jceks -storepass test123 -keyalg HMacSHA256 -keysize 2048 -alias HS256 -keypass test123
由于dgate利用Vert.x的JWTAuthProvider产生JWT Token，因此其密钥文件为符合其要求的文件格式。关于密钥和如何产生密钥文件的命令，可以参见。
注意：
- 在产品环境中请安全地保管好这个密钥文件！
- 在开发环境可以使用dgate自带的测试密钥文件：dgate，密码为“dcloud”。请注意不要将其用于产品环境，否则为伪造证书提供了便利。
Mock JWT Token
对于使用Mock功能来进行开发的访问层，有时会需要mock login来获得mock的jwt token以便开发相应的功能。可以参考下面的代码：
import io.vertx.core.http.HttpMethodimport io.vertx.core.Vertximport io.vertx.ext.auth.jwt.JWTAuthimport top.dteam.dgate.utils.*apiGateway { port = 7000 login = "/login" urls { "/login" { required = ["sub", "password"] methods = [HttpMethod.GET, HttpMethod.POST] expected { statusCode = 200 payload = { JWTAuth jwtAuth = Utils.createAuthProvider(Vertx.vertx()) JWTTokenGenerator tokenGenerator = new JWTTokenGenerator(jwtAuth) [token: tokenGenerator.token(["sub": "13572209183", "name": "foxgem", "role": "normal"], 200)] } } } ……} 既然login指向的是dgate暴露的url，那么当然也就是可以直接mock啦。
注意：不要忘记payload本身是一个闭包！否则，无法模拟JWT Token过期后重新生成另一个Token的情况。
刷新JWT Token
dgate支持JWT Token的刷新，刷新用的url为：/token-refresh。它会从Request Header中取出JWT，解码，然后重新生成新的JWT。即，刷新JWT Token的前提是必须先获得dgate的JWT Token。
刷新JWT Token的配置由login配置块决定。当login是一个url时，则使用缺省的刷新属性。刷新属性（单位：秒）包括：
- refreshLimit，刷新时限，即对于一个超时的JWT Token，若距离当前时间小于这个值，则允许刷新。否则返回401。
- refreshExpire，新生成的JWT Token的时限，一旦超过，则对应的JWT Token失效。
若要自定义这两个值，则可按照如下定义：
login { …… refreshLimit = 30 * 60 refreshExpire = 30 * 60 ……} 若不指定，则使用缺省值。这两个值的缺省值都为：30分钟，即：30 * 60（秒）。
CORS支持
对于某些情况下，需要打开CORS支持才能让访问层正常使用。在dgate中需要在apiGateway中添加如下的配置：
apiGateway { …… cors { allowedOriginPattern = "*" allowedMethods = [HttpMethod.GET, HttpMethod.POST, HttpMethod.DELETE] allowedHeaders = ['content-type'] allowCredentials = true } ……} cors配置并非必需的，若没有，dgate不会支持CORS。CORS的配置项目如下：
- allowedOriginPattern，字符串，如 “”。
- allowedHeaders，字符串集合，支持的HTTP请求HEADER集合
- allowedMethods，Vertx的HttpMethod集合，支持的HTTP方法集合
- exposedHeaders，字符串集合，允许暴露的响应头集合
- maxAgeSeconds，整型，可用于缓存preflight的时间，单位（秒）
- allowCredentials，是否允许Cookie
其中仅allowedOriginPattern是必填。但，对于提交格式为JSON的ajax请求，需要允许：'content-type'。
此外，在调试过程中，也可以注意浏览器给出的提示，根据相应提示进行配置。
警告：在产品环境中不要使用“*”作为allowedOriginPattern的值。
每个请求的附加参数
dgate会给每个发往后端服务的请求参数中添加若干参数，通过下面的key可以获得：
- nameOfApiGateway，Api Gateway的名字，字符串。
- token，已解码的jwt token，其类型是一个Map，内容依赖于在产生token时设置的值。如：在产生时包含[sub, name, role]这几个键值，则此处就获得这3个键值。若在产生时为[sub, name, role, other]，则此处就可以会有这4个键值。
注意：除了必需的几个属性，JWT Token中token本身是可以附加其他属性进来的。相当于将token本身作为信息的载体。
断路器设置
dgate缺省会为每个上游服务（注：对于Mock服务，断路器设置无效）设置一个断路器，缺省的配置如下：
- 最大失败次数（maxFailures），3次
- 请求超时（timeout），5秒
- 断路器重置时间（resetTimeout），10秒
若缺省的设置不合适，dgate支持两个层次的设置：gateway级别和上游服务级别。并且，在两者都存在时，上游服务的断路器设置会覆盖gateway级别的设置。
gateway级别的设置
这个设置将对gateway内所有的上游服务生效，例子如下：
apiGateway { …… circuitBreaker { maxFailures = 5 timeout = 10000 resetTimeout = 30000 } ……} 上游服务级别的设置
这个设置仅对当前上游服务生效，例子如下：
……"/url" { upstreamURLs = [ [host: 'localhost', port: 8080, url: '/test1', circuitBreaker: [maxFailures: 2, timeout: 3000, resetTimeout: 3000]] ]}……