全部产品

后端路由

更新时间:2019-08-12 14:26:33

1. 概述

Routing插件具备根据请求的参数取值与系统参数取值,变更后端地址、路径、参数或类型的能力。可以用于租户路由,蓝绿发布,不同环境的区分等场合。

2. 配置方式

2.1 配置模板

可以选择json或者yaml格式的来配置您的插件,两种格式的schema相同,可以搜索yaml to json转换工具来进行配置格式的转换,yaml格式的模板见下表

  1. ---
  2. routes:
  3. # 当调用方的AppId为"123456"时, 路由至独立的地址, 例子中指定了VPC授权名为"slbAddressForVip"的地址
  4. - name: Vip
  5. condition: "$CaAppId = 123456"
  6. backend:
  7. type: "HTTP-VPC"
  8. vpcAccessName: "slbAccessForVip"
  9. # 针对太老的客户端, 返回不再支持的应答, ClientVersion是API中的自定义参数
  10. - name: MockForOldClient
  11. condition: "$ClientVersion < '2.0.5'"
  12. backend:
  13. type: "MOCK"
  14. statusCode: 400
  15. mockBody: "This version is not supported!!!"
  16. # 蓝绿发布场景: 将5%的请求路由给蓝绿发布后端
  17. - name: BlueGreenPercent05
  18. condition: "Random() < 0.05"
  19. backend:
  20. type: "HTTP"
  21. address: "https://beta-version.api.foo.com"
  22. constant-parameters:
  23. - name: x-route-blue-green
  24. location: header
  25. value: "route-blue-green"

配置模板的根对象为routes,包含多个route对象,每个route对象用于指定一条路由,每条路由以下几个部分组成

  • name: 表示这个路由的名称,大小写英文字母和数字,在每个插件中保持唯一,如果命中了这条路由,后端收到的请求会包含一个名为X-Ca-Routing-Name的HTTP头,指示本次命中的路由名称
  • condition:路由的条件表达式,条件表达式的规范见本文2.2节中的描述,如果当前的请求符合条件表达式,则本条路由命中,Routing插件会按照插件的配置顺序从上到下进行判断,并将请求路由给命中的第一条记录,并忽略后面的记录,如果您配置了多条路由记录,请仔细检查配置的顺序与您期望的逻辑一致。
  • backend: 后端描述,与API网关的Swagger标准保持一致,请参考[],后端在原有API的后端上覆盖backend配置后处理,如果覆盖后的backend不完整,会提示客户端X-Ca-Error-Code: I504RB,当看到这个错误时,请检查自己的backend配置是否完整,关于Backend描述,请参照2.3节,Routing插件中的Backend覆盖规则
  • constant-parameters: 可以自行设置路由的常量参数,常量参数会附加在命中路由的后端请求上,用于后端的业务逻辑处理,location支持headerquery

2.2. Condition条件表达式

2.2.1 基本语法

  • Condition表达式与SQL表达式类似,基础表达形式为$A = 'A' and '$B = 'B'
  • 参数以$开头,可以引用在API中定义的参数(API为映射与透传方式均可),如果您在API中定义了名为query1的参数,则$query1可以表示当前请求中的query1参数s
  • 支持以下常量类型:
    • STRING: 字符串类型,支持单引号或双引号,如: “Hello”
    • INTEGER: 整数类型,如: 1001,-1
    • NUMBER: 浮点数类型,如: 0.1, 100.0
    • BOOLEAN: 布尔类型,如: true、false
  • 可以使用andor来连接不同的表达式
  • 可以用小括号()来指定条件判断的优先级
  • Random()作为内置函数,可以产生一个0-1NUMBER浮点类型参数,用于随机的判断
  • 可以使用 $CaAppId 形式来引用当前请求的系统参数,系统参数不需要API中被定义即可引用,但如果您在API中定义了重名的参数,取到的值会被自定义参数覆盖,可用于路由插件的系统参数列表如下:
    • CaStage: 当前API请求的环境, RELEASE,PRE,TEST
    • CaDomain: 当前请求的域名
    • CaRequestHandleTime:请求处理的UTC时间
    • CaAppId:请求参数的AppId
    • CaAppKey:请求参数的AppKey
    • CaClientIp:客户端IP
    • CaApiName:创建时候的API名字
    • CaHttpScheme:请求的协议HTTP,HTTPS,WS
    • CaClientUa: 客户端上传的UserAgent字段
  • 如果表达式中使用了不存在的参数, 如$UnknonwParameter = 1,则表达式的判断会返回false

