dgate：an API Gateway based on Vert.x

头像
DTeam
    阅读 9 分钟
    1

    dgate：an API Gateway based on Vert.x

    dgate是基于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采用ConfigSlurper解析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.jceks
export dgate_key_type=jceks
export 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.HttpMethod
import io.vertx.core.Vertx
import io.vertx.ext.auth.jwt.JWTAuth
import 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，字符串，如 “http://localhost:7000”。
    • 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]]
    ]
}
……
    groovyjavavert.x微服务开源项目介绍
    DTeam
    391 声望89 粉丝

    邮件：jian.hu@shifudao.com

    下一篇 »
    JWT必知必会

    引用和评论

    推荐阅读
    头像
    Nginx SSL快速双向认证配置(脚本)

    DTeam赞 9阅读 8.6k

    头像
    Bitmap 和 布隆过滤器傻傻分不清？你这不应该啊

    程序员小富赞 10阅读 4.6k评论 1

    头像
    Jerry和您聊聊Chrome开发者工具

    注销赞 9阅读 4.8k评论 3

    头像
    Spring 实现 3 种异步流式接口，干掉接口超时烦恼

    程序员小富赞 6阅读 2.4k

    头像
    💢线上高延迟请求排查

    crossoverJie赞 6阅读 3.9k评论 5

    头像
    Spring Boot起步，CRUD、错误处理与宝塔部署

    微芒不朽赞 3阅读 3.8k

    头像
    前端微服务跨域配置解决办法，devServer为例

    smallStone赞 7阅读 6.9k评论 29

    0 条评论
    得票最新