全部产品
阿里云办公

约束规范

更新时间:2017-11-16 10:42:50

简介

服务发布规范定义了服务发布中的命名规则、协议选择和映射关系,以及其他的一些规范信息。

命名规范

  • 服务组名称:允许使用中英文字符、数字及”-“,”_”。不允许有空格
  • 服务全名:不可以为中文,只能使用数字,字母或“-”
  • 服务版本:不可以为中文, 只能使用数字,字母或“.”
  • 服务发布的参数名:只能使用数字,字母或“_”

协议转换种类

CSB 支持常用协议服务的接入和开放(HTTP/HSF/Dubbo/Web Service),可扩展支持定制化的协议转换。

  • 服务接入:在 CSB 上注册某个服务并且提供足够的信息让 CSB 可以访问这个已有的服务。
  • 服务开放:把一个已接入的服务在某个 CSB 上提供对应的不同协议的 API 调用入口。

缺省支持的服务接入、开放协议如下表所示:

支持的接入协议类型 对应支持的协议开放类型
HTTP Restful API、HTTP Open API、Web Service
HSF HTTP Open API、Web Service、HSF 级联
Dubbo HTTP Open API、Web Service
Web Service HTTP Open API、Web Service 级联
  • CSB 支持数组、列表、集合类型的服务参数,也可以定义复杂的多级参数结构,其它特别的支持情况请参考下面的 CSB接入规范/限制 部分。
  • 在协议转换外,CSB 还支持接入接口和开放接口的参数映射、是否可选、缺省值以及在开放接口上是否可见的设置。还将支持定制开发的参数映射机制(Groovy 脚本)。
  • CSB 暂不支持 OAuth 2.0 开放标准。
  • CSB 接入规范/限制如下表所示:
开放 > 接入协议对 接入规范/限制明细
HTTP > HTTP
  1. 支持 GET/PUT/POST/DELETE
  2. 参数传递
    1. Query:Key-Value 形式
    2. Body:Key-Value/JSON/byte[] 形式
  3. 支持 RESTful 风格的接入,如:http://localhost:9090/aaa/{userId}/test
  4. 支持 HTTP 返回结果透传,不做任何变换加工
HTTP > Dubbo
  1. 支持特别指定注册中心或使用默认注册中心
  2. 支持开放一个接口某个指定方法
  3. 支持 Dubbo 和 Hessian 序列化协议
  4. 支持简单数据类型泛型的HashMap
  5. 返回结果固定为 JSON 格式
HTTP > Web Service
  1. 支持两种格式的用户名密码接入 SOAP Header
    1. Authorization 类型
    2. WSSE 类型
  2. 不支持 WSS 和 Policy 等相关的安全和加密处理
  3. 对于 anytype 参数类型,参数定义时要经过特殊定义为“ws:anyType” 或者 “java.lang.Object”
  4. 接入后端 WS 服务方法必须是同步的,不支持异步
  5. 支持的 bindType 是 Document-Literal (Wrapper or Unwrapper)
  6. 返回结果是将 SOAP XML 转化为 JSON 格式
Web Service > Web Service
  1. 支持 MTOM 等附件数据传输方式的调用
  2. 支持透传式调用后端接入服务
  3. 需要使用 CSB 提供的 WS Client SDK(目前有 Java 版本)传递 Accesskey 和 signature 等相关 Header 信息。
Web Service > HTTP/HSF
  1. 相应服务会以 SOAP 1.1的格式发布成一个 Web Service 并提供标准的 WSDL。
  2. 需要使用 CSB 提供的 WS Client SDK(目前有 Java 版本)传递 Accesskey 和 signature 等相关 Header 信息。
  3. 暂不支持入参的可选和默认值设置。

服务控制

  • 支持具体用户消费凭证到具体服务的访问限流设置。
  • 支持实例级(即服务器级)的总体访问流量保护。
  • 支持实例级(即服务器级)和服务级的基于IP的黑白名单设置。

服务发布

提供版本管理和基本的服务(API)组织管理,支持跨 CSB 实例联动发布。

  • API 服务发布的接入和开放协议,缺省支持的情况请参考“协议转换”部分的协议类型支持列表
  • 支持 API 服务分组,用以实现对所发布服务的基本组织分类。
  • 支持 API 服务多版本,可指定变更当前的激活版本。
  • 支持 API 服务的启用、停用、注销、定义变更等基本生命周期管理。
  • 支持 API 服务基于 IP 的黑白名单设置。
  • 支持指定 API 服务每秒最大调用量。
  • 支持指定无需授权审批,申请即可自动授权的自由调用模式。
  • 支持基于路由选择的服务发布,可以根据接入参数的取值不同决定接入的实际协议或地址。
  • 支持 API 服务的级联发布,即可以在一个 CSB 实例上接入服务,可能途径其它中间 CSB 实例,然后在另一个目标 CSB 实例上开放出来,消费方应用直接访问目标 CSB 实例即可。
  • 支持对已发布 API 服务的级联扩展,例如在 A 实例接入 B 实例开放的 API,可以再次指定在实例 C 上开放,服务级联链路按规则自动适配。

CSB 发布的服务的端口说明

  1. CSB 发布出的 Restful 服务的访问地址访问格式: http://broker-vip:8086/CSB

    • broker-vip 是 CSB-Broker 的前置 SLB 地址或者具体的一个 broker 的地址(当没有前置的 SLB 或者 Proxy)
    • 默认的访问端口为 “8086”
    • 请求的 context-path 可以任意指定,默认使用“CSB”
  2. 根据 CSB 的设计约定,当 CSB 开放成 WebService 服务时,对应的 WSDL 的地址为如下格式:

    • 如果接入是 HTTP 协议,则开放出的 WSDL 地址是:
      1. http://broker-vip:9081/$api_name/$api_version/ws2restful?wsdl
      2. $api_name 为发布的服务名; $api_version 为发布的服务版本; "ws2restful"为固定值。
    • 如果接入是 HSF 协议, 则开放出来的 WSDL 地址是:
      1. http://broker-vip:9081/$api_name/$api_version/$method?wsdl
      2. $api_name 为发布的服务名; $api_version 为发布的服务版本; $method 为发布服务时对应的接入方法名。
    • 如果接入是 WS 协议(即WS透传), 则开放出来的 WSDL 地址是:
      1. http://broker-vip:9081/$api_name/$api_version/ws2ws?wsdl
      2. $api_name 为发布的服务名; $api_version 为发布的服务版本; "ws2ws"为固定值。

CSB服务的调用返回约定

调用由 CSB 发布的 HTTP 服务时,如果发生调用错误,则默认返回回值是一个如下的 JSON 格式:

  1. {
  2. "code":500,
  3. "message":"[503]service not registed, key is : _api_PING_null_null_vcsb",
  4. "requestId":"1e1eb5d215059677158731001d3d47"
  5. }