2.2.3 条件表达式样例

  • 5%的几率为真

    Random() < 0.05

  • 当前API请求的是测试环境

    $CaStage = 'TEST'

  • 自定义参数中的UserName是Admin且来源IP是47.47.74.77

    $UserName = 'Admin' and $CaClientIp = '47.47.74.77'

  • 当前请求的用户Id是1001,1098,2011中的一个,且使用HTTPS协议请求

    $CaHttpScheme = 'HTTPS' and ($CaAppId = 1001 or $CaAppId = 1098 or $CaAppId = 2011)

2.3. Backend的定义与覆盖规则

Backend的结构与API网关导入Swagger时的结构一致,详细请参考文档通过导入Swagger创建API,目前支持的后端类型及配置样例如下,如果插件中不需要变更后端类型,只需要变更部分设置,则不需要填写完整的字段,仅填写需要变更的即可。

  • HTTP
  1. ---
  2. backend:
  3. type: HTTP
  4. address: "http://10.10.100.2:8000"
  5. path: "/users/{userId}"
  6. method: GET
  7. timeout: 7000
  • HTTP-VPC
  1. ---
  2. backend:
  3. type: HTTP-VPC
  4. vpcAccessName: vpcAccess1
  5. path: "/users/{userId}"
  6. method: GET
  7. timeout: 10000
  • FC
  1. ---
  2. backend:
  3. type: FC
  4. fcRegion: cn-shanghai
  5. serviceName: fcService
  6. functionName: fcFunction
  7. arn: "acs:ram::111111111:role/aliyunapigatewayaccessingfcrole"
  • MOCK
  1. ---
  2. backend:
  3. type: MOCK
  4. mockResult: "mock resul sample"
  5. mockStatusCode: 200
  6. mockHeaders:
  7. - name: server
  8. value: mock
  9. - name: proxy
  10. value: GW

2.4. 限制

  • 插件的文本大小限制为16384字节,超过后会报错InvalidPluginData.TooLarge
  • 单个Routing插件的条数限制为16条,超过后会报错InvalidPluginData.TooManyRoutes
  • 单条Condition语句的大小限制为512字节,超过后会报错InvalidPluginData.ConditionTooLong
  • 插件更新会实时生效至所有已绑定该插件的API,插件的更新频率被限制为45秒一次,超出时会报错,InvalidPluginData.UpdateTooBusy

3. 典型应用场景

3.1. 配置租户路由(根据AppId分配不同的后端地址)

AppId为10098,10099的用户是我的VIP用户,我希望来自这两个用户的请求路由到独立的服务器集群去,

  1. ---
  2. routes:
  3. # 当调用方的AppId为10098或10099时, 路由至独立的地址,
  4. # 例子中指定了VPC授权名为"slbAddressForVip"的地址
  5. - name: Vip
  6. condition: "$CaAppId = 10098 or $CaAppId = 10099"
  7. backend:
  8. type: "HTTP-VPC"
  9. vpcAccessName: "slbAccessForVip"

3.2. Stage路由(测试/预发/生产环境变更)

我的正式环境在阿里云的VPC中,但我希望将所有访问测试环境的API指向我的公网测试服务器

  1. ---
  2. routes:
  3. # 当访问测试环境时, 将路由转向我的公网服务器
  4. - name: Vip
  5. condition: "$CaStage = 'TEST'"
  6. backend:
  7. type: "HTTP"
  8. address: "https://test-env.foo.com"

3.3. 蓝绿发布

我准备将5%的流量指向一组beta服务器地址,进行蓝绿发布

  1. ---
  2. routes:
  3. # 蓝绿发布场景: 将5%的请求路由给蓝绿发布后端
  4. - name: BlueGreenPercent05
  5. condition: "Random() < 0.05"
  6. backend:
  7. type: "HTTP"
  8. address: "https://beta-version.api.foo.com"