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

命名规范

  • 服务组名称:只允许使用中英文字符、数字、短划线(-)和下划线(_),不允许有空格。
  • 服务全名:不可以为中文,只能使用数字,字母和短划线(-)。
  • 服务版本:不可以为中文,只能使用数字,字母和英文句号(.)。
  • 服务发布的参数名:只能使用数字,字母和下划线(_)。

协议转换种类

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

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

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

支持的接入协议类型 对应支持的协议开放类型
RESTful RESTful、WebService
SpringCloud RESTful
HSF RESTful、WebService、HSF级联
WebService RESTful、WebService级联
Dubbo RESTful、WebService
JDBC RESTful
  • CSB支持数组、列表、集合类型的服务参数,也可以定义复杂的多级参数结构,其它特别的支持情况,请参见CSB接入规范和限制
  • 在协议转换外,CSB还支持接入接口和开放接口的参数映射、是否可选、缺省值以及在开放接口上是否可见等设置。还将支持定制开发的参数映射机制(Groovy脚本)。
  • CSB暂不支持OAuth 2.0开放标准。

CSB接入规范和限制

开放 > 接入协议对 接入规范和限制明细
RESTful> RESTful
  • 支持GET/PUT/POST/DELETE
  • 参数传递
    • Query:Key-Value形式
    • Body:Key-Value/JSON/byte[]形式
  • 支持RESTful风格的接入,如http://localhost:9090/aaa/{userId}/test
  • 支持HTTP返回结果透传,不做任何变换加工。
RESTful> Dubbo
  • 支持特别指定注册中心或使用默认注册中心。
  • 支持开放一个接口的某个指定方法。
  • 支持Dubbo和Hessian序列化协议。
  • 支持简单数据类型泛型的HashMap。
  • 返回结果固定为JSON格式。
RESTful> WebService
  • 支持两种格式的用户名密码接入SOAP Header。
    • Authorization类型
    • WSSE类型
  • 不支持WSS和Policy等相关的安全和加密处理。
  • 对于anytype参数类型,参数定义时要经过特殊定义为ws:anyType或者java.lang.Object
  • 接入后端WebService服务方法必须是同步的,不支持异步。
  • 支持的bindTypeDocument-Literal (Wrapper or Unwrapper)
  • 返回结果是将SOAP XML转化为JSON格式。
RESTful> HSF 支持开放一个接口某个指定方法。
  • 支持java.util.Map参数。
  • 返回结果固定为JSON格式。
WebService > WebService
  • 支持MTOM等附件数据传输方式的调用。
  • 支持透传式调用后端接入服务。
  • 需要使用CSB提供的WebService Client SDK(目前有Java版本)传递AccessKey和signature等相关Header信息。
WebService > Restful/Dubbo/HSF
  • 相应服务会以SOAP 1.1的格式发布成一个WebService并提供标准的WSDL。
  • 需要使用CSB提供的WebService Client SDK(目前有Java版本)传递AccessKey和signature等相关Header信息。
  • 暂不支持入参的可选和默认值设置。

服务控制

  • 支持具体用户消费凭证到具体服务的访问限流设置。
  • 支持实例级(即服务器级)的总体访问流量保护。
  • 支持实例级(即服务器级)和服务级的基于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://CSB服务地址:8086/CSB

    • CSB服务地址即创建该实例时绑定的SLB的地址。
    • 默认的访问端口为8086
    • 请求的context-path可以任意指定,默认使用CSB
  2. 根据CSB的设计约定,当CSB开放成WebService服务时,对应的WSDL的地址为以下格式:

    • 如果接入是HTTP协议,则开放出的WSDL地址是http://CSB服务地址:9081/$api_name/$api_version/ws2restful?wsdl

      • CSB服务地址即创建该实例时绑定的SLB的地址。
      • $api_name为发布的服务名。
      • $api_version为发布的服务版本。
      • ws2restful为固定值。
    • 如果接入是HSF协议, 则开放出来的WSDL地址是http://CSB服务地址:9081/$api_name/$api_version/$method?wsdl
      • CSB服务地址即创建该实例时绑定的SLB的地址。
      • $api_name为发布的服务名。
      • $api_version为发布的服务版本。
      • $method为发布服务时对应的接入方法名。
    • 如果接入是WS协议(即WS透传), 则开放出来的WSDL地址是http://CSB服务地址:9081/$api_name/$api_version/ws2ws?wsdl
      • CSB服务地址即创建该实例时绑定的SLB的地址。
      • $api_name为发布的服务名。
      • $api_version为发布的服务版本。
      • ws2ws为固定值。

CSB服务的调用返回约定

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

